English for Explaining Dark Mode and Design Token Decisions

Implementing dark mode and theming sounds like a purely visual problem, but the conversations around it — with designers, other engineers, and QA — require precise vocabulary about tokens, contrast, and semantic naming. This guide covers the English for having those conversations clearly.

Key Vocabulary

Design token — a named, reusable value (a color, spacing unit, font size) that represents a design decision, used instead of hardcoded values so themes can be swapped consistently. “Instead of hardcoding #1a1a1a, we use the token color-surface-primary, which resolves to a different hex value depending on whether light or dark theme is active.”

Semantic naming — naming a token by its purpose or role (“color-text-danger”) rather than its literal value (“red-500”), so the name still makes sense when the underlying value changes between themes. “We renamed red-500 to color-text-danger — the semantic name still makes sense in dark mode, where the actual color might be a different shade of red.”

Theme switching — the mechanism by which an application changes which set of token values is active, typically by swapping a CSS variable set or a context value. “Theme switching happens by toggling a data-theme attribute on the root element — all our tokens are defined as CSS custom properties scoped to that attribute.”

Contrast ratio — a measurement of the difference in luminance between two colors, used to verify text remains readable against its background in both themes. “We need to re-check contrast ratios for dark mode specifically — a pairing that passes in light mode doesn’t automatically pass once the background inverts.”

Token resolution — the process of a token ultimately resolving to a concrete value at build time or runtime, sometimes through multiple layers of aliasing. “This bug was a token resolution issue — color-button-primary was aliased to a token that itself wasn’t defined for dark mode, so it silently fell back to the default.”

Common Phrases

• “This component still uses a hardcoded color instead of a token — that’s why it doesn’t respond to theme switching.”
• “Can we make this token semantic instead of literal, so it still makes sense in dark mode?”
• “We need to verify contrast ratios separately for each theme, not just light mode.”
• “This is a token resolution bug — the alias chain breaks in dark mode.”
• “Let’s define a dark mode value for this token before merging.”

Example Sentences

Explaining a bug caused by a hardcoded value: “This card’s border is invisible in dark mode because it’s hardcoded to #e0e0e0, a light gray that blends into the dark background. If we switch it to the color-border-default token, it’ll automatically pick up an appropriate value in both themes.”

Proposing semantic naming to a designer: “Rather than naming this token blue-600, I’d suggest something like color-action-primary — it describes what the color is for, not what it looks like, which matters because the actual hex value will differ between light and dark themes.”

Flagging a contrast issue found during dark mode QA: “During dark mode testing, I found that the disabled button text has a contrast ratio of 2.3:1 against its background, which fails accessibility guidelines. This combination wasn’t a problem in light mode, so it looks like it just wasn’t checked for dark mode specifically.”

Explaining the token architecture to a new team member: “We have two layers: primitive tokens, which are raw values like gray-900, and semantic tokens, like color-text-primary, which reference a primitive token and can point to a different one per theme. Components should only ever reference semantic tokens, never primitives directly.”

Professional Tips

• When flagging a dark mode bug, name the specific token (or the absence of one) as the root cause — “this is hardcoded instead of using a token” is a precise, actionable bug description.
• Use “semantic token” vs “primitive token” as a distinction when discussing architecture — it’s the standard vocabulary in design systems and signals you understand the layering.
• Always mention that contrast needs separate verification per theme — it’s a common oversight, and stating it explicitly in a design review saves a QA cycle.
• Describe theme-switching bugs as “token resolution” issues when the value is coming from the wrong place in an alias chain — it’s more specific than “the color is wrong.”
• When proposing new tokens, justify the name by its purpose, not its appearance — this is the core argument for semantic naming and it lands well with designers.

Practice Exercise

1. Write a sentence describing a dark mode bug caused by a hardcoded (non-token) value.
2. Write a sentence proposing a semantic token name and explaining why it’s better than a literal one.
3. Write a sentence flagging a contrast ratio failure found specifically during dark mode testing.