After a redesign that looked fine, I measured it against WCAG 2.2 AA. 57 of 194 colour pairs failed, plus keyboard and structure issues, all fixed.
This site got a new look today: colourful rounded tiles, thick outlines, offset shadows, a coral accent, light and dark mode. It looked fine. Then I measured it against WCAG 2.2 level AA instead of trusting my eyes, and found real problems. This post covers the accessibility work: what I checked, what failed and how I fixed it while keeping the design. Every number comes from my own runs.
Measure every colour pair, including opacity
A browser tool tests only the elements on screen, in the theme you have open. I computed the contrast ratio of every text and background pair straight from the colour values in the stylesheet, in both themes: 194 pairs. That includes text made lighter with opacity and all 18 colours of the tag badges.
Opacity is the trap: dimmed text is a mix with whatever sits behind it, so blend first, then compare. The formula is the one from WCAG:
def lum(hex_colour):
r, g, b = (int(hex_colour[i:i + 2], 16) / 255 for i in (1, 3, 5))
lin = lambda c: c / 12.92 if c <= 0.04045 else ((c + 0.055) / 1.055) ** 2.4
return 0.2126 * lin(r) + 0.7152 * lin(g) + 0.0722 * lin(b)
def blend(fg, bg, alpha): # text with opacity, painted on its background
mix = lambda i: round(int(fg[i:i + 2], 16) * alpha + int(bg[i:i + 2], 16) * (1 - alpha))
return "#" + "".join(f"{mix(i):02x}" for i in (1, 3, 5))
def ratio(a, b):
hi, lo = sorted((lum(a), lum(b)), reverse=True)
return (hi + 0.05) / (lo + 0.05)
print(round(ratio(blend("#1a1a1a", "#fff8ee", 0.55), "#fff8ee"), 2)) # 3.83
Normal text needs 4.5:1; the parts you need to recognise a control, such as borders, need 3:1 (WCAG 1.4.11). Body text passed, and so did the muted grey, at a lowest 4.66:1 on the peach tiles. 57 of the 194 pairs failed, in a few patterns:
- Dimmed small numbers. Menu and filter counts at 55% opacity were 3.74:1. At 70% they are 6.0:1. Counts inside tag badges went from as low as 2.7:1 to a worst case of 4.5:1 at 90%.
- White on bright colours. The numbers on the homepage activity grid were 2.1 to 3.7:1. Dark text on the same colours gives 4.6 to 8.1:1.
- Hover colours. Coral link text on cream was 2.75:1. The link now keeps its text colour and the underline gets thicker.
- Dark mode borders. Outlines and text-field borders were 1.55:1. Outlines are now 3.02 to 3.35:1, text fields 3.69:1.
Apart from slightly brighter outlines in dark mode, none of this changed the look. Most contrast fixes are a little more opacity, or dark text instead of white.
Structure and the keyboard
For structure I wrote a small script that reads the HTML of every page type and checks for one h1, no gaps in heading levels, landmarks, a skip link, alt text on images, names on links and buttons, and labels on form fields. Before trusting it, I ran it on a page I had broken on purpose, and it caught every planted fault. A check that never fails proves nothing.
Together with a keyboard pass, it found:
- No skip link. Added.
- Focus. Mostly browser default, and the search box had no outline at all. Now one 3-pixel ring in the text colour, or in the tile's own text colour on coloured tiles.
- The sticky header could cover the focused element (WCAG 2.4.11). Scroll padding fixed it.
- Escape in a dropdown threw focus away. It now closes the menu and keeps focus.
- Label in Name. The theme button showed "Dark" but screen readers heard "Switch colour theme". WCAG 2.5.3 wants the visible words inside the accessible name, so it is now "Switch to dark theme".
- Headings. 14 small labels were h4 straight after the h1. They are h2 now, with the same look.
Target size, smaller fixes and the phone menu
Target size (WCAG 2.5.8) asks for 24 by 24 CSS pixels. Menu arrows and tag badges got an invisible larger click area. The activity grid, with cells of about 8 pixels on phones, is hidden on small screens; the lists next to it hold the same updates.
:focus-visible { outline: 3px solid var(--focus, var(--text)); outline-offset: 2px; }
.tile { --focus: var(--tile-text); } /* the ring follows the tile's text colour */
html { scroll-padding-top: 5rem; } /* focused items stay clear of the sticky header */
/* a bigger click area without a bigger badge */
.badge { position: relative; }
.badge::after { content: ""; position: absolute; inset: -6px; }
Smaller fixes: "reduce motion" now stops all animations, Chinese characters in a game name carry a lang attribute, emoji used as icons are hidden from screen readers, and game input fields got labels.
A manual keyboard test on a phone then found something no checker had: with the phone menu open, the page behind it could still be reached. The menu is now a full-screen layer and the rest of the page is inert while it is open.
What I do not know yet
I have not tested with a real screen reader. 200% zoom and text spacing were checked from the CSS, not in a browser by a person.
Frequently asked questions
Why compute contrast from the stylesheet instead of using a browser tool?
A browser tool tests only what is on screen, in the theme you have open. Computing every pair from the colour values covers both themes, every tile colour and text dimmed with opacity.
Which WCAG level did you aim for?
WCAG 2.2 level AA: 4.5:1 for normal text, 3:1 for the parts you need to recognise a control, and click targets of at least 24 by 24 CSS pixels.
Did the fixes change the design?
Hardly. Apart from slightly brighter outlines in dark mode, the look stayed the same. Most fixes were a little more opacity, or dark text instead of white.
What to do first
- List every text and background pair in your stylesheet, in every theme, and compute the ratios, blending opacity first.
- Write a structure check and prove it on a page you broke on purpose.
- Put the mouse away and tab through every page type, including on a phone with the menu open.
- Give every interactive element one visible focus ring and at least a 24 by 24 pixel click area.
For what Lighthouse said about the same pages, see Lighthouse on every page type.