google-labs-code/design.md

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.

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**:

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

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

```yaml
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 inhe...

@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 theme...

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 intention...

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:

```yaml
---
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...