Support for different modes/themes?

[craigsmitham]

Thanks for promoting an open standard for DESIGN.md. Our token set has ~100 role tokens maintained in parallel for light and dark. What if the spec were extended to support something like this?

---
version: alpha
name: AcmeOrg
themes: [light, dark]
default-theme: light
colors:
  surface:    { light: "#ffffff", dark: "#1b1a18" }
  on-surface: { light: "#2a2825", dark: "#f3f0ec" }
  brand-accent: "#5f3dc4"
components:
  button: { backgroundColor: "{colors.surface}" }   # resolves per active theme
---

[dd-bmunge]

Strong +1 on this. We run a multi-platform design system with several brand themes, each with light/dark modes, across thousands of tokens organized in three tiers (base primitives, semantic usage tokens, component tokens).

The inline { light: ..., dark: ... } approach in the OP works well for light/dark within a single theme. For brand-level theming on top of that, I think there also needs to be a multi-file inheritance model. Something like:

---
name: Consumer
extends: ./DESIGN.base.md
modes:
  light:
    colors:
      text-default: "{colors.neutral-100}"
      background-default: "{colors.white}"
  dark:
    colors:
      text-default: "{colors.neutral-0}"
      background-default: "{colors.neutral-900}"
---

Where DESIGN.base.md defines the primitive tokens and defaults, and brand files extend it with overrides. This would give you:

1. A base file defining primitives and defaults
2. Theme files that extend the base and override specific tokens
3. Mode definitions (light/dark) within each theme file
4. export and lint resolving the full inheritance chain

Without something like this, design.md can't be used as a source of truth for any design system with brand variants -- which is most production systems at scale.

[MickaelV0]

Adding a real-world case that stretches the theme model beyond light/dark — a branded aesthetic variant that shares brand hues but differs in ways a theme token can't express.

Our product "Lyra" ships two aesthetic variants:

Axis	v1 Obsidian	v2 GitHub-dark
Scope	Marketing / hero / avatar / READMEs	Dep-graphs / architecture / dense docs
bg	#0a0a0f	#0d1117
Elevation ladder	bg → surface (2 levels, recessed)	bg → cell → panel → card (4 levels, raised)
Body chrome	Radial ember + 42px grid mask	Flat
Display font	Chakra Petch 700 (loaded)	Outfit 700 (Chakra Petch NOT loaded)
Accent glow α	0.22	0.40
Light theme	Authorized for docs	Dark-only by design

The key gap vs. {light, dark} per-token:

1. Font-loading deltas. A themes: [v1, v2] model would still need to say "don't load Chakra Petch on v2" — a constraint no current field can express. This matters for performance and intentional aesthetic scoping, not just preference.
2. Different elevation models. v1 has 2 surface levels; v2 has 4. surface.v1 and surface.v2 aren't the same token resolved differently — the schema differs.
3. Different type scales per variant. v1 display is Chakra Petch at 4rem; v2 promotes Outfit to display. Not a palette swap.
4. Mixing rule. A file must pick one variant — crossing variants across a link is the signal (marketing → architecture). This is authoring-rule info the spec has no place for.

Proposal to extend this issue: consider a top-level variants: (distinct from themes:) where each variant can override not just color/typography values but also which tokens exist and which fonts load. Themes stay for pure per-token value swaps (light/dark). Variants cover branded siblings with structural deltas.

Happy to share our full three-brand setup (Roxabi hub / Lyra product / Mickael personal — with Roxabi→Mickael variation and Lyra v1↔v2) as a test case if useful.

[Qrofeus]

@MickaelV0's variants: vs themes: split is cleaner than what I was going to propose. Font-loading deltas and different elevation schemas aren't value swaps across a single schema; they're separate systems that happen to share tokens.

Adding a linter angle neither comment has touched.

I've been running the lint CLI on a draft DESIGN.md converted from my portfolio's existing design guide. Palette sketch:

colors:
  primary:        { light: "#2C8A96", dark: "#5BBECB" }
  primary-subtle: { light: "#E6F4F5", dark: "#0D2328" }
  bg:             { light: "#FFFFFF", dark: "#0F0F0F" }
  text:           { light: "#1A1A1A", dark: "#E8E8E8" }

The accent lightness flips across themes (hsl 37% ↔ 63%), so neutrals and accents both move. Two existing lint rules get weird as soon as #13 lands:

1. orphaned-tokens. Right now any dark token that no component references comes back orphaned, because components can only point at one color. Half the palette looks unused. Once themes exist, a token should count as orphaned only if no theme uses it.

2. contrast-ratio. Needs to resolve (bg, text) pairs per theme. My current draft has a hover pair (primary on primary-subtle) that clears AA in dark and fails at 3.59:1 in light. A theme-blind check misses it.

Variants from #17 and Mickael's proposal push this further: the resolver needs to iterate over (theme × variant) before running either
rule. The rules themselves don't change, the graph they walk does.

If the theme/variant direction settles in a way that makes sense, I'd be up for a PR on the linter side.

[oknemixam]

We built a multi-theme implementation in our @google/design.md bridge — sharing our design choices and two specific validators we found useful, in case they help this discussion.

Our shape vs the author's proposal

The author's syntax is inline per-token:

colors:
  surface: { light: "#ffffff", dark: "#1b1a18" }

Ours is per-theme block override, namespaced under our extension key:

colors:
  primary: "#E44001"
  background: "#FFFFFF"
  on-background: "#1A1A1A"

x-oknemix-themes:
  light:
    colors:
      background: "#FFFFFF"
      on-background: "#1A1A1A"
  dark:
    colors:
      background: "#0B1326"
      on-background: "#DAE2FD"
  high-contrast:
    colors:
      background: "#000000"
      on-background: "#FFFFFF"

Trade-offs we noticed:

Inline-per-token (author's)	Per-theme block (ours)
Minimal vertical space	Easier to scan one theme at a time
Every token must declare full theme map	Unchanged tokens simply inherit from base
Hard to validate "is this theme complete?"	Easy: iterate each theme block, diff keys
Clean for 2 themes, awkward for 4+	Scales to light/dark/high-contrast/print/custom

For real products we've touched (single-theme → light+dark → add HC for accessibility), the block form kept authoring friction low.

Two validators we'd suggest the spec requires

Once themes exist, these two checks save a lot of pain:

1. theme-token-coverage — warn when one theme defines a token that others don't. Common failure mode: light: { surface: #fff, onSurface: #1a1a1a }, dark: { surface: #0b1326 } → onSurface silently falls back to the light value in dark theme, reading light gray text on near-black bg. The linter catches it:

warning [theme-token-coverage]: theme 'dark' omits tokens [on-surface]
  that other themes define. Values inherit from base — likely wrong.

2. theme-contrast — run the existing WCAG contrast check per theme. A component passing 4.5:1 in the light theme can easily fail in dark if the contrast relationship between primary and surface inverts (happens a lot). The check is the same ratio calc Google already ships, applied to each merged theme palette.

warning [theme-contrast]: theme 'dark': textColor (#1a1a1a) on
  backgroundColor (#0b1326) has contrast ratio 1.32:1, below WCAG
  AA minimum of 4.5:1.

Both validators are about 50 lines each in our bridge. Happy to PR either direction (inline-per-token or block form) if the spec decides — we're invested in interoperability either way.

Linking to related issues since they intersect here:

• Support OKLCH colors #27 OKLCH — theme blocks interact with color space, since dark themes often shift lightness on the same hue
• Feature: Add Support for Component Variations #17 component variations — theme overrides can cover component-level states, overlap to keep in mind

[davideast]

Just wanted to drop in here and say there a lot of great ideas and it makes me really happy seeing everyone discussing. It's been a wild week but I'm going to find the time to review all the issues and PRs with real and thoughtful feedback.

[craigsmitham]

@oknemixam that's a great option too! Trade-offs make sense.

[davideast]

I'm very supportive of multi-themes and I like @dd-bmunge's proposal because modes or whatever common property name will be agent friendly when tooling isn't present. I also like the idea of extension though extends as that is intuitive to agents, especially with extends in tsconfig.json. I want to avoid token explosion so this is a good option.

I also think this presents a good opportunity to source external files as token values. What I'm interested in everyone's thoughts is not only being able to reference another yaml file, dark.yaml and light.yaml:

---
name: Consumer
extends: ./DESIGN.base.md
modes:
  light: './light.yaml'
  dark: './dark.yaml'
---

But possibly with existing configuration such as tailwind.config.js, DTCG's tokens.json, and also just a simple :root declaration of CSS custom properties.

---
name: My cool theme
imports: './tokens.json`
---

The tokens.json being a file like below:

{
  "color": {
    "$type": "color",
    "brand": {
      "primary": {
        "$value": "#0047FF",
        "$description": "The primary brand color, used for main CTAs."
      },
      "secondary": {
        "$value": "#6B7280"
      }
    },
    "surface": {
      "neutral": {
        "$value": "{color.brand.secondary}",
        "$description": "An alias token pointing to the secondary brand color."
      }
    }
  },
  "spacing": {
    "$type": "dimension",
    "base": {
      "$value": "4px"
    },
    "large": {
      "$value": "16px"
    }
  },
  "typography": {
    "body": {
      "$type": "typography",
      "$value": {
        "fontFamily": "Inter, sans-serif",
        "fontSize": "16px",
        "fontWeight": "400",
        "lineHeight": "1.5",
        "letterSpacing": "0px"
      }
    }
  },
  "shadow": {
    "card": {
      "$type": "shadow",
      "$value": {
        "color": "#00000033",
        "offsetX": "0px",
        "offsetY": "4px",
        "blur": "8px",
        "spread": "0px"
      }
    }
  }
}

Or an analogous CSS custom properties file:

---
name: My cool theme
imports: './base.css`
---

:root {
  /* Colors */
  --color-brand-primary: #0047FF;
  --color-brand-secondary: #6B7280;
  
  /* Dimensions */
  --spacing-base: 4px;
  --spacing-large: 16px;

  /* Typography (Expanded from composite object) */
  --typography-body-font-family: Inter, sans-serif;
  --typography-body-font-size: 16px;
  --typography-body-font-weight: 400;
  --typography-body-line-height: 1.5;
  --typography-body-letter-spacing: 0px;
}

[v41e]

I strongly agree with this approach!

DESIGN.md should build on top of existing standards rather than trying to reinvent the wheel. To seamlessly connect the token standard and the markdown file, they need to share the exact same vocabulary. For example, if a token is defined as sys.light.primary in the tokens.json, we should be able to reference it using that exact same name in the DESIGN.md.

[AndrewOCC]

Agreed on the need for theming options! And would love to see the standard support token definitions from external files like tokens.json 😄

For my team's use case, we want an app to support multiple theme options, that affect different groups/design foundations. For example, a user, or app may want a dark theme for color, but squared off corners for rounding.

The available list of themes may look something like this, each affecting a different foundation:

themeState = {
  color: 'light' | 'dark'
  typography: 'marketing' | 'app'
  rounded: 'sharp' | 'soft'
  motion: 'bouncy' | 'professional'
}

In code, we do this by defining multiple JSON files, one for each foundation/token group. Those translate into multiple CSS files, which are enabled/disabled based on the current theme preference.

Keen to work out the best way to represent this, either via frontmatter or via linking to external files. Based on @craigsmitham's proposed structure, in frontmatter it may look something like this:

---
version: alpha
name: AcmeOrg
themes: { color: [light, dark], rounded: [sharp, soft]}
default-theme: light
colors:
  surface:    { light: "#ffffff", dark: "#1b1a18" }
  on-surface: { light: "#2a2825", dark: "#f3f0ec" }
rounded:
  small:  { sharp: '0px', soft: '4px' } 
  medium: { sharp: '2px', soft: '6px' } 
  large:  { sharp: '4px', soft: '8px' } 
---

Since the DTCG json format doesn't have a defined way of handling such themes, the approach would either be to recommend a format for encoding themes inside the DTCG format, or have a similar themes object that links to different json files:

---
version: alpha
name: AcmeOrg
themes: { color: ['./color/light.json', './color/dark.json'], rounded: ['./rounded/sharp.json', './rounded/soft.json']}
---

[davideast]

Just an update here, I'm running through all issues and PRs this week. This is at the top of the list.

[mvanhorn]

Took a pass at the endorsed inline modes shape in #128 - per-token { light, dark } values with per-mode resolution and Tailwind v4 export, additive and backward compatible. Scoped to the inline model only; extends/external-file sourcing left for a separate spec decision. bun test src/linter: 274 pass.