themelia-ui 1.0.0

package/dist/styles/themes/default.css

@@ -0,0 +1,166 @@
+/*
+ * Theme — the swappable palette.
+ *
+ * GENERATED from scripts/theme-manifest.mjs by scripts/gen-theme.mjs.
+ * Do not hand-edit; edit the manifest and re-run `npm run tokens:theme`.
+ *
+ * This file owns only the shadcn-compatible contract: palette, radius, shadows, sidebar
+ * palette, and charts. Package state, layout, density, and component knobs live in
+ * styles/tokens/* and styles/theming/*.
+ *
+ * Every colour resolves through a primitive in styles/tokens/palette.css — there are no
+ * colour literals here — so a rebrand moves the ramp, not forty separate values.
+ */
+/*
+ * Raw inputs — `:root` ONLY, so a consumer's override inherits everywhere
+ * instead of being restated (and overwritten) at each scope boundary.
+ */
+:root {
+	--radius: 0.625rem; /* Base shadcn corner radius from which package radii derive. */
+	--border-width: 1px; /* Default hairline weight for dividers, outlines, and control borders. */
+	--border-width-strong: 2px; /* Emphasized rail weight for quote bars and active navigation indicators. */
+	--radius-pill: 999px; /* Fully rounded ends for pills, switches, and avatars. */
+}
+
+:root,
+[data-ui-scope],
+[data-density],
+[data-theme],
+.light {
+	--radius-sm: calc(var(--radius) * 0.6);
+	--radius-md: calc(var(--radius) * 0.8);
+	--radius-lg: var(--radius);
+	--radius-xl: calc(var(--radius) * 1.4);
+	--radius-2xl: calc(var(--radius) * 1.8);
+	--radius-3xl: calc(var(--radius) * 2.2);
+	--radius-4xl: calc(var(--radius) * 2.6);
+	--background: var(--neutral-0); /* Application canvas and default page background. */
+	--foreground: var(--neutral-800); /* Primary text and icon color on the application canvas. */
+	--card: var(--neutral-0); /* Card and framed content-surface background. */
+	--card-foreground: var(--neutral-800); /* Primary text and icons on card surfaces. */
+	--popover: var(--background); /* Popover, menu, select, and transient-surface background. */
+	--popover-foreground: var(--foreground); /* Primary text and icons on popover surfaces. */
+	--primary: var(--brand-600); /* Brand and primary-action color. */
+	--primary-foreground: var(--neutral-50); /* Text and icons on solid primary fills. */
+	--secondary: var(--neutral-100); /* Neutral secondary-control and supporting-surface fill. */
+	--secondary-foreground: var(--neutral-900); /* Text and icons on secondary fills. */
+	--muted: var(--neutral-100); /* Subdued backgrounds for passive regions and skeletons. */
+	--muted-foreground: var(--neutral-550); /* Secondary text, metadata, and passive icons. */
+	--accent: var(--neutral-100); /* Hover, selected-row, and emphasized neutral fill. */
+	--accent-foreground: var(--neutral-900); /* Text and icons on accent fills. */
+	--destructive: var(--danger-600); /* Destructive action, error, and invalid-state color. */
+	--destructive-foreground: var(--neutral-25); /* Text and icons on solid destructive fills. */
+	--border: var(--neutral-200); /* Default divider, outline, and surface-border color. */
+	--input: var(--neutral-200); /* Default form-control border color. */
+	--ring: var(--neutral-400); /* Focus-visible ring and outline color. */
+	--chart-1: var(--series-1); /* First categorical chart-series color; never a status color. */
+	--chart-2: var(--series-2); /* Second categorical chart-series color; never a status color. */
+	--chart-3: var(--series-3); /* Third categorical chart-series color; never a status color. */
+	--chart-4: var(--series-4); /* Fourth categorical chart-series color; never a status color. */
+	--chart-5: var(--series-5); /* Fifth categorical chart-series color; never a status color. */
+	--radius-surface: var(--radius-lg); /* Panels, cards, dialogs, and other framed surfaces. */
+	--radius-control: var(--radius-md); /* Buttons, inputs, and other interactive controls. */
+	--radius-inner: var(--radius-sm); /* Elements nested inside a control, which must read as tighter than it. */
+	--sidebar: var(--neutral-150); /* Sidebar shell background. */
+	--sidebar-foreground: var(--neutral-800); /* Primary sidebar text and icon color. */
+	--sidebar-primary: var(--neutral-900); /* Strong sidebar selection or primary action fill. */
+	--sidebar-primary-foreground: var(--neutral-50); /* Text and icons on sidebar primary fills. */
+	--sidebar-accent: var(--neutral-75); /* Sidebar hover and selected-row neutral fill. */
+	--sidebar-accent-foreground: var(--neutral-900); /* Text and icons on sidebar accent fills. */
+	--sidebar-border: var(--neutral-200); /* Sidebar dividers and shell border. */
+	--sidebar-ring: var(--neutral-400); /* Focus-visible ring inside the sidebar. */
+	--shadow-ink: var(--pure-black); /* Ink every elevation tier tints with. */
+	--shadow-2xs: 0 1px 3px 0px color-mix(in oklab, var(--shadow-ink) 5%, transparent); /* Minimal elevation for compact controls. */
+	--shadow-xs: 0 1px 3px 0px color-mix(in oklab, var(--shadow-ink) 5%, transparent); /* Extra-small elevation for controls and rows. */
+	--shadow-sm: 0 1px 3px 0px color-mix(in oklab, var(--shadow-ink) 10%, transparent), 0 1px 2px -1px color-mix(in oklab, var(--shadow-ink) 10%, transparent); /* Small elevation for raised controls and cards. */
+	--shadow: 0 1px 3px 0px color-mix(in oklab, var(--shadow-ink) 10%, transparent), 0 1px 2px -1px color-mix(in oklab, var(--shadow-ink) 10%, transparent); /* Default elevation for framed content. */
+	--shadow-md: 0 1px 3px 0px color-mix(in oklab, var(--shadow-ink) 10%, transparent), 0 2px 4px -1px color-mix(in oklab, var(--shadow-ink) 10%, transparent); /* Medium elevation for floating surfaces. */
+	--shadow-lg: 0 1px 3px 0px color-mix(in oklab, var(--shadow-ink) 10%, transparent), 0 4px 6px -1px color-mix(in oklab, var(--shadow-ink) 10%, transparent); /* Large elevation for menus, dialogs, and popovers. */
+	--shadow-xl: 0 1px 3px 0px color-mix(in oklab, var(--shadow-ink) 10%, transparent), 0 8px 10px -1px color-mix(in oklab, var(--shadow-ink) 10%, transparent); /* Extra-large elevation for prominent overlays. */
+	--shadow-2xl: 0 1px 3px 0px color-mix(in oklab, var(--shadow-ink) 25%, transparent); /* Maximum elevation for exceptional floating surfaces. */
+}
+
+/*
+ * Dark theme — overrides only.
+ *
+ * Every token not listed here inherits its light value through the cascade, which is
+ * declared explicitly as `inherits: true` in scripts/theme-manifest.mjs rather than
+ * left to chance. GENERATED: edit the manifest, then run `npm run tokens:theme`.
+ */
+.dark,
+[data-theme="dark"] {
+	--background: var(--neutral-800);
+	--foreground: var(--neutral-50);
+	--card: var(--neutral-900);
+	--card-foreground: var(--neutral-50);
+	--popover: var(--background);
+	--popover-foreground: var(--foreground);
+	--primary: var(--brand-350);
+	--primary-foreground: var(--brand-950);
+	--secondary: var(--neutral-850);
+	--secondary-foreground: var(--neutral-50);
+	--muted: var(--neutral-850);
+	--muted-foreground: var(--neutral-400);
+	--accent: var(--neutral-700);
+	--accent-foreground: var(--neutral-50);
+	--destructive: var(--danger-400);
+	--destructive-foreground: var(--danger-950);
+	--border: var(--white-a10);
+	--input: var(--white-a15);
+	--ring: var(--neutral-500);
+	--chart-1: var(--series-1-dark);
+	--chart-2: var(--series-2-dark);
+	--chart-3: var(--series-3-dark);
+	--chart-4: var(--series-4-dark);
+	--chart-5: var(--series-5-dark);
+	--sidebar: var(--neutral-900);
+	--sidebar-foreground: var(--neutral-50);
+	--sidebar-primary: var(--violet-500);
+	--sidebar-accent: var(--neutral-800);
+	--sidebar-accent-foreground: var(--neutral-50);
+	--sidebar-border: var(--white-a10);
+	--sidebar-ring: var(--neutral-500);
+}
+
+/*
+ * The same values under the OS preference, for `colorScheme: "system"`.
+ *
+ * Emitted rather than hand-written so it cannot drift from the block above.
+ */
+@media (prefers-color-scheme: dark) {
+	:root:not([data-theme="light"]),
+	[data-ui-scope]:not([data-theme="light"]),
+	[data-density]:not([data-theme="light"]) {
+		--background: var(--neutral-800);
+		--foreground: var(--neutral-50);
+		--card: var(--neutral-900);
+		--card-foreground: var(--neutral-50);
+		--popover: var(--background);
+		--popover-foreground: var(--foreground);
+		--primary: var(--brand-350);
+		--primary-foreground: var(--brand-950);
+		--secondary: var(--neutral-850);
+		--secondary-foreground: var(--neutral-50);
+		--muted: var(--neutral-850);
+		--muted-foreground: var(--neutral-400);
+		--accent: var(--neutral-700);
+		--accent-foreground: var(--neutral-50);
+		--destructive: var(--danger-400);
+		--destructive-foreground: var(--danger-950);
+		--border: var(--white-a10);
+		--input: var(--white-a15);
+		--ring: var(--neutral-500);
+		--chart-1: var(--series-1-dark);
+		--chart-2: var(--series-2-dark);
+		--chart-3: var(--series-3-dark);
+		--chart-4: var(--series-4-dark);
+		--chart-5: var(--series-5-dark);
+		--sidebar: var(--neutral-900);
+		--sidebar-foreground: var(--neutral-50);
+		--sidebar-primary: var(--violet-500);
+		--sidebar-accent: var(--neutral-800);
+		--sidebar-accent-foreground: var(--neutral-50);
+		--sidebar-border: var(--white-a10);
+		--sidebar-ring: var(--neutral-500);
+	}
+}

package/dist/styles/theming/animation.css

@@ -0,0 +1,207 @@
+/*
+ * RAW INPUTS — `:root` only. See styles/SCOPES.md for why derived tokens are the opposite.
+ *
+ * A literal restated at every scope boundary cannot be overridden from `:root`: the nearest
+ * declaring ancestor wins, and every provider, density and theme element is one. Measured
+ * rather than assumed — a `:root` override of these read back as the override at the root
+ * and as the kit's own value inside `[data-ui-scope]`. Declared once here, an override
+ * reaches every scope; setting one ON a scope still works, because the derived tokens
+ * below re-resolve at each boundary.
+ */
+:root {
+	/* Neutral defaults — a surface overrides only the axis it animates. */
+	--enter-opacity: 1;
+	--enter-scale: 1;
+	--enter-translate-x: 0;
+	--enter-translate-y: 0;
+	--exit-opacity: 1;
+	--exit-scale: 1;
+	--exit-translate-x: 0;
+	--exit-translate-y: 0;
+
+	/* Looping animations, exposed the same way and for the same scoping reason. */
+	--animate-spin: spin 1s linear infinite;
+	--animate-ping: ping 1s cubic-bezier(0, 0, 0.2, 1) infinite;
+	/* An expanding halo — a live location on a map, a recording indicator. */
+
+	/*
+	 * Slide distances. `slide-in-from-*-2` (0.5rem) is the common nudge for menus and
+	 * popovers; the -10 and -52 tiers upstream are sheet and drawer travel.
+	 */
+	--slide-nudge: 0.5rem;
+	--slide-panel: 2.5rem;
+}
+
+/*
+ * Animation.
+ *
+ * ── The largest gap left by dropping Tailwind ───────────────────────────────────────
+ * The source kit contains no `@keyframes` at all. Every animation came from Tailwind
+ * plus `tailwindcss-animate`: `animate-spin` (25 uses), `animate-pulse` (8),
+ * `animate-in` / `animate-out` (42), and their 100+ companion modifiers — `fade-in-0`,
+ * `zoom-in-95`, `slide-in-from-top-2`. Without them every spinner, skeleton, popover,
+ * menu, dialog, and drawer loses its motion.
+ *
+ * ── The enter/exit mechanism ────────────────────────────────────────────────────────
+ * `tailwindcss-animate` uses one parameterised keyframe pair rather than a keyframe per
+ * combination, and that design is worth keeping: a surface composes its own entrance by
+ * setting only the variables it cares about.
+ *
+ *   .content {
+ *     animation: var(--animate-exit);
+ *     --enter-opacity: 0;
+ *     --enter-scale: 0.95;
+ *   }
+ *   .content[data-open] { animation: var(--animate-enter); }
+ *
+ * Unset variables fall back to the neutral value, so `--enter-opacity: 0` alone gives a
+ * plain fade with no transform.
+ *
+ * Base UI drives open/close through `data-open` / `data-closed` and the
+ * `data-starting-style` / `data-ending-style` attributes, which is what the ported
+ * components hook rather than a `data-[state]` prop.
+ */
+/*
+ * Declared at every scope boundary, not at `:root`. A custom property's var()
+ * references resolve where the property is DECLARED, so a single `:root` block
+ * freezes these at root values and scoped density/theming silently do nothing.
+ * See styles/SCOPES.md.
+ */
+:root,
+[data-ui-scope],
+[data-density],
+[data-theme],
+.light,
+.dark {
+		/*
+		 * Composed here rather than written out in each module, and not only for brevity:
+		 * CSS Modules scopes `@keyframes` NAMES, so an `animation: enter …` shorthand written
+		 * inside a .module.css is rewritten to a scoped name that does not exist, and the
+		 * animation silently never runs. Referencing the whole shorthand through a variable
+		 * defined in this global sheet sidesteps that rewrite.
+		 *
+		 * To change the SPEED, a module overrides `animation-duration` as a longhand AFTER
+		 * the shorthand — not by redefining a variable used inside these values. A custom
+		 * property's `var()` references are substituted where the property is DECLARED, so
+		 * the duration below is already resolved to --duration-fast by the time any
+		 * descendant inherits it; overriding that variable further down has no effect.
+		 */
+		--animate-enter: enter var(--duration-fast) var(--ease-out);
+		--animate-exit: exit var(--duration-fast) cubic-bezier(0.4, 0, 1, 1);
+		--animate-pulse: pulse 2s var(--ease-in-out) infinite;
+}
+
+@keyframes enter {
+	from {
+		opacity: var(--enter-opacity);
+		transform: translate3d(var(--enter-translate-x), var(--enter-translate-y), 0)
+			scale3d(var(--enter-scale), var(--enter-scale), var(--enter-scale));
+	}
+}
+
+@keyframes exit {
+	to {
+		opacity: var(--exit-opacity);
+		transform: translate3d(var(--exit-translate-x), var(--exit-translate-y), 0)
+			scale3d(var(--exit-scale), var(--exit-scale), var(--exit-scale));
+	}
+}
+
+/* Indeterminate progress — spinners and loader buttons. */
+@keyframes spin {
+	to {
+		transform: rotate(360deg);
+	}
+}
+
+/* An expanding, fading halo. Paired with a solid dot that stays put. */
+@keyframes ping {
+	75%,
+	100% {
+		transform: scale(2);
+		opacity: 0;
+	}
+}
+
+/* Skeleton placeholders. */
+@keyframes pulse {
+	50% {
+		opacity: 0.5;
+	}
+}
+
+/*
+ * ── Native top-layer surfaces ───────────────────────────────────────────────────────
+ * Dialog, alert dialog, sheet, and drawer animate with transitions plus `@starting-style`
+ * rather than the keyframe pair above. A top-layer element is removed the instant
+ * `close()` runs, so an exit KEYFRAME never gets to render; transitioning `overlay` and
+ * `display` with `allow-discrete` is what holds the element in the top layer long enough
+ * to animate out.
+ *
+ * `@starting-style` supplies the "before it existed" values for the entrance, which
+ * keyframes cannot express for an element entering the top layer.
+ *
+ * Where this is unsupported (~9% of users in 2026) the surface appears and disappears
+ * instantly — no layout breakage, just no motion.
+ */
+
+/* Determinate-looking progress for indeterminate bars. */
+@keyframes progress-indeterminate {
+	from {
+		transform: translateX(-100%);
+	}
+	to {
+		transform: translateX(100%);
+	}
+}
+
+/*
+ * Motion is decorative here: a spinner that does not spin still reads as "busy" beside
+ * its label, and a popover that appears instantly is still usable. Honouring the user's
+ * preference costs nothing.
+ */
+@media (prefers-reduced-motion: reduce) {
+	:root {
+		--animate-enter: none;
+		--animate-exit: none;
+	}
+
+	/*
+	 * The sweep is load-bearing, not belt-and-braces: zeroing the duration TOKENS stops
+	 * everything written against them, and leaves what is not — a spinner's 0.7s ring, a
+	 * skeleton's 2s pulse, a progress bar's 1.2s indeterminate crawl, and any third-party
+	 * stylesheet the kit does not own. Removing this block leaves nineteen things moving.
+	 *
+	 * `0s` for animations and `0.01ms` for transitions, which is not a typo. The familiar
+	 * snippet uses the near-zero value for both so the end events still fire, and that is
+	 * true of TRANSITIONS: a `0s` transition fires no `transitionend`, and a library waiting
+	 * on one waits forever. Animations are the other way round — a `0s` animation fires
+	 * `animationstart` and `animationend` immediately, verified here rather than assumed.
+	 *
+	 * The near-zero value cost something: Base UI reads the panel's computed style to decide
+	 * whether it is animating or transitioning, and `0.01ms` counts as a duration, so it saw
+	 * both and warned on every Collapsible and Accordion — but only for a reader with the
+	 * preference on, which is why the console sweeps never met it.
+	 */
+	*,
+	*::before,
+	*::after {
+		animation-duration: 0s !important;
+		animation-iteration-count: 1 !important;
+		transition-duration: 0.01ms !important;
+	}
+}
+
+/*
+ * The band travels from right to left across a background sized to twice the element, so
+ * the highlight crosses the text once per cycle.
+ */
+@keyframes shimmer-sweep {
+	from {
+		background-position: 200% 0;
+	}
+
+	to {
+		background-position: -200% 0;
+	}
+}

package/dist/styles/theming/breakpoints.css

@@ -0,0 +1,48 @@
+/*
+ * Breakpoints and container sizes.
+ *
+ * ── Why these are @custom-media, not custom properties ──────────────────────────────
+ * A media query condition cannot read `var()` — `@media (min-width: var(--bp-md))` is
+ * invalid CSS and silently never matches. So responsive breakpoints are the one part of
+ * the system that cannot be a runtime variable. `@custom-media` keeps a single source of
+ * truth anyway, resolved at build time by the plugin in vite.config.ts.
+ *
+ * Usage in a module:
+ *
+ *   @media (--bp-md) { .root { … } }
+ *   @container card-header (--cq-xl) { .title { … } }
+ *
+ * Values are Tailwind v4's defaults, because 531 responsive modifiers across the source
+ * kit were authored against them and changing one would move every layout.
+ */
+
+/* Viewport — min-width, mobile-first. 232 `sm:`, 150 `md:`, 119 `lg:` uses upstream. */
+@custom-media --bp-sm (min-width: 40rem);
+@custom-media --bp-md (min-width: 48rem);
+@custom-media --bp-lg (min-width: 64rem);
+@custom-media --bp-xl (min-width: 80rem);
+@custom-media --bp-2xl (min-width: 96rem);
+
+/* Viewport — max-width, for the 13 `max-sm:` uses. Offset so the ranges never overlap. */
+@custom-media --bp-max-sm (max-width: 39.999rem);
+@custom-media --bp-max-md (max-width: 47.999rem);
+@custom-media --bp-max-lg (max-width: 63.999rem);
+
+/* The one arbitrary breakpoint the kit reaches for, named so it stops being arbitrary. */
+@custom-media --bp-compact-grid (min-width: 480px);
+
+/*
+ * Container query sizes. Used with a named container, e.g.
+ * `@container metric-bar (--cq-xl)`. Values match Tailwind's container scale.
+ */
+@custom-media --cq-3xs (min-width: 16rem);
+@custom-media --cq-2xs (min-width: 18rem);
+@custom-media --cq-xs (min-width: 20rem);
+@custom-media --cq-sm (min-width: 24rem);
+@custom-media --cq-md (min-width: 28rem);
+@custom-media --cq-lg (min-width: 32rem);
+@custom-media --cq-xl (min-width: 36rem);
+@custom-media --cq-2xl (min-width: 42rem);
+@custom-media --cq-3xl (min-width: 48rem);
+@custom-media --cq-4xl (min-width: 56rem);
+@custom-media --cq-5xl (min-width: 64rem);

package/dist/styles/theming/colors.css

@@ -0,0 +1,90 @@
+/*
+ * Alpha ladder — the global colour wiring layer.
+ *
+ * GENERATED by scripts/gen-alpha-ladder.mjs from the source kit's real usage.
+ * Do not hand-edit; re-run the generator instead.
+ *
+ * Every colour/alpha pair the components actually use, declared once. Modules
+ * reference `var(--border-60)` rather than repeating color-mix() inline, which
+ * gives consumers a single override point per pair and keeps modules value-free.
+ *
+ * `color-mix(in oklab, …)` is exactly what Tailwind v4 emits for `/nn` opacity,
+ * so the rendered colour is identical to the source implementation.
+ *
+ * 143 pairs across 22 colours.
+ *
+ * Declared at every scope boundary rather than `:root`, so a scope that rethemes a colour
+ * re-derives its whole ladder. See styles/SCOPES.md.
+ */
+:root,
+[data-ui-scope],
+[data-density],
+[data-theme],
+.light,
+.dark {
+
+	--border-50: color-mix(in oklab, var(--border) 50%, transparent);
+	--border-60: color-mix(in oklab, var(--border) 60%, transparent);
+	--border-70: color-mix(in oklab, var(--border) 70%, transparent);
+
+	--muted-20: color-mix(in oklab, var(--muted) 20%, transparent);
+	--muted-30: color-mix(in oklab, var(--muted) 30%, transparent);
+	--muted-35: color-mix(in oklab, var(--muted) 35%, transparent);
+	--muted-40: color-mix(in oklab, var(--muted) 40%, transparent);
+	--muted-50: color-mix(in oklab, var(--muted) 50%, transparent);
+	--muted-60: color-mix(in oklab, var(--muted) 60%, transparent);
+	--muted-80: color-mix(in oklab, var(--muted) 80%, transparent);
+
+	/* destructive — 13 steps, 127 uses */
+	--destructive-5: color-mix(in oklab, var(--destructive) 5%, transparent);
+	--destructive-10: color-mix(in oklab, var(--destructive) 10%, transparent);
+	--destructive-20: color-mix(in oklab, var(--destructive) 20%, transparent);
+	--destructive-30: color-mix(in oklab, var(--destructive) 30%, transparent);
+	--destructive-40: color-mix(in oklab, var(--destructive) 40%, transparent);
+	--destructive-50: color-mix(in oklab, var(--destructive) 50%, transparent);
+	--destructive-60: color-mix(in oklab, var(--destructive) 60%, transparent);
+
+	/* primary — 13 steps, 73 uses */
+	--primary-5: color-mix(in oklab, var(--primary) 5%, transparent);
+	--primary-10: color-mix(in oklab, var(--primary) 10%, transparent);
+	--primary-12: color-mix(in oklab, var(--primary) 12%, transparent);
+	--primary-15: color-mix(in oklab, var(--primary) 15%, transparent);
+	--primary-20: color-mix(in oklab, var(--primary) 20%, transparent);
+	--primary-25: color-mix(in oklab, var(--primary) 25%, transparent);
+	--primary-30: color-mix(in oklab, var(--primary) 30%, transparent);
+	--primary-40: color-mix(in oklab, var(--primary) 40%, transparent);
+
+	--ring-50: color-mix(in oklab, var(--ring) 50%, transparent);
+
+	--success-10: color-mix(in oklab, var(--success) 10%, transparent);
+	--success-15: color-mix(in oklab, var(--success) 15%, transparent);
+	--success-30: color-mix(in oklab, var(--success) 30%, transparent);
+
+	--foreground-8: color-mix(in oklab, var(--foreground) 8%, transparent);
+	--foreground-10: color-mix(in oklab, var(--foreground) 10%, transparent);
+	--foreground-20: color-mix(in oklab, var(--foreground) 20%, transparent);
+	--foreground-80: color-mix(in oklab, var(--foreground) 80%, transparent);
+
+	--muted-foreground-40: color-mix(in oklab, var(--muted-foreground) 40%, transparent);
+	--muted-foreground-70: color-mix(in oklab, var(--muted-foreground) 70%, transparent);
+
+	--warning-10: color-mix(in oklab, var(--warning) 10%, transparent);
+	--warning-20: color-mix(in oklab, var(--warning) 20%, transparent);
+	--warning-30: color-mix(in oklab, var(--warning) 30%, transparent);
+	--warning-40: color-mix(in oklab, var(--warning) 40%, transparent);
+	--warning-50: color-mix(in oklab, var(--warning) 50%, transparent);
+
+	/* info — 10 steps, 34 uses */
+	--info-5: color-mix(in oklab, var(--info) 5%, transparent);
+	--info-10: color-mix(in oklab, var(--info) 10%, transparent);
+	--info-15: color-mix(in oklab, var(--info) 15%, transparent);
+	--info-30: color-mix(in oklab, var(--info) 30%, transparent);
+	--info-40: color-mix(in oklab, var(--info) 40%, transparent);
+
+	--background-70: color-mix(in oklab, var(--background) 70%, transparent);
+	--background-80: color-mix(in oklab, var(--background) 80%, transparent);
+
+	/* input — 2 steps, 6 uses */
+	--input-30: color-mix(in oklab, var(--input) 30%, transparent);
+
+}

package/dist/styles/theming/feedback.css

@@ -0,0 +1,20 @@
+/*
+ * Feedback — Empty and Progress.
+ * Alert keeps its own contract in theming/alert.css.
+ */
+:root,
+[data-ui-scope],
+[data-density],
+[data-theme],
+.light,
+.dark {
+
+	/* Empty state — a centred, generous block, because it is the whole surface. */
+	/* Illustration internals — every part token-driven so they follow the theme. */
+	--empty-art-h: calc(6rem * var(--space-scale));
+
+	--alert-meta-label-fg: var(--muted-foreground);
+	/* The bar's colour. .toneSuccess/.toneWarning/.toneDestructive/.toneInfo re-point it. */
+	--progress-fill: var(--primary);
+
+}

package/dist/styles/theming/field.css

@@ -0,0 +1,38 @@
+/*
+ * RAW INPUTS — `:root` only. See styles/SCOPES.md for why derived tokens are the opposite.
+ *
+ * A literal restated at every scope boundary cannot be overridden from `:root`: the nearest
+ * declaring ancestor wins, and every provider, density and theme element is one. Measured
+ * rather than assumed — a `:root` override of these read back as the override at the root
+ * and as the kit's own value inside `[data-ui-scope]`. Declared once here, an override
+ * reaches every scope; setting one ON a scope still works, because the derived tokens
+ * below re-resolve at each boundary.
+ */
+:root {
+	--field-bg: transparent;
+
+	/* Label column for horizontal fields, so a settings page aligns down its controls. */
+	--field-label-width: 12rem;
+}
+
+/*
+ * Field — the shared contract every form control participates in.
+ *
+ * One set of tokens for input, textarea, select, and anything added
+ * later. Without this each control ends up with its own height, its own border colour, and
+ * its own focus ring, and they drift the moment one is touched — which is exactly what a
+ * row of mismatched controls looks like.
+ */
+:root,
+[data-ui-scope],
+[data-density],
+[data-theme],
+.light,
+.dark {
+		/* Surface */
+		--field-h: var(--control-h);
+		--field-px: calc(var(--control-x) * 0.8333333 * var(--space-scale));
+		--field-py: var(--space-xs);
+		--field-icon-lane: calc(var(--size-icon) + var(--space-md) * 2);
+		--field-addon-lane: calc(2.5rem * var(--density-scale));
+}

package/dist/styles/theming/focus.css

@@ -0,0 +1,102 @@
+/*
+ * RAW INPUTS — `:root` only. See styles/SCOPES.md for why derived tokens are the opposite.
+ *
+ * A literal restated at every scope boundary cannot be overridden from `:root`: the nearest
+ * declaring ancestor wins, and every provider, density and theme element is one. Measured
+ * rather than assumed — a `:root` override of these read back as the override at the root
+ * and as the kit's own value inside `[data-ui-scope]`. Declared once here, an override
+ * reaches every scope; setting one ON a scope still works, because the derived tokens
+ * below re-resolve at each boundary.
+ */
+:root {
+	--focus-ring-width: 3px;
+	--focus-ring-offset: 0px;
+
+	/* Disabled — `disabled:opacity-50`, 89 uses. */
+	--disabled-opacity: 0.5;
+}
+
+/*
+ * Focus — the global focus-ring wiring layer.
+ *
+ * `focus-visible` is the single most repeated pattern in the source kit (263 uses), and
+ * upstream every occurrence respelled the same ring as a cluster of utilities:
+ *
+ *   focus-visible:border-ring focus-visible:ring-3 focus-visible:ring-ring/30
+ *
+ * Tailwind compiled that to a box-shadow. Composing the shadow once here means a module
+ * writes `box-shadow: var(--focus-ring)` and a consumer retunes every focus state in the
+ * kit from one place — width, colour, and offset included.
+ *
+ * The invalid ring is the same construction over --destructive, used by the 76
+ * `aria-invalid:` occurrences.
+ */
+/*
+ * Declared at every scope boundary, not at `:root`. A custom property's var()
+ * references resolve where the property is DECLARED, so a single `:root` block
+ * freezes these at root values and scoped density/theming silently do nothing.
+ * See styles/SCOPES.md.
+ */
+:root,
+[data-ui-scope],
+[data-density],
+[data-theme],
+.light,
+.dark {
+		--focus-ring-color: color-mix(in oklab, var(--ring) 30%, transparent);
+
+		/* Composite ring. Offset renders as a same-coloured-as-surface inner spread. */
+		--focus-ring:
+			0 0 0 var(--focus-ring-offset) var(--background),
+			0 0 0 calc(var(--focus-ring-width) + var(--focus-ring-offset)) var(--focus-ring-color);
+
+		/*
+		 * The same ring drawn INSIDE the box, for a control whose ancestor clips.
+		 *
+		 * A box-shadow ring is painted outside the border box, so any ancestor with
+		 * `overflow: hidden` erases it — and a rounded surface that draws a header strip needs
+		 * exactly that overflow. Four AI-chat surfaces wrote `box-shadow: var(--focus-ring)`
+		 * on their trigger and painted between 0 and 2 pixels of it; the ring was in the
+		 * stylesheet and never on the screen.
+		 *
+		 * `inset var(--focus-ring)` is not the fix and looks like it is: the keyword applies to
+		 * the FIRST shadow layer only, so it insets the invisible backing layer and leaves the
+		 * visible one outside, still clipped. Both layers are restated here.
+		 */
+		--focus-ring-inset:
+			inset 0 0 0 var(--focus-ring-offset) var(--background),
+			inset 0 0 0 calc(var(--focus-ring-width) + var(--focus-ring-offset)) var(--focus-ring-color);
+
+		/* Invalid state — aria-invalid, 76 uses. */
+		--invalid-ring-color: var(--destructive-20);
+		--invalid-ring-border: var(--destructive);
+		--invalid-ring: 0 0 0 var(--focus-ring-width) var(--invalid-ring-color);
+}
+
+/*
+ * Dark theme deepens both rings: the light-theme alphas disappear against a dark surface.
+ * Mirrors the source kit's `dark:aria-invalid:ring-destructive/40`.
+ */
+.dark,
+[data-theme="dark"] {
+	--focus-ring-color: var(--ring-50);
+	--invalid-ring-color: var(--destructive-40);
+	--invalid-ring-border: var(--destructive-50);
+}
+
+/*
+ * The same values under the OS preference.
+ *
+ * A bare `.dark` block is DEAD whenever the theme comes from the system rather than an
+ * explicit class — which is what `colorScheme: "system"` does, and what the docs site
+ * itself runs. Both forms are needed, and `verify:dark-overrides` fails if they drift.
+ */
+@media (prefers-color-scheme: dark) {
+	:root:not([data-theme="light"]),
+	[data-ui-scope]:not([data-theme="light"]),
+	[data-density]:not([data-theme="light"]) {
+		--focus-ring-color: var(--ring-50);
+		--invalid-ring-color: var(--destructive-40);
+		--invalid-ring-border: var(--destructive-50);
+	}
+}