fix(tokens): stop tailwind-tokens.css self-referencing (breaks light mode where Tailwind theme output is unlayered)

[Shrinks99]

Problem

Importing @eqtylab/equality/theme-config.css left every token resolving to nothing in light mode in our docs site (Astro + Starlight + Tailwind v4). Dark mode was fine. Anything built on the tokens — including Equality's own <Button> — rendered unstyled.

Root cause

build-tokens.js generated tailwind-tokens.css as:

@theme inline {
  --color-background: var(--color-background); /* ...×260 */
}

Tailwind emits those into :root,:host, so the shipped CSS contains :root,:host { --color-background: var(--color-background) }. That declaration is cyclic → invalid at computed-value time, so the token computes to nothing.

Whether that dead declaration wins comes down to cascade layers, and that is decided by the consumer's build:

• Plain Vite/PostCSS apps (governance-studio, explorer, gateway): Tailwind's theme output lands inside @layer theme. Unlayered declarations always beat layered ones, so the real light values Equality scopes to html (unlayered) win. Light works — which is why this was invisible for so long.
• Starlight: @astrojs/starlight-tailwind ships its own top-level @theme {}; when Tailwind merges it, the emitted theme-variable block comes out unlayered. Now it's a pure specificity fight — :root (0,1,0) outranks html (0,0,1) — so the cycle wins and light collapses to nothing. Dark survives because html[data-equality-theme='dark'] (0,1,1) still wins.

This is not a Tailwind-version or import-style issue — verified that 4.1.18 / 4.2.1 / 4.3.3 all emit the block into @layer theme for a plain input, and it's the presence of starlight-tailwind's unlayered @theme that hoists it out.

Fix

Register the colour tokens in a non-inline @theme carrying their real light values, instead of @theme inline self-references:

@theme inline {
  --color-mixed-light: color-mix(...);   /* genuinely inline — needs per-element --mix-color */
  --color-mixed-dark:  color-mix(...);
}

@theme {
  --color-background: color(display-p3 1 1 1);   /* real value, no cycle */
  /* ...×260 */
}

• Utilities still compile to background-color: var(--color-background) — so consumer --color-* overrides (html-scoped and wrapper-scoped, e.g. governance-studio's brand tokens) are unchanged.
• The emitted :root,:host block now holds a plain value, so it's harmless whether it ends up layered or not.
• Dark keeps overriding via its more specific selector.

Diff is just the generator plus the regenerated tailwind-tokens.css.

Verification (headless Chrome, real built CSS, full 260-token theme-config)

Pipeline	Light	Dark	.bg-* utility	--color-* override
Starlight — TW 4.3.3 + starlight-tailwind (was broken)	✅ resolves	✅	✅	n/a
Plain Vite — TW 4.1.18 (governance-studio)	✅	✅	✅	✅ html + wrapper both win

Before the fix, the same Starlight probe returned empty custom properties in light; after, --color-background = color(display-p3 1 1 1), --color-text-primary = color(display-p3 0 0 0), --color-lilac-400 resolves, and the .bg-background utility computes correctly.

Downstream

• governance-platform-docs can drop its temporary relative deep-import workaround of dist/generated/color-vars.css once it bumps to the release containing this fix.
• governance-studio / explorer / gateway: no change required; their output and override behaviour are unaffected.

🤖 Generated with Claude Code