No-flash theme bootstrap script

@interlace/ui — the inline `<head>` script that applies the stored theme before first paint. Without it every page load flashes the default theme.

foundationserverlibv1.0.1

No-flash theme bootstrap script — live renderutilities-theme-script--default ↗

Rendered from the story the storybook (a11y) CI gate runs axe against — the preview can't show something that hasn't been verified.

Install

Two equivalent paths — the URL works in any shadcn-CLI setup; the alias works once you've registered @interlace in your components.json.

Via shadcn URL

npx shadcn@latest add https://ds.interlace.tools/r/theme-script.json

With the @interlace alias

npx shadcn@latest add @interlace/theme-script

History

This component is at v1.0.1, first shipped in @interlace/ui 1.0.0. The version is stamped as a banner into the file the install writes, so the copy in your tree says which one you have — compare it with the number above before deciding whether to re-run the install.

No release note names this component yet. It shipped with the release above and has not changed since — see the full changelog for what moved elsewhere in the DS.

Import

3 named exports — pull the parts you need.

Public API

import { SCHEME_STORAGE_KEY, THEME_SCRIPT, THEME_STORAGE_KEY } from '@/lib/theme-script';

Accessibility

Every story for this component is rendered headlessly and checked with axe-core (wcag2aa, wcag22aa, best-practice, ACT) on every PR. That gate has no continue-on-error, so what ships has zero known violations.

What follows is what static analysis can see. Axe cannot press a key and never sees an overlay open, so the operable-without-a-mouse claim lives in Behavior instead, where the keyboard path is replayed step by step.

Focus + keyboard behaviour: Native element semantics — no interaction layer to get wrong.
Focus ring (WCAG 2.2 SC 2.4.13): Not focusable — no focus indicator required.
Reduced motion: No animation to gate.
ARIA in the source: None — semantics come from the element or the Base UI primitive rather than hand-written ARIA.

Dependencies

Base UI primitive: Native / no Base UI dependency
Lucide icons: none
NPM dependencies: none
Registry dependencies: @interlace/theme-tokens

Source

The full implementation — lib/theme-script.ts once installed.

123 lines · TypeScript

github ↗

import { DEFAULT_THEME, THEMES } from '@/lib/theme-tokens';

// @interlace/theme-script v1.0.1 — Interlace design system.
// Docs, props and live preview: https://ds.interlace.tools/c/theme-script
// What changed since: https://ds.interlace.tools/c/theme-script#history
// Generated banner — keep it, the upgrade diff reads this version.

/**
 * @interlace/ui — the no-flash theme bootstrap.
 *
 * A theme applied after hydration is a WHITE FLASH on every page load: the
 * document paints `:root` (Interlace · light) first, React mounts, an effect
 * reads localStorage, and only then does the page repaint into the dark or
 * re-branded palette the user actually chose. On a fast connection that is
 * one frame of the wrong colours; on a slow one it is half a second of a
 * blinding white page. It is the single most visible failure mode of a theme
 * system, and no amount of correctness in the hook fixes it — by the time
 * any React code runs, the wrong paint has already happened.
 *
 * The only fix is to write the DOM attributes BEFORE first paint, which means

…103 more lines…

Registry JSON

The raw registry record — what the shadcn CLI fetches.

/r/theme-script.json