CSS light-dark() with design tokens: preserve semantic roles and theme control

An implementation article published in May 2025 describes light-dark() as color-only. That limit is out of date. The MDN page captured for this guide on September 8, 2026 documents either two color values or two image values. The same used-color-scheme mechanism can select a gradient pair or a pair of text or surface colors.

:root {
  color-scheme: light dark;

  /* Paired colors */
  --surface: light-dark(#f7f8f5, #151714);
  --text: light-dark(#20231f, #f1f3ee);

  /* Paired images */
  --page-wash: light-dark(
    linear-gradient(#ffffff, #f3f4ef),
    linear-gradient(#1b1e1a, #111310)
  );
}

body {
  color: var(--text);
  background-color: var(--surface);
  background-image: var(--page-wash);
}

Dark mode crosses several layers. Treating them as one setting makes failures hard to route. The token source defines the authoritative light and dark values for a role such as surface.default. A transformation turns that decision into CSS. Then a root element or nested scope establishes the used color scheme. Finally, a component consumes the semantic property and produces an observable result.

The distinction between tokens and CSS variables matters here. Tokens capture source decisions that may serve several platforms; CSS custom properties are one web representation of them. A successful browser edit doesn't prove that the source record or generated artifact is correct. A correct token export doesn't prove that the application established the intended scheme either.

Start with the preference contract, not the newest syntax. Does the product follow the operating system, offer an explicit choice, contain independently themed subtrees, or combine those paths? The answer determines who should own color-scheme.

For an explicit choice, color-scheme controls branch selection. A class such as .dark is one way to target that declaration. The paired custom properties can stay in one place because their values resolve against the resulting used scheme.

Keep primitive values separate from semantic roles and component consumers. Primitives describe the palette; semantic properties describe intent. Components consume those semantic names, so a card doesn't need to know that its background happens to be a particular green in one mode.

:root {
  color-scheme: light dark;

  /* Primitive palette values */
  --sage-050: #f3f4ef;
  --sage-900: #171a16;
  --ink-900: #20231f;
  --ink-050: #f1f3ee;
  --line-light: #d7dbd2;
  --line-dark: #3a4038;

  /* Semantic roles with paired mode values */
  --background: light-dark(var(--sage-050), var(--sage-900));
  --foreground: light-dark(var(--ink-900), var(--ink-050));
  --border: light-dark(var(--line-light), var(--line-dark));
}

.card {
  color: var(--foreground);
  background: var(--background);
  border: 1px solid var(--border);
}

The component still requests --background, --foreground, and --border. It doesn't select a mode or reach into the primitive palette. If the dark border is wrong across many consumers, inspect the semantic pair. If only one card is wrong, inspect that component's cascade before changing the shared token.

The pattern below supports a System, Light, and Dark preference. The default root declaration permits both schemes, so the system preference can participate. An explicit application choice narrows the root to one scheme. A nested preview can establish another without rewriting every token.

/* Default: allow the user agent to use the system preference. */
:root {
  color-scheme: light dark;

  --background: light-dark(#f7f8f5, #151714);
  --foreground: light-dark(#20231f, #f1f3ee);
  --border: light-dark(#d8ddd4, #394038);
  --focus-ring: light-dark(#536b3e, #b6d58d);
}

/* Explicit app choices. The app owns this attribute and its persistence. */
:root[data-theme="light"] {
  color-scheme: light;
}

:root[data-theme="dark"] {
  color-scheme: dark;
}

/* A bounded preview can differ from the surrounding page. */
.theme-preview[data-preview-theme="light"] {
  color-scheme: light;
}

.theme-preview[data-preview-theme="dark"] {
  color-scheme: dark;
}

body {
  color: var(--foreground);
  background: var(--background);
}

input,
button,
.card {
  color: var(--foreground);
  background-color: var(--background);
  border-color: var(--border);
}

:focus-visible {
  outline: 2px solid var(--focus-ring);
}

CSS doesn't handle preference persistence. Your application must decide where the user's choice lives and when to apply it. The implementation varies by framework and rendering model, so this guide doesn't present one storage script or initial-render strategy as universal.

Don't begin by replacing every .dark declaration. First, identify which duplicated declarations express a simple light and dark pair. Choose a low-risk role such as a secondary surface or border, then record the expected result before editing.

1. 1

   Choose one semantic role

   Name the role, its authoritative light and dark values, and the source version. Don't start with a role that has many undocumented exceptions.

2. 2

   Name every intended consumer

   List representative components and surfaces that should change. Also record the protected surfaces that must remain unchanged.

3. 3

   Declare the scheme owner

   Record whether the root, an explicit app preference, a nested scope, or a hybrid path determines the used color scheme.

4. 4

   Write the expected values first

   For each supported path, record the expected computed value before changing the CSS. This prevents the current rendering from rewriting the requirement.

5. 5

   Convert the role

   Put the paired values in the semantic custom property. Leave unrelated selector rules in place until you've classified their responsibilities.

6. 6

   Observe and decide

   Record the computed value and rendered result separately. Mark the migration accept, revise, or retain selectors, and assign an owner to every exception.

Classify the remaining selectors instead of dismissing them as legacy. They may encode compatibility policy or behavior that light-dark() can't express. Remove genuine duplication only after verification.

• Unsupported-browser requirements: keep a tested fallback strategy that matches the project's actual support policy. Don't infer support from one development browser.
• Non-paired behavior: retain application logic or selectors for layout, visibility, motion, component variants, and interaction changes.
• Separate visual assets: a paired CSS image may work for gradients or other CSS images, but logos, illustrations, video, canvas content, and inline asset rules may need their existing mechanism.
• High-contrast requirements: treat forced colors, custom high-contrast modes, and accessibility-specific adaptations as their own contract. Don't assume a light or dark pair covers them.
• Local inversions and previews: keep bounded scope rules when a subtree intentionally differs from the application root.
• Project-specific exceptions: record why the exception exists, who owns it, which surfaces it affects, and what evidence would allow its removal.

/* Baseline for the project's fallback policy. */
:root {
  --background: #f7f8f5;
  --foreground: #20231f;
}

/* Upgrade only when the function is supported. */
@supports (color: light-dark(white, black)) {
  :root {
    color-scheme: light dark;
    --background: light-dark(#f7f8f5, #151714);
    --foreground: light-dark(#20231f, #f1f3ee);
  }
}

Write down expectations before opening the page. Then capture the computed custom property, computed consuming property, and rendered result as separate observations. A variable may contain the intended expression while a later override changes the component. Even a correct computed color can sit beside an incorrect asset or native control.

Trace failures in ownership order. Confirm the source pair first, then inspect the generated representation, scheme controller, cascade, and consumer. This prevents a local override from prompting an unnecessary change to a shared token.

Identity Forge supplies upstream design decisions, including 28 semantic light and dark color roles and CSS-oriented exports. Those paired roles are suitable inputs for this migration. The consuming application still owns the control model, selector conversion to light-dark(), preference persistence, browser-support policy, cascade resolution, unrelated assets and behavior, and validation of the rendered result.

The two sides have distinct jobs. The design kit remains authoritative for what roles such as --background, --foreground, --primary, and --border mean in each mode. The consuming application remains authoritative for how those values reach a particular browser and surface.

Choose one low-risk semantic pair and record its source values, consumers, protected surfaces, scheme owner, fallback requirement, and expected matrix results. Convert the role, run every supported preference and scope path, then mark it accept, revise, or retain selectors. Don't convert the next role until the first record contains real observations instead of assumptions.

• light-dark() CSS function - MDN Web Docs - Mozilla: MDN documents how light-dark() selects through the used color scheme, accepts paired color or image values, and provides current compatibility information.
• color-scheme and light-dark() - Medium: The article demonstrates system-following and explicitly controlled theming with semantic custom properties while making an older color-only limitation claim.
• The developer's guide to design tokens and CSS variables - Penpot: Penpot distinguishes platform-agnostic design-token decisions from the CSS custom properties that implement them in the browser.
• Design Tokens To Dark Mode - Frank Congson: The project note shows light and dark semantic token sets mapped from core values and then connected to applied theme tokens.
• Design Tokens - Web Awesome: Web Awesome documents token variables across root, light, dark, and inverted contexts, demonstrating scoped theme consumers.
• Visual modes - Cloudscape Design System: Cloudscape treats light and dark modes, user choice, mode-aware custom styles, and visual assets as deliberate product concerns.
• Design Tokens - NYS Design System: The NYS Design System separates primitive, semantic, and theme tokens and directs components toward purpose-driven roles rather than raw palette values.
• Semantic color tokens explained: Identity Forge publishes 28 semantic light and dark color roles and explains role-based names such as background, foreground, primary, border, and ring.