Color
This skill holds the colour rules that apply on every screen. It covers contrast, role tokens, translucent neutrals, dark mode and what the accent is for.
Ratios are exact, measured on screen
The contrast ratios here are exact and apply in every theme. They are WCAG 2 ratios, the method conformance claims and accessibility law cite. A ratio is read from the colour the screen draws, never guessed from a token's name. A ratio under the threshold is a finding in any style.
Searching for an existing token belongs to reuse. color-scheme, theme-color, the theme switch, status shown by colour alone and surfaces under reduced transparency belong to defaults. Whether a colour should be there at all belongs to restraint. A focus ring's style belongs to defaults, and its 3:1 change from the unfocused state is checked stop by stop in keyboard.
Body text clears 4.5:1
Text under 24px, or under 18.66px when bold, meets 4.5:1 against what sits behind it. Larger text meets 3:1. Placeholders and secondary text count, and disabled controls do not. #999 text on white, at 2.8:1, is color-text-contrast.
Field edges and icons clear 3:1
The edge that shows where a field is, a toggle's track and an icon that carries meaning meet 3:1 against their surround. A field whose only edge is a #e5e5e5 border on white, at 1.3:1, is color-ui-contrast. Dividers and the ring on a floating surface are decoration and exempt.
Native checkboxes, radios and range inputs take the accent through accent-color, and the drawn control meets 3:1 against its surface. With color-scheme: light dark on the root, they redraw for the dark theme. A default blue checkbox beside an orange accent is color-accent-color.
Measure the colour on screen
Translucent colours and opacity composite over every layer behind them before the ratio is read. Read each theme and each surface the text appears on. A ratio taken from the token's hex while the text sits at opacity: 0.6 is color-measure-composited.
Run contrast.js in the page through the browser's evaluate call. Treat each result as a candidate, and confirm it in a zoomed crop before reporting it. Each failure carries suggestion, the nearest colour at the same hue that passes. Fix with the role token closest to it. Each text finding also carries lc, its APCA lightness contrast.
The ratio is the pass line
APCA lightness contrast (Lc) is a second read, never a pass. No standard requires it yet. White on #f97316 reads at Lc 58 but fails at 2.8:1, and calling it a pass is color-ratio-is-the-pass-line.
The ratio overstates light text on dark surfaces. #888888 on #0a0a0a passes at 5.6:1 yet reads at only Lc 38. Report Lc beside the ratio in the dark theme, and between two passing candidates take the higher absolute Lc.
The contrast-color() function stays off mid-tones
contrast-color() returns white or black, whichever has the higher ratio. On a mid-tone fill the pick can pass and still read poorly. #2277d3 gets black at 4.65:1 and Lc 33, while white reads at Lc 76.
Use it only on fills where its pick clears 7:1, a fill luminance under 0.1 or over 0.3. Give a mid-tone fill a paired token such as --on-accent. contrast-color() on a mid-blue button is color-contrast-color-mid-tones. Declare a fixed colour before it, which older browsers keep.
Text over images takes a scrim
Text on a photo or a video sits on a gradient scrim or a solid plate. The ratio holds at the lightest point of the image under the text. White text over a bright sky is color-scrim-under-text.
Components use role tokens
Components reference tokens named for their role, such as --text-secondary or --surface-raised. Only the theme file maps a role to a palette step. color: var(--gray-500) inside a component is color-role-tokens.
States mix from their role token
Hover and pressed states of a coloured fill, such as --accent, derive from that token with color-mix(in oklch, …) or relative colour syntax. Every theme then carries them. Mix toward --text-primary, not black, so the dark theme lightens on hover. A hand-picked #1d4ed8 hover beside --accent: #2563eb is color-states-from-tokens. The mixed fill is measured like any other.
Neutrals on surfaces are translucent
Borders, dividers, hover fills and pressed fills use alpha neutrals, so they read on any surface beneath them. A solid #f5f5f5 hover fill that vanishes on a grey card is color-alpha-neutrals.
Dark mode is its own palette
Dark surfaces rise by getting lighter, because a shadow barely shows on a dark page. A dark popover the colour of the page, raised by a shadow alone, is color-dark-raises-lighter.
Accents and status colours take dark values tuned for contrast. The light #2563eb link reused on a #0a0a0a page, at 3.8:1, is color-dark-tuned-accents.
Dark body text is an off-white such as #ededed, which still reads at 16.9:1 on #0a0a0a. Pure #ffffff at 19.8:1 halates on near-black, and is color-dark-off-white-text.
Logos and brand images carry a variant or a treatment that reads in both themes. A dark logo on a dark surface is color-logo-both-themes. An image with a white background dims slightly in dark mode, with filter: brightness(0.9).
Increased contrast has its own tokens
Under @media (prefers-contrast: more) the role tokens remap. Small text reaches 7:1 and translucent borders turn opaque. Read every colour in light, dark and increased contrast. A theme with no prefers-contrast: more block is color-more-contrast.
Gradients blend in oklch and fade on a curve
A gradient between two hues interpolates in oklch, so its middle stays saturated rather than turning grey. A blue to yellow gradient with a muddy grey middle is color-gradient-in-oklch. A color-mix() between two hues takes in oklch too, because in srgb greys the same way.
A fade to transparent, such as a scroll edge or a scrim, takes about 6 stops along an ease-out curve. Two linear stops leave a visible line where the fade meets the solid colour. linear-gradient(transparent, black 24px) is color-eased-gradient.
The accent marks action
The accent colour marks the primary action, the selection and focus. An accent heading or a row of accent icons is color-one-accent.
Each view or region, such as a card, a toolbar or a form, holds one accent-filled button, and the rest are secondary or quiet. Two filled accent buttons side by side is color-one-primary. A dialog footer's order belongs to overlays-button-order.
Each status colour keeps one meaning. Red marks errors and destructive actions only. A red "New" badge is color-status-meaning.
The pair
Every check is a pair. The broken line sits beside the line that replaces it.
| Rule | Broken | Replacement |
|---|---|---|
color-text-contrast |
color: #999 on white, 2.8:1 |
color: #737373, 4.7:1 |
color-ui-contrast |
A field edged by #e5e5e5 on white, 1.3:1 |
border-color: #8a8a8a, 3.5:1 |
color-accent-color |
A default blue checkbox beside an orange accent | accent-color: var(--accent) at 3:1, with color-scheme: light dark on the root |
color-measure-composited |
"The token is #171717, so it passes" |
The ratio of the drawn colour at opacity: 0.6, read on screen |
color-ratio-is-the-pass-line |
"White on #f97316 reads at Lc 58, so it passes" |
2.8:1 fails, so the fill darkens to #c2410c, 5.18:1 |
color-contrast-color-mid-tones |
color: contrast-color(#2277d3), black at 4.65:1 and Lc 33 |
color: var(--on-accent) set to #ffffff, 4.52:1 and Lc 76 |
color-scrim-under-text |
White text straight over a photo | An eased scrim from rgba(0, 0, 0, 0.6) at the bottom to transparent, under the text |
color-role-tokens |
color: var(--gray-500) in Card |
color: var(--text-secondary) |
color-states-from-tokens |
.button:hover { background: #1d4ed8 } beside --accent: #2563eb |
background: color-mix(in oklch, var(--accent), var(--text-primary) 12%) |
color-alpha-neutrals |
background: #f5f5f5 on hover |
background: var(--gray-a3) on hover |
color-dark-raises-lighter |
A dark popover at the page's #0a0a0a |
The popover at #1a1a1a over the #0a0a0a page |
color-dark-tuned-accents |
#2563eb links on #0a0a0a, 3.8:1 |
#60a5fa in the dark theme, 7.8:1 |
color-dark-off-white-text |
--text-primary: #ffffff on #0a0a0a, 19.8:1 |
--text-primary: #ededed, 16.9:1 |
color-logo-both-themes |
The dark logo on the #0a0a0a page |
A light logo variant in the dark theme |
color-more-contrast |
One set of role tokens for every contrast setting | A prefers-contrast: more block with small text at 7:1 and opaque borders |
color-gradient-in-oklch |
linear-gradient(to right, #2563eb, #facc15) |
linear-gradient(in oklch to right, #2563eb, #facc15) |
color-eased-gradient |
linear-gradient(transparent, black 24px) |
linear-gradient(transparent, rgb(0 0 0 / 0.36) 5px, rgb(0 0 0 / 0.64) 10px, rgb(0 0 0 / 0.84) 14px, rgb(0 0 0 / 0.96) 19px, black 24px) |
color-one-accent |
Section headings in the accent colour | Headings in --text-primary, the accent on the primary button |
color-one-primary |
Save Draft and Publish side by side, both accent-filled |
Publish filled, Save Draft secondary |
color-status-meaning |
A red "New" badge | A neutral or accent badge |
Reporting
Severity. HIGH is body text under its ratio on a primary surface, a field whose edge fails 3:1 or text over an image with no scrim. MEDIUM is a palette step inside a component, a solid neutral that vanishes on a surface or a ratio never read on screen. It is also a dark surface raised by shadow alone or a light accent reused in dark mode. It is also a theme with no increased contrast remap, or a logo lost on a dark surface. It is also two accent-filled buttons in one view or region. It is also a pass claimed from Lc on a failing ratio, contrast-color() on a mid-tone fill or a hover colour picked by hand. LOW is the accent used for decoration, a status colour carrying a second meaning or a gradient that greys in the middle. It is also a fade on two linear stops, or a native control left in the default accent. It is also pure white body text on a dark page.
Format. One finding per root cause:
file:line - [rule-id] what is wrong (measured ratio)Then a Rule | Count | Severity summary. Block when any HIGH remains, Approve otherwise. Never Approve a theme you did not open. Mark text over canvas, video and cross-origin frames as Not verified.