agentleFS
AdilSiddiquiHQAdilSiddiquiHQ/a11y-skills/skills/forced-colors-and-dark-mode/SKILL.md

forced-colors-and-dark-mode

Skill0 starsChanged 29 days agoMITView on GitHub

Use when contrast fails in dark mode, when a component disappears in Windows High Contrast, when status is shown only with color, or when a border or focus ring is a box-shadow that vanishes under forced colors.

The file

We split this skill into the rules it gives an agent

3 rules. About 0 are common, 2 are distinctive, and 1 is very specific to this project.

  • ≈0

    Common · estimate

    Many files like this have a rule of this kind.

  • ≈2

    Distinctive · estimate

    This author's own choices. Worth a look.

  • 1

    Very specific

    Tied to their project's names, files or tools. Probably skip.

  • Common
  • Distinctive
  • Very specific
  1. Distinctive:

    Every contrast claim is a claim about a specific pair of colours in a specific theme and state.

    line 10
  2. Distinctive:

    Never make colour the only cue (SC 1.4.1, Level A): If a field turning red is the only error signal, or a legend colour is the only key, …

    line 59
  3. Very specific:

    Use forced-color-adjust: none sparingly (a last resort): Only when a component's meaning depends on its colours — a colour-swatch picker, …

    line 126

≈ “Common” is an estimate: at least 1 in 5 of the 372,429 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
SKILL.md

Forced colors and dark mode

Criteria: SC 1.4.3 Contrast (Minimum), SC 1.4.6 Contrast (Enhanced), SC 1.4.11 Non-text Contrast, SC 1.4.1 Use of Color, SC 1.3.3 Sensory Characteristics

Every contrast claim is a claim about a specific pair of colours in a specific theme and state. The mistake that matters most is auditing the light theme and shipping the dark one, because dark tokens are generated by inverting the light ones and the ratios silently fall below the floor. The companion mistake is a focus ring or card border drawn with box-shadow, which Windows High Contrast mode does not draw at all, leaving a control with no visible edge in the one theme the user chose for visibility.

When to use

  • A design has a dark theme, a high-contrast theme, or both.
  • A button, input, or focus ring becomes invisible in Windows High Contrast Mode.
  • Status, validation, or chart data is conveyed with red, green, or a colour legend.
  • Placeholder text, disabled text, or a thin icon edge looks too faint.
  • A component is "fixed" with forced-color-adjust: none and now ignores the OS theme.

Procedure

  1. Meet the text ratios in every theme (SC 1.4.3, SC 1.4.6). SC 1.4.3 (AA) requires 4.5:1 for normal text and 3:1 for large text. Large text means ≥ 24 px, or ≥ 18.66 px when bold. SC 1.4.6 (AAA) requires 7:1 for normal text and 4.5:1 for large text. Logotypes are exempt; incidental text is exempt; text in a disabled control still needs to be readable if it conveys information.

    /* Fails SC 1.4.3 in dark mode — #767676 on #1e1e1e is about 3.9:1 */
    [data-theme='dark'] .meta { color: #767676; background: #1e1e1e; }
    
    /* Passes — checked against the dark background, not the light one */
    [data-theme='dark'] .meta { color: #a8a8a8; background: #1e1e1e; }
  2. Meet the non-text ratios (SC 1.4.11, AA). Anything visual that is required to identify a control or understand a graphic needs 3:1 against the adjacent colour(s): input borders, toggle tracks, checkbox outline, chart lines, icon glyphs, and the focus indicator. Disabled controls and user-agent-rendered controls with no author styling are exempt. Check every state, not just the default: hover, focus, active, selected, and error.

    /* Fails SC 1.4.11 — a 1px #e5e5e5 input border on white is ~1.1:1 */
    .input { border: 1px solid #e5e5e5; }
    
    /* Passes — the border is a real boundary at 3:1 or better */
    .input { border: 1px solid #949494; }
    .input:focus-visible { outline: 3px solid #005fcc; outline-offset: 2px; }
  3. Never make colour the only cue (SC 1.4.1, Level A). If a field turning red is the only error signal, or a legend colour is the only key, the information is lost for a colour-blind user. Add a non-colour cue — an icon, a text label, an underline, a pattern — and make sure the cue survives without colour. This is also where links inside body text live: a link distinguished only by hue needs an additional cue on hover and focus.

    <!-- Fails SC 1.4.1 — red alone means "required not filled" -->
    <input class="invalid" aria-invalid="true">
    
    <!-- Passes — the error is named in text and shown with an icon -->
    <p class="error" id="email-err">
      <svg aria-hidden="true" focusable="false"><use href="#error"/></svg>
      Enter an email address.
    </p>
    <input aria-invalid="true" aria-describedby="email-err">
  4. Audit both themes with the same tool. Take the ratio from a contrast checker for every foreground/background pair in both light and dark, including placeholders, dividers, and text on images. Do not trust color-scheme: dark or a filter-based inversion to preserve contrast; a filter: invert() theme inverts the ratios too and reorders nothing.

    /* Declare the theme honestly so form controls and scrollbars follow the OS. */
    :root { color-scheme: light dark; }
    @media (prefers-color-scheme: dark) {
      :root { --fg: #e8e8e8; --bg: #121212; } /* re-check every pair here */
    }

    Note that "pure black background, pure white text" is not a WCAG violation, but very high-luminance text on pure black causes halation for many readers with astigmatism. A near-black (#121212) and an off-white are kinder and make the ratio easier to keep. This is a craft recommendation, not a threshold.

  5. Keep components visible under forced colors. Windows High Contrast Mode discards author colours and replaces them with the user's palette. Author background-image is kept, but box-shadow and background-color are overridden, so a border drawn as a shadow disappears.

    /* Fails in forced-colors — the box-shadow edge is not drawn, so the card and
       the focus ring both vanish. */
    .card { box-shadow: 0 0 0 1px #d0d0d0; }
    .btn:focus-visible { box-shadow: 0 0 0 3px #000; }
    
    /* Passes — a real outline/border with a system colour survives the override. */
    .card { border: 1px solid CanvasText; }
    .btn:focus-visible { outline: 3px solid Highlight; outline-offset: 2px; }
    
    @media (forced-colors: active) {
      .card { border: 1px solid CanvasText; }
      svg.icon { fill: currentColor; }   /* follow the user's text colour */
    }

    Common system colours: Canvas, CanvasText, LinkText, VisitedText, ButtonText, ButtonFace, ButtonBorder, Field, FieldText, GrayText, Highlight, HighlightText, Mark, MarkText, AccentColor. Use currentColor and these keywords instead of hard-coded hex. currentColor on SVGs, outline rather than box-shadow, and border rather than background-image boundaries are the three changes that fix most forced-colors failures.

  6. Use forced-color-adjust: none sparingly (a last resort). Only when a component's meaning depends on its colours — a colour-swatch picker, a syntax-highlighted diff, a photo-editing hue slider. Applying it to a whole component or app restores your palette and defeats the user's theme.

    /* Acceptable: the swatch must show its actual colour to be meaningful. */
    .swatch { forced-color-adjust: none; background: var(--swatch); }
    
    /* Not acceptable: opting the entire card out of the user's theme. */
    .card { forced-color-adjust: none; }
  7. Never name a thing by its colour, shape, size or position alone (SC 1.3.3, Level A). This is the criterion that catches instructions, not decoration: "click the round button", "tap the green one", "see the panel on the right". A user who cannot see colour, or who is reading the page linearly, has no way to act on it. Add the non-sensory identifier the instruction was standing in for.

    <!-- Fails SC 1.3.3 — colour and position are the only identifiers -->
    <p>Press the green button to continue.</p>
    
    <!-- Passes — the instruction names the control -->
    <p>Press <strong>Continue</strong> to move on.</p>

    It also covers state that is carried by colour alone, which is why it sits next to SC 1.4.1 here: a red row that means "failed" needs a word or an icon, and a chart whose series are distinguished only by hue needs a second channel. SC 1.3.3 is about the instruction, SC 1.4.1 about the information; the same fix usually satisfies both.

Verify

Contrast ratios are computable, so verify them numerically; colour-only and forced-colors behaviour needs a human.

// WCAG relative-luminance contrast for a pair of hex colours.
const linear = (c) => { c /= 255; return c <= 0.03928 ? c / 12.92 : ((c + 0.055) / 1.055) ** 2.4; };
const luminance = (hex) => {
  const [r, g, b] = hex.replace('#', '').match(/../g).map((h) => parseInt(h, 16));
  return 0.2126 * linear(r) + 0.7152 * linear(g) + 0.0722 * linear(b);
};
const ratio = (a, b) => {
  const [hi, lo] = [luminance(a), luminance(b)].sort((x, y) => y - x);
  return (hi + 0.05) / (lo + 0.05);
};
console.log(ratio('#a8a8a8', '#1e1e1e').toFixed(2)); // must be >= 4.5 for SC 1.4.3
// Walk the rendered tree and report the computed ratio per text node.
const bgOf = (el) => {
  let node = el;
  while (node) {
    const bg = getComputedStyle(node).backgroundColor;
    if (bg && !bg.includes('rgba(0, 0, 0, 0)')) return bg;
    node = node.parentElement;
  }
  return 'rgb(255, 255, 255)';
};
const toHex = (rgb) => '#' + rgb.match(/\d+/g).slice(0, 3)
  .map((n) => (+n).toString(16).padStart(2, '0')).join('');
for (const el of document.querySelectorAll('p,span,a,li,label,button')) {
  if (!el.textContent.trim() || el.children.length) continue;
  const cs = getComputedStyle(el);
  const r = ratio(toHex(cs.color), toHex(bgOf(el)));
  const large = parseFloat(cs.fontSize) >= 24 ||
    (parseFloat(cs.fontSize) >= 18.66 && parseInt(cs.fontWeight, 10) >= 700);
  if (r < (large ? 3 : 4.5)) console.warn(`SC 1.4.3 ${r.toFixed(2)}:1 on`, el);
}

For forced colors, switch on Emulate CSS media feature forced-colors: active in DevTools and check that every control, border, divider, icon and focus ring is still visible. For SC 1.4.1, desaturate the screen or view a greyscale screenshot: any meaning that disappears was carried by colour alone. Both steps are judgement, and neither axe nor a contrast checker performs them.

Failure modes

  • Dark mode as a filter over light mode. filter: invert() or hue-rotate() on the whole document inverts every ratio with the pixels; the result passes "there is a dark theme" and fails SC 1.4.3.
  • Tokens validated in one theme only. The dark palette is generated by tweaking lightness, and muted text lands at 3.9:1. Only the light theme was ever measured.
  • Focus and boundaries drawn with box-shadow. The ring looks right in the browser, is invisible in Windows High Contrast, and fails SC 1.4.11 and SC 2.4.7 for the users who need them most.
  • forced-color-adjust: none on a component or app. Used to keep brand colours, it also opts the user out of their own palette and can leave dark text on a dark forced background.
  • Colour-only status. Red/green validation, a state dot, a temperature map, or a "highlighted" table row distinguished by hue alone. Passes automated colour checks and fails SC 1.4.1.
  • Low-contrast placeholder and disabled text. #bbb placeholders on white sit near 1.9:1. Placeholder text is not incidental when it is the only hint of what to type.
  • Contrast checked only in the default state. Hover, focus, selected and error states change the background or the text colour and are rarely re-measured; they are separate pairs under SC 1.4.3 and SC 1.4.11.
  • Overcorrection: deleting the focus ring or greying the whole dark theme. Removing a focus outline because it "clashes" in dark mode fails SC 2.4.7 and SC 1.4.11, and washing every colour to pass contrast destroys hierarchy. Fix the specific pair, keep the design.

Download now (ZIP)

Does it work?

Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.

No reviews yet

People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.

  • It worked
  • Partly
  • It didn't
What did you use it for? e.g. Reviewing pull requests in a Rails app

Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.

Your trail

Files you open will collect here, so you can find them again.

Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.

Now do this for your own.

Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.