Design systems / Practical guide # How to review light and dark color themes together A paired-theme review matrix with explicit checks. [By CRRT](/)·November 2, 2026·4 min read [← All resources](/resources) ## The short answer Review light and dark themes as two versions of the same task. Compare matching screens and states, measure relevant text/background pairs, and check that semantic roles survive the theme change. A readable default screen does not establish that hover, focus, error, and disabled states are correct. ## 1\. Pair matching screens and states Start with one real flow and use the same content in both themes. Include an empty state, a populated state, a validation error, and an open overlay where those exist. Record the build and theme preference so another reviewer can reproduce the comparison. Review each theme in the running product rather than judging a palette sheet alone. A surface color can work in isolation while making a field, border, or secondary action difficult to distinguish in context. Keep browser settings and viewport consistent while comparing the pair. ## 2\. Measure the pairs people must read Identify the actual foreground and background for body text, supporting text, field labels, errors, and buttons. Check the pair in the state being reviewed. An overlay, transparency, or image can change the effective background, so a simple opaque-color calculation may not describe the rendered result. Use the text contrast checker linked below for opaque sRGB HEX pairs. It reports the selected text criterion; it does not evaluate the entire component or certify a page. Review non-text indicators and interactions separately using the relevant accessibility requirements. * Check normal text against the applicable minimum text contrast requirement. * Confirm the text category before applying a large-text exception. * Review supporting text and placeholders in each theme. * Check errors and selected states without relying only on color. ## 3\. Preserve meaning across the theme switch An action should retain its role even if its color changes. Check that destructive actions, quiet actions, selected navigation, and status messages remain distinguishable for the same reason in both themes. Avoid treating a light palette as a set of values to invert mechanically. Inspect the tokens behind an inconsistent element before asking for a new color. The component may use a raw value or a token that describes the wrong role. A correction such as “Use the secondary-text token for this explanation in both themes” gives an implementer a clearer rule than “make the gray lighter.” Copy & adapt ``` Theme review matrix Screen / state: account form with invalid email Light: label, input, error text, border, primary action Dark: label, input, error text, border, primary action Check: text pairs, visible focus, error meaning, overlay layering Issue: helper text uses a fixed color instead of its semantic token Requested fix: reuse the helper-text token in both themes Verify: repeat the state, switch themes, and reload the saved preference ``` ## 4\. Test switching, persistence, and the fix If the product offers a theme preference, switch while a dialog is open and while a field has an error. Reload the page to inspect persistence. Check the preference rules your product actually supports rather than assuming that a system setting and an application setting are interchangeable. Record the specific theme and state with every visual correction. When a shared token changes, inspect another consumer in both themes. A coding agent can implement an accepted request, but a reviewer should confirm the resulting pair before approving the change. ## Common questions ### Does passing a contrast check mean the theme is accessible? No. A text contrast result addresses one color pair and criterion. Keyboard access, focus, state communication, reflow, and other applicable requirements still need review. ### Should every light-theme color have a direct dark-theme equivalent? Every semantic role needs an appropriate treatment, but its implementation can differ. Review the role and task instead of requiring a mechanical inversion of each value. ## Sources & further reading * [W3C: minimum text contrast](https://www.w3.org/WAI/WCAG22/Understanding/contrast-minimum.html) * [W3C: use of color](https://www.w3.org/WAI/WCAG22/Understanding/use-of-color.html) Written with AI assistance. Tool references checked against the linked documentation on November 2, 2026. Examples are starter templates to adapt and review in your own project. Keep going ## Put the next piece in place. [ Practical guide · 3 min read ### How to organize a Storybook design review A component review plan that stays connected to the product. ](/resources/storybook-design-review)[ Interactive tool · 3 min read ### Text contrast checker for UI color pairs Check a color pair and copy a precise review note. ](/resources/text-contrast-checker) ## See something off? Ship the fix. Pin the feedback. Give your coding agent the context. Review what comes back. [Try CRRT](/docs/install)