Theme Authoring

Both are supported and they answer different questions. Pick the first if your app has ONE brand; pick the second if a reader has to be able to switch.

Import the DS baseline, then declare the brand layer after it. Source order does not matter — the layer wins by cascade rule, not by specificity or position.

/* consumer's global.css */
@import "tailwindcss";
@import "@interlace/ui/styles/index.css";

@layer interlace.brand {
  :root {
    --interlace-primary: oklch(0.55 0.22 264);          /* your blue */
    --interlace-primary-foreground: #ffffff;
    --interlace-background: #ffffff;
    --interlace-foreground: #0a0a0f;
    --interlace-muted-foreground: #4a4458;              /* ≥4.5:1 on background */
    /* … the rest of the manifest */
  }

  .dark {
    --interlace-primary: oklch(0.78 0.18 264);
    --interlace-background: #0a0a0f;
    --interlace-foreground: #ededf2;
    --interlace-muted-foreground: #c4c0d4;
    /* … */
  }
}

The Interlace defaults were Tailwind violet until July 2026 and were repointed to burnt orange + green entirely inside this layer, with zero component edits. That is the whole claim, and it is why the layer — not the components — is the override surface. Full layer model: CSS contract.

A colour SCHEME and a THEME are different questions and must not share a selector. Until Phase 8 they did: [data-theme='dark'] meant dark mode, which spent the one obvious attribute for “which brand” on “which scheme” and left a second brand nowhere to go but a fork of the file.

.dark stays load-bearing on purpose: it is the shadcn / next-themes convention that every consumer and the Storybook decorator already write. The theme axis is purely additive.

A theme is a data file, not a pile of CSS: it supplies --interlace-* literals and nothing else. The semantic aliases (--background, --primary, the @theme inline registration) are owned by the DS and never change — that is the entire point of the cascade.

Every token below must appear in BOTH the light block and the dark block. Not because it is tidy: a missing token does not throw and does not warn. It resolves from whatever rule of lower specificity last matched — the previous theme, or this theme's other scheme — so the page renders 54surfaces in your brand and one in someone else's, and nobody files a bug because nobody can name what is wrong.

The list is not maintained by hand: it is derived from the :root block of interlace-theme.css, and the lock re-derives it on every run and fails if the two disagree.

/* 1. packages/ui/styles/themes/<name>.css */
@layer interlace.brand {
  [data-theme='<name>'] { /* … every token, light … */ }

  [data-theme='<name>'].dark,
  [data-theme='<name>'][data-scheme='dark'],
  [data-theme='<name>'] .dark,
  [data-theme='<name>'] [data-scheme='dark'] { /* … every token, dark … */ }
}

/* 2. packages/ui/styles/index.css — AFTER interlace-theme.css.
      Order is load-bearing: [data-theme='X'] and .dark are BOTH (0,1,0),
      so the tie is broken by source order. */
@import "./interlace-theme.css";
@import "./themes/<name>.css";

// 3. packages/ui/src/lib/theme-tokens.ts
export const THEMES = [
  /* … */
  { name: '<name>', label: '<Label>', description: '…', default: false },
] as const;

The registry is what the switcher renders and what the no-flash bootstrap validates against, so this third edit is not bookkeeping: without it, the theme exists in CSS and is unreachable — and with only it, the switcher offers a theme no stylesheet defines. The lock asserts the two lists agree.

Currently registered: interlace (default), harbor.

cd packages/ui && npx vitest run __tests__/theme-contract-lock.test.ts

Six ways it goes red, each of them a defect that is otherwise completely silent:

1. A missing token.It inherits the previous theme's value and ships a two-brand page.
2. An extra token. A typo is silent for exactly the same reason — --interlace-muted-forground is a perfectly valid custom property that nothing reads, and the real token keeps its inherited value.
3. A value it cannot parse. Hex, oklch(), a var() alias to another brand token, or a rem length. A token that is present but unreadable passes a completeness check and fails the user.
4. Text below 4.5:1, on any surface it actually paints. Over 20 pairs per theme × scheme — body copy, copy in a card, in a popover, on muted, every filled status chip, and text-primary on bg-primary/10, which is where a primary colour usually breaks.
5. Non-text UI below 3:1. The focus ring (SC 2.4.13) and control borders and chart axes (SC 1.4.11), measured on the page AND on a card.
6. A selector that moved. The lock matches the stylesheet's selectors exactly, including the subtree forms. If the matrix changes and the table in the test does not, it fails — rather than parsing an empty block and making every assertion above vacuous.

“It looks fine on my screen” is how #eae7e2 shipped as a form-control border at 1.23:1. Three layers measure instead, and they overlap on purpose:

• The palette. theme-contract-lockrecomputes every pair from the hex in your theme file on every run. The ratios written in a theme's header comment are a reader's convenience; the test is the authority, and it fails if the comments become fiction.
• The composites. composite-contrast-lock walks component source for tinted pairs (bg-primary/10 + text-primary) that no palette check can see.
• The rendered page. The storybook (a11y) CI gate runs axe over every story — and then re-runs the colour rules once per registered theme, at the scheme the story is in. The theme list there is discovered from the stylesheet that loaded, so your theme is swept the moment it is imported, with no edit to the gate.

To see resolved values rather than compute them, the semantics catalogue lists every semantic token with its light and dark value.

A theme applied after hydration is a repaint on every page load: the document paints the default, React mounts, an effect reads localStorage, and only then does the page become what the user chose. On a slow connection that is half a second of the wrong brand. No amount of correctness in the hook fixes it — by the time any React code runs, the wrong paint has already happened.

// app/layout.tsx — server component, no 'use client'
import { THEME_SCRIPT } from '@interlace/ui/theme-script';

<html lang="en" suppressHydrationWarning>
  <head>
    <script dangerouslySetInnerHTML={{ __html: THEME_SCRIPT }} />
  </head>

// anywhere in your chrome
import { ThemeSwitcher } from '@interlace/ui/theme-switcher';

<ThemeSwitcher size="sm" align="end" />

suppressHydrationWarning on <html> is required — the script deliberately mutates the element React is about to hydrate, which is the same thing next-themes asks for. The script is derived from the registry, so a theme added in step 4 needs no edit here.

Embedding previews in an iframe? The frame is a separate document: nothing about the page's palette crosses into it. Pass the theme explicitly — this site does it with Storybook's ?globals=interlaceTheme:<name> — or your previews will keep showing the default brand under a re-themed page.

interlace is not a theme file. It IS :root, and it is written as the ABSENCE of the attribute — there is no [data-theme='interlace'] selector anywhere. Choosing it removes the attribute rather than setting it, which keeps “no preference” and “chose the default” from becoming indistinguishable in the DOM.

The visible consequence is in the switcher: the obvious flourish — a dot per theme painted in that theme's own primary — cannot be done honestly. The dot would need [data-theme='X'] on itself, and for the default there is no such selector, so its swatch would paint in whatever theme is currently active. A dot that lies about which brand it represents is worse than no dot, so ThemeSwitcher ships check marks and the check carries the state.

Adding [data-theme='interlace'] as a :rootalias would fix it. It is a CONTRACT change, not a component change: the selector matrix, the manifest's provenance rule (the manifest is derived from the :rootblock), the lock's selector table and the stylesheet header all move together, or the lock goes red — by design.

• @layer interlace.preflight — the focus-ring + min-viewport baseline. Overriding it costs WCAG 2.2 SC 2.4.13.
• @layer interlace.bridge — fumadocs ↔ shadcn translation. Overriding it breaks cross-framework primitive resolution.
• @layer interlace.foundation— type scale + spacing scale + radius + container widths. These are structural; if you really need a different spacing scale you're forking the DS, not theming it.
• @layer interlace.semantics — a theme file that declares --background directly has bypassed the alias graph, and the next token added to the graph will not reach it. The lock refuses this outright.