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.

Navigating Nuance: Specific Language for International Teams

Communicating effectively about complex topics like dark mode and design tokens requires more than just stating a fact. It’s about conveying why a decision was made, anticipating potential challenges, and fostering collaboration – all of which benefit from precise language. For developers who are still building their professional English vocabulary, particularly when discussing technical details with international teams, there are specific phrases and approaches that can dramatically improve understanding and reduce misunderstandings. The key is to move beyond simply stating the what and delve into the how and why.

Let’s consider a common scenario: you receive a code review comment on a PR introducing a new dark mode theme. Instead of just responding with “Fixed,” which can be frustratingly vague, try something like, “Thanks for pointing this out! I’ve adjusted the color-palette-dark token to ensure consistent application across all components. Specifically, I’ve modified the --primary-text-color-dark value from #FFFFFF to #212121, aligning it with the brand guidelines outlined in the design system documentation. I’ve also added a comment within the relevant component files explaining this change and referencing the token definition for future clarity.” Notice the shift? We’re not just fixing a bug; we’re demonstrating an understanding of the broader context, acknowledging the reviewer’s feedback, and proactively communicating the rationale behind our solution.

Another situation arises when discussing design token decisions with a designer in a Slack channel. Instead of saying, “Dark mode looks better,” which is subjective and doesn’t offer insight, you could say, “I’m adjusting the --background-color token to a darker shade – currently #121212. This was based on user testing data showing improved readability in low-light conditions, as documented in the design system’s research report. It also allows us to better adhere to accessibility guidelines regarding contrast ratios for text.” Framing your input around quantifiable data and referencing established documentation strengthens your argument and shows you’re operating within a shared understanding of design principles and technical constraints.

Finally, when writing PR descriptions, avoid overly technical jargon that might not be understood by everyone on the team. Instead of “Implemented dark mode using CSS variables,” try “Introduced a new dark theme utilizing design tokens for consistent styling across the application, enhancing accessibility and improving visual comfort in low-light environments.” The latter is more approachable, clearly states the purpose, and provides context – crucial when collaborating with colleagues from diverse backgrounds. Remember, clear communication isn’t about technical perfection; it’s about ensuring everyone understands the value of your work and how it contributes to the overall product vision.