Prevent low-contrast background combinations

[slifty]

Is your feature request related to a problem? Please describe.

I really value authorship colors, but sometimes a color is dark enough that it makes it hard to read the text. I can't change another user's colors, so I'm left in a tough spot. I checked against WCAG standards and indeed they can fail.

Describe the solution you'd like

Ideally we could (1) constrain the valid colors so that they are only WCAG-allowed combinations.

A second solution which would be helpful for other use cases would be to (2) allow a user to create a "local" color override for a given user, so I can define their color regardless of what they have picked.

Describe alternatives you've considered

Within the current feature set I believe I could either disable authorship colors for myself, or clear the authorship color for the text I want to read, which of course impacts everybody.

Additional context

For example:

Plugin?

I don't think this would make sense as a plugin.

[JohnMcLear]

I'm +1 this.

Side quest: How would this work w/ ep_font_colors?

[ferrlen]

Fix proposal: add an outline color to text with poor contrast

maybe whenever adding colors/background-colors to some text in ace this issue could be solved by checking the text element's contrast ratio and then, instead of changing colors, adding a CSS rule -webkit-text-stroke: var(--contrast-color) to the element with poor color contrast ratio. The custom property contrast-color could be black or white, depending on its own contrast with the elements color.

it would produce something like this:

instead of this:

So, in pseudoish-code:

<script>
// whenever adding or removing color (e.g. via the ep_font_color plugin), run this code to add or remove outline

// if an element is detected with poor contrast
poorContrastElement.classList.add("poor-contrast");

// check contrast between element's color and a white outline color 
const goodContrast  = checkContrast("#FFF", window.getComputedStyle(poorContrastElement).color);

if (goodContrast) poorContrastElement.classList.add("white-outline-color");
else poorContrastElement.classList.add("black-outline-color");
</script>

<style>
.poor-contrast {
  -webkit-text-stroke-width: 0.5px;
}

.white-outline-color {
  -webkit-text-stroke-color: white;
}

.black-outline-color {
  -webkit-text-stroke-color: black;
}}
</style>

Advantage of this proposal:

Colors and background colors don't need to be changed. So if a user with red color paints a text red, the background author color won't conflict with the text color, and neither colors need to change.

example of working code to get contrast

/* This uses the standard WCAG contrast formula. A ratio of:

4.5+ is good for normal text
3+ is acceptable for large text
*/

function getContrastRatio(el) {
const style = getComputedStyle(el);

function parseRGB(rgb) {
return rgb.match(/\d+/g).map(Number).map(v => {
v /= 255;
return v <= 0.03928
? v / 12.92
: Math.pow((v + 0.055) / 1.055, 2.4);
});
}

function luminance([r, g, b]) {
return 0.2126 * r + 0.7152 * g + 0.0722 * b;
}

const fg = parseRGB(style.color);
const bg = parseRGB(style.backgroundColor);

const L1 = luminance(fg);
const L2 = luminance(bg);

const ratio = (Math.max(L1, L2) + 0.05) / (Math.min(L1, L2) + 0.05);
return ratio.toFixed(2);
}

// usage
const el = document.querySelector('#myElement');
console.log(getContrastRatio(el));

[slifty]

Really excited to see that this suggestion is being considered (and worked on!) -- Thank you so much to this community and project.

@ferrlen my "peanut gallery" question to the black-or-white-outline proposal would be whether that has a11y challenges in itself.

[ferrlen]

Really excited to see that this suggestion is being considered (and worked on!) -- Thank you so much to this community and project.

@ferrlen my "peanut gallery" question to the black-or-white-outline proposal would be whether that has a11y challenges in itself.

That's an excellent question, slifty! I also didn't know, I tried finding out, but it seems most contrast tools don't take into account text-stroke. I asked ChatGPT and it told me I'd need a 5px stroke for it to be a11y compliant, which is clearly the wrong answer, since you can't read anything with a 5px thick stroke. I'd love to find out the real answer, though.

I will, however, add my 2 cents: -webkit-text-stroke-width: 1px black stroke is already very close to changing color: black. I think it's possible some people might still struggle, but there are high contrast modes in browsers and OSs, and also by zooming in the page one can also see the outline more clearly. Neither answer is very good, but this way at least we don't change the author's background color nor a text color that might have meaning. A final option is for participants to avoid using author colors that conflict with chosen text colors

[JohnMcLear]

I think I have a PR in that addresses this problem but I'd really appreciate feedback before we merge as WCAG goalposts have moved (rightly so) and I am rusty. Please see #7565 and provide feedback as it's really valuable to us landing this feature :)

STR/STT

For anyone who wants to try the fix in PR #7565 before it lands — here's a recipe to run it locally. Tested on Linux/macOS; Windows works too with PowerShell equivalents for the env vars.

1. Get the branch

git clone https://github.com/ether/etherpad.git
cd etherpad
git fetch origin pull/7565/head:wcag-7377
git checkout wcag-7377

(If you already have an etherpad checkout, just run the fetch + checkout lines.)

2. Install + build

pnpm install   # uses the repo's pinned pnpm via Corepack — `corepack enable` if needed
cd src
pnpm install

3. Run the dev server

# from src/
npm run dev

Open http://localhost:9001 — give it ~10s after the Etherpad is running log line for the client bundle to compile.

4. Reproduce the original bug, then verify the fix

The cleanest way to set a specific author colour without fiddling with the picker:

1. Open a fresh pad: http://localhost:9001/p/wcag-test

2. Open DevTools → Console, paste:

   async function setColor(hex) {
     document.querySelector('.buttonicon-showusers').click();
     await new Promise(r => setTimeout(r, 150));
     document.getElementById('myswatch').click();
     await new Promise(r => setTimeout(r, 150));
     document.getElementById('mycolorpickerpreview').style.backgroundColor = hex;
     document.getElementById('mycolorpickersave').click();
   }

3. Try the cases from the original issue and the regressions the PR was originally missing:

   setColor('#9AB3FA');   // exact bg from the issue screenshot — was 3.78:1 (fail AA)
   setColor('#ff0000');   // pure red — was 4.00:1 (fail AA)
   setColor('#cc0000');   // dark red — was the older luminosity-cutoff failure
   setColor('#ffeedd');   // already AA-friendly pastel; should NOT be mutated
   setColor('#111111');   // dark bg; should pick light text without clamping

   After each setColor, type a few characters in the pad. Your text should be on a coloured highlight that is clearly readable.

5. Inspect the rendered contrast (optional, for the WCAG-curious)

Run this in the top frame's DevTools console to read the actually-rendered author span:

(() => {
  const inner = document.querySelector('iframe[name="ace_outer"]')
                ?.contentDocument?.querySelector('iframe[name="ace_inner"]')
                ?.contentDocument;
  const spans = inner?.querySelectorAll('#innerdocbody span[class*="author-"]') ?? [];
  if (!spans.length) return console.warn('Type some text first.');
  const seen = new Set();
  spans.forEach(s => {
    const cls = [...s.classList].find(c => c.startsWith('author-'));
    if (seen.has(cls)) return;
    seen.add(cls);
    const cs = getComputedStyle(s);
    console.log({author: cls, bg: cs.backgroundColor, color: cs.color});
  });
})();

Plug those bg/color values into https://webaim.org/resources/contrastchecker/ — every author span should be ≥4.5:1 (WCAG AA).

6. Sanity-check the opt-out

The fix can be turned off by setting padOptions.enforceReadableAuthorColors: false in settings.json (or PAD_OPTIONS_ENFORCE_READABLE_AUTHOR_COLORS=false env var for Docker). With the flag off, you should see the original problem return on #9AB3FA and #ff0000, confirming the clamp is what fixes it.

What to look for / report

• Does the #9AB3FA case from the issue screenshot now look readable to you?
• Any author colour where you can still see a contrast problem? Please paste the hex and a screenshot.
• Anything that looks wrong with #ffeedd or other already-readable colours (the clamp should leave those alone).

@slifty @ferrlen — feedback particularly welcome from you two given the original discussion.