DESIGN.md for dark mode: give agents paired colour tokens

Give an agent a rule for each colour’s job in both themes. A panel needs a background and readable text; the main action needs its own background and label colour. Asking for a darker page without naming those pairs leaves the agent to decide which text, borders and controls should change.

This example uses one set of semantic names, including --surface and --ink. The stylesheet changes their values when the browser reports a dark preference. MDN documents prefers-color-scheme as the CSS media feature for that preference. The example follows the system setting and deliberately has no manual theme control.

The file below tells a reviewer which pairs to check. It keeps the values in styles.css, so the note describes usage without duplicating a palette. Wrenboard is a fictional product; these theme values are a proposed example rather than a measured brand system.

Read the note through AGENTS.md when using the Codex fixture. For Claude Code or Cursor, use the corresponding loading guide. Loading the rule and producing the intended colours remain separate things to verify.

Save this complete stylesheet beside the downloadable HTML. The panel, supporting text and action all consume the same token names in either theme. The hover state changes underline thickness, leaving the action’s text and background pair intact. The focus outline has its own value in each theme.

If you already have a theme system, use its existing owner and selector instead of adding a second one. The existing CSS-conflict guide covers tracing a value back to its owning file; this example addresses the separate problem of checking both themes.

Open the supplied HTML and use your browser’s rendering tools to emulate light and dark preferences. Inspect the computed background and text colours on body, the panel, the supporting paragraph and the main action. A token declaration alone does not tell you which later CSS rule wins.

For normal text, WCAG 2.2’s minimum contrast criterion is 4.5:1; qualifying large text has a 3:1 threshold and the criterion has other exceptions. This fixture chooses 4.5:1 as its check for all its text pairs. That is a proposed test for this sample, not a statement that contrast alone establishes accessibility. Tab to the link and inspect its outline in both modes.

On 3 November 2026, we calculated contrast from the exact hex values in the downloadable stylesheet. All eight declared text pairs exceeded 4.5:1; the lowest was supporting text in the light theme at 7.167:1. These are source-palette calculations using the WCAG contrast formula, not measurements of computed browser styles. A later overriding style could change the rendered pair.

The page contains a panel, supporting text and a link to an access note. There is no form service. Save index.html and styles.css together, then compare the same page in both themes at 390 and 1440 pixels. Keep the content identical so the comparison concerns theme behaviour.

Ask an agent to report each computed text and background pair, then check those numbers in the browser. If it cannot run a browser, its source review should say so. The downloadable AGENTS.md points to the design note; it does not supply a browser tool or guarantee an accurate review.

On 3 November 2026, Codex CLI 0.162.1 reviewed the supplied fixture with codex exec -s read-only and the exact prompt below. It read AGENTS.md, DESIGN.md, styles.css and index.html. Its reply began: “Theme check: No concrete mismatches found in `index.html` and its linked `styles.css`.” It quoted the theme rules and calculated all eight text contrast ratios from the stylesheet, each above 4.5:1. The command exited 0 without changing files.

The run loaded the user’s global configuration too. This is one source review of a compliant fixture; the calculated ratios are not computed browser measurements or a whole-site accessibility result. Separate source checks parsed the CSS, resolved its tokens and confirmed the access target. MDN and W3C documentation was checked on 3 November 2026. A separate native Chrome check at 390 by 844 showed both themes, keyboard focus and a link reaching #access.

Before adding the example to a real site, test its longest text, actual media and form states in both themes. A product image may already have the right colours; do not invert it merely because the surrounding page changes.