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.