Theme and token audit

Use when touching colours or themes, adding a component, or reviewing a screen in both themes.

Rules

1. Colours come only from the design tokens (CSS custom properties or the theme config of your design system). No hex values, rgb(, bg-black, text-white or raw palette hues such as bg-blue-600 in components or inline styles. If a needed colour has no token, add a token in the app's own theme file; do not edit a vendored design system to get it.
2. Every new surface, border, chip, focus ring and state works in light and dark (and in "system", if the app follows the OS setting).
3. Use semantic tokens by meaning, not by look: main text, secondary text, muted labels and meta, surface and raised surface, border, success, warning, danger. Tone carries meaning: the warning tone only for what needs the user, never for decoration.
4. Contrast: body text 4.5:1, large text and meaningful icons 3:1, in both themes, measured from the token values or the screenshot, never judged by feel. Muted label text on a raised or hover surface is the pair to check first: it is the smallest, palest text.
5. Surfaces and borders: a card in dark must still separate from the page (a border token, not a shadow that vanishes on dark). Pale text on a pale surface, or a dark button on a dark surface, is a defect.
6. States and focus in dark: hover, selected, disabled and the focus ring all exist and keep contrast.
7. Embedded content with its own styles (an iframe preview, a rendered email, user HTML) may keep its own colours, but the frame around it follows the tokens.

Examples

• An email preview pane with a hardcoded white background. It may be deliberate, because emails assume a white canvas. If so, mark it in the code as a named exception with a comment; otherwise it is a hardcoded colour that glares in dark mode. Ask before calling it a defect.
• Status chips for "paid", "pending" and "failed" that all render the same grey in dark mode because they used fixed light-theme values. Fix with success, warning and danger tokens that have dark values, not with per-theme overrides in the component.
• A table row's state on the right uses the success token for "shipped" and the warning token for "needs you"; the same row in dark picks up the dark token values with no extra code. That is the target.

How to test

Search the diff for hardcoded colours:

git diff | grep -nE '#[0-9a-fA-F]{3,8}\b|rgba?\(|hsla?\(|bg-(black|white)|text-(black|white)|-(red|blue|green|amber|yellow|gray|slate)-[0-9]'

Capture light and dark at desktop and phone width; for the smallest text compute contrast against its background in both themes. Use test data only, no secrets in screenshots.

How to report

One finding per problem, ranked by cost to the user: the exact element by its visible text, the offending value, the measured contrast in each theme, the token that replaces it, and the file.