@usetheo/ui 0.12.0 → 0.13.1

package/dist/themes/color.d.ts

@@ -0,0 +1,62 @@
+/**
+ * Color helpers for `ColorScale` and `defineTheme`.
+ *
+ * Post-T2.6 (community-best-practices alignment, ADR-0005): the canonical
+ * output format is OKLCH (`"oklch(L C H)"`). Built-in themes also use OKLCH
+ * after the T2.4 migration. The CSS regex (`COLOR_VALUE_PATTERN`) accepts
+ * both formats for backward compatibility — legacy themes pinned to the
+ * HSL split format keep working.
+ *
+ * Helpers:
+ *   - hex(input)      → "oklch(L C H)"  (NEW — primary path post-T2.6)
+ *   - rgb(r, g, b)    → "oklch(L C H)"  (NEW)
+ *   - hexToHsl(input) → "H S% L%"       (legacy — deprecated, kept 1 minor)
+ *   - rgbToHsl(...)   → "H S% L%"       (legacy — deprecated)
+ *
+ * Alpha channels are intentionally discarded — `ColorScale` is opaque;
+ * compose alpha in CSS via `color-mix(in oklch, var(--primary) 50%, transparent)`.
+ *
+ * Original plan: `.claude/knowledge-base/plans/theming-and-sizes-plan.md` T2.2.
+ * Updated by: `.claude/knowledge-base/plans/theo-ui-community-best-practices-alignment-plan.md` T2.6.
+ */
+/**
+ * Convert a hex color string to the HSL string-tuple format used by
+ * `ColorScale` ("`H S% L%`", e.g. `"262 83% 58%"`).
+ *
+ * Accepts `#rgb`, `#rgba`, `#rrggbb`, `#rrggbbaa`. Case-insensitive.
+ * Alpha bytes are silently dropped — use `hsl(var(--primary) / 0.5)`
+ * in CSS for transparency.
+ *
+ * @throws if the input is malformed.
+ *
+ * @example
+ *   hex("#A855F7")   // "oklch(0.628 0.225 296)"
+ *   hex("#a855f7")   // same — case-insensitive
+ *   hex("#abc")      // expanded to "#aabbcc"
+ */
+export declare function hex(input: string): string;
+/**
+ * Legacy helper that returns HSL string-tuple format (pre-T2.6).
+ *
+ * @deprecated Since 2026-06-03 — use `hex(input)` which returns OKLCH.
+ *   Kept for one minor cycle to avoid breaking consumers that authored
+ *   themes using the HSL split format. Both formats are accepted by
+ *   `ColorScale` and by `<ThemeProvider>` runtime validation.
+ */
+export declare function hexToHsl(input: string): string;
+/**
+ * Convert an RGB triplet (each in `[0, 255]`) to the HSL string-tuple
+ * format used by `ColorScale`.
+ *
+ * @throws if any channel is out of `[0, 255]`.
+ *
+ * @example
+ *   rgb(168, 85, 247)  // "oklch(0.628 0.225 296)"
+ */
+export declare function rgb(r: number, g: number, b: number): string;
+/**
+ * Legacy helper that returns HSL string-tuple format (pre-T2.6).
+ *
+ * @deprecated Since 2026-06-03 — use `rgb(r, g, b)` which returns OKLCH.
+ */
+export declare function rgbToHslLegacy(r: number, g: number, b: number): string;

package/dist/themes/define.d.ts

@@ -0,0 +1,65 @@
+/**
+ * `defineTheme(input)` — build a `Theme` from a partial override.
+ *
+ * Reduces the boilerplate of authoring a custom theme from 58 colour
+ * keys (`light` × 29 + `dark` × 29) to "just what you want to change".
+ * The merge always uses `violetForge` as the base — this is a pure,
+ * deterministic helper that does not depend on whatever theme is active
+ * at the call site.
+ *
+ * The `Theme` object it returns is drop-in compatible with
+ * `<ThemeProvider themes={[...]}>` — same shape as `violetForge`,
+ * `classicPaper`, and `auroraTerminal`.
+ *
+ * Honest caveat: if you override `light.primary` but NOT `dark.primary`,
+ * the two modes will use different colours — your override in light,
+ * Violet Forge's default in dark. That's intentional. Pass both sides
+ * to keep them in sync.
+ *
+ * @example
+ *   import { defineTheme, hex } from "@theokit/ui";
+ *   export const corp = defineTheme({
+ *     name: "corp",
+ *     light: { primary: hex("#0EA5E9") },
+ *     dark: { primary: hex("#38BDF8") },
+ *   });
+ *
+ * Plan: `.claude/knowledge-base/plans/theming-and-sizes-plan.md` T2.1.
+ */
+import type { ColorScale, Theme, ThemeFonts } from "./types.js";
+export interface DefineThemeInput {
+    /**
+     * Stable id used in `data-theme="<name>"` on the root element. Must
+     * match `/^[a-z][a-z0-9-]*$/i` (CSS-identifier-safe). Required.
+     */
+    name: string;
+    /**
+     * Human-readable label for theme switchers. Defaults to the
+     * capitalized version of `name` (e.g. "corp" → "Corp").
+     */
+    label?: string;
+    /** Optional one-line description shown in switchers. */
+    description?: string;
+    /**
+     * Override light-mode colours. Any key omitted is inherited from
+     * `violetForge.light`. See `ColorScale` for the full list.
+     */
+    light?: Partial<ColorScale>;
+    /**
+     * Override dark-mode colours. Any key omitted is inherited from
+     * `violetForge.dark`.
+     */
+    dark?: Partial<ColorScale>;
+    /**
+     * Override fonts (`display`, `body`, `mono`). Any key omitted is
+     * inherited from `violetForge.fonts`.
+     */
+    fonts?: Partial<ThemeFonts>;
+    /**
+     * Replace the default remote font URLs. Pass an empty array to skip
+     * font fetching entirely. Defaults to `violetForge.fontUrls` when
+     * omitted (so consumers that don't care still get Geist preloaded).
+     */
+    fontUrls?: string[];
+}
+export declare function defineTheme(input: DefineThemeInput): Theme;

package/dist/themes/density.d.ts

@@ -0,0 +1,17 @@
+export type Density = "compact" | "comfortable" | "spacious";
+export interface DensityContextValue {
+    density: Density;
+    setDensity: (next: Density) => void;
+}
+export declare const DensityContext: import("react").Context<DensityContextValue | undefined>;
+/**
+ * Inject (idempotent) the density CSS variable definitions into the document
+ * head. Returns true if the style tag was newly created. Safe to call on
+ * every ThemeProvider mount — duplicates are skipped.
+ */
+export declare function injectDensityCss(): boolean;
+/**
+ * Read the current density from the active ThemeProvider context. Throws
+ * outside the provider so misuse fails loud — analogous to `useTheme`.
+ */
+export declare function useDensity(): DensityContextValue;

package/dist/themes/dracula.d.ts

@@ -0,0 +1,14 @@
+import type { Theme } from "./types.js";
+/**
+ * Dracula — the cult OSS dark theme (https://draculatheme.com, MIT).
+ *
+ * Dark mode = canonical Dracula spec (background #282A36, signature pink
+ * #FF79C6, purple #BD93F9, etc.).
+ *
+ * Note: "light" mode is a Theo-original adaptation — Dracula upstream
+ * spec is dark-only. We darken the signature pink/purple to pass WCAG AA
+ * against light backgrounds, sacrificing palette purity for accessibility.
+ *
+ * Plan: .claude/knowledge-base/plans/seven-themes-plan.md T4.1
+ */
+export declare const dracula: Theme;

package/dist/themes/github-dark.d.ts

@@ -0,0 +1,11 @@
+import type { Theme } from "./types.js";
+/**
+ * GitHub Dark — GitHub's default dark theme.
+ *
+ * Based on the canonical Primer Primitives tokens
+ * (https://github.com/primer/primitives, MIT). Light fallback uses GitHub's
+ * "light-default" Primer scale.
+ *
+ * Plan: .claude/knowledge-base/plans/seven-themes-plan.md T3.1
+ */
+export declare const githubDark: Theme;

package/dist/themes/index.d.ts

@@ -0,0 +1,26 @@
+export type { ColorScale, Theme, ThemeFonts, ThemeMode } from "./types.js";
+export { ThemeProvider, useTheme } from "./theme-provider.js";
+export { ThemeScript } from "./theme-script.js";
+export { ThemeSwitcher } from "./theme-switcher.js";
+export { violetForge } from "./violet-forge.js";
+export { classicPaper } from "./classic-paper.js";
+export { auroraTerminal } from "./aurora-terminal.js";
+export { defineTheme, type DefineThemeInput } from "./define.js";
+export { hex, hexToHsl, rgb, rgbToHslLegacy } from "./color.js";
+export { useDensity, type Density, type DensityContextValue } from "./density.js";
+export { vercelMono } from "./vercel-mono.js";
+export { githubDark } from "./github-dark.js";
+export { dracula } from "./dracula.js";
+export { oneDark } from "./one-dark.js";
+export { anthropicStyle } from "./anthropic-style.js";
+export { openaiStyle } from "./openai-style.js";
+export { linearGlass } from "./linear-glass.js";
+/**
+ * All themes bundled with Theo UI. Pass to `<ThemeProvider themes={builtinThemes}>`
+ * if you want all 10 available out of the box.
+ *
+ * EC-4 note: passing the full 10-entry list triggers ~60 KB CSS injection in
+ * `<style id="theo-ui-theme-vars">`. For apps focused on 1-2 themes, prefer
+ * `themes={[violetForge, dracula]}` to keep the payload at ~12 KB.
+ */
+export declare const builtinThemes: import("./types.js").Theme[];

package/dist/themes/linear-glass.d.ts

@@ -0,0 +1,11 @@
+import type { Theme } from "./types.js";
+/**
+ * Linear Glass — linear.app-inspired glassy indigo.
+ *
+ * Inspired by, not affiliated with Linear. Refined indigo-violet primary
+ * (#5E6AD2) on near-black canvas in dark, pure white in light. Subtle
+ * glassmorphic surface temperature.
+ *
+ * Plan: .claude/knowledge-base/plans/seven-themes-plan.md T8.1
+ */
+export declare const linearGlass: Theme;

package/dist/themes/one-dark.d.ts

@@ -0,0 +1,11 @@
+import type { Theme } from "./types.js";
+/**
+ * One Dark / One Light — Atom's iconic syntax theme.
+ *
+ * Sources:
+ *   - atom/one-dark-syntax (MIT) — dark mode canonical
+ *   - atom/one-light-syntax (MIT) — light mode canonical
+ *
+ * Plan: .claude/knowledge-base/plans/seven-themes-plan.md T5.1
+ */
+export declare const oneDark: Theme;

package/dist/themes/openai-style.d.ts

@@ -0,0 +1,10 @@
+import type { Theme } from "./types.js";
+/**
+ * OpenAI-style — chatgpt.com-inspired minimal tech-utility.
+ *
+ * Inspired by, not affiliated with OpenAI. Pure white / charcoal canvas +
+ * signature ChatGPT green (#10A37F). Minimal saturation, high contrast.
+ *
+ * Plan: .claude/knowledge-base/plans/seven-themes-plan.md T7.1
+ */
+export declare const openaiStyle: Theme;

package/dist/themes/schema.d.ts

@@ -0,0 +1,112 @@
+/**
+ * Valibot schema for Theme — Phase 2 T2.7 / D5 (revised post-EC-6).
+ *
+ * Validates the shape and types of a Theme object passed to <ThemeProvider>
+ * or registerTheme(). Complements the COLOR_VALUE_PATTERN regex (the second
+ * defense layer against CSS injection): valibot validates shape; regex
+ * validates that each individual color value is safe to interpolate.
+ *
+ * Why valibot (not zod): valibot core is ~1.5KB gzipped vs zod ~12KB.
+ * <ThemeProvider> is a sync constructor — dynamic import does not tree-shake.
+ * For our use case (validating ~37 string fields) valibot is strictly
+ * better in bundle size and API parity.
+ *
+ * Output of safeParse → { success: true, output } or { success: false, issues }.
+ * formatThemeIssues() produces human-readable error message with the failing
+ * field path so consumers see what to fix.
+ */
+import * as v from "valibot";
+export declare const themeSchema: v.ObjectSchema<{
+    readonly name: v.SchemaWithPipe<[v.StringSchema<undefined>, v.CheckAction<string, "theme name must match /^[a-z][a-z0-9-]*$/ (lowercase + digits + hyphens, starts with a letter)">]>;
+    readonly label: v.StringSchema<undefined>;
+    readonly description: v.OptionalSchema<v.StringSchema<undefined>, never>;
+    readonly fonts: v.ObjectSchema<{
+        readonly display: v.SchemaWithPipe<[v.StringSchema<undefined>, v.CheckAction<string, "font family contains disallowed characters (parens, semicolons, etc.)">]>;
+        readonly body: v.SchemaWithPipe<[v.StringSchema<undefined>, v.CheckAction<string, "font family contains disallowed characters (parens, semicolons, etc.)">]>;
+        readonly mono: v.SchemaWithPipe<[v.StringSchema<undefined>, v.CheckAction<string, "font family contains disallowed characters (parens, semicolons, etc.)">]>;
+    }, undefined>;
+    readonly light: v.ObjectSchema<{
+        readonly background: v.SchemaWithPipe<[v.StringSchema<undefined>, v.CheckAction<string, "color value did not match the allowed format (hex, oklch, hsl, rgb, var(), HSL split, or CSS keyword)">]>;
+        readonly foreground: v.SchemaWithPipe<[v.StringSchema<undefined>, v.CheckAction<string, "color value did not match the allowed format (hex, oklch, hsl, rgb, var(), HSL split, or CSS keyword)">]>;
+        readonly card: v.SchemaWithPipe<[v.StringSchema<undefined>, v.CheckAction<string, "color value did not match the allowed format (hex, oklch, hsl, rgb, var(), HSL split, or CSS keyword)">]>;
+        readonly "card-foreground": v.SchemaWithPipe<[v.StringSchema<undefined>, v.CheckAction<string, "color value did not match the allowed format (hex, oklch, hsl, rgb, var(), HSL split, or CSS keyword)">]>;
+        readonly popover: v.SchemaWithPipe<[v.StringSchema<undefined>, v.CheckAction<string, "color value did not match the allowed format (hex, oklch, hsl, rgb, var(), HSL split, or CSS keyword)">]>;
+        readonly "popover-foreground": v.SchemaWithPipe<[v.StringSchema<undefined>, v.CheckAction<string, "color value did not match the allowed format (hex, oklch, hsl, rgb, var(), HSL split, or CSS keyword)">]>;
+        readonly primary: v.SchemaWithPipe<[v.StringSchema<undefined>, v.CheckAction<string, "color value did not match the allowed format (hex, oklch, hsl, rgb, var(), HSL split, or CSS keyword)">]>;
+        readonly "primary-deep": v.OptionalSchema<v.SchemaWithPipe<[v.StringSchema<undefined>, v.CheckAction<string, "color value did not match the allowed format (hex, oklch, hsl, rgb, var(), HSL split, or CSS keyword)">]>, never>;
+        readonly "primary-glow": v.OptionalSchema<v.SchemaWithPipe<[v.StringSchema<undefined>, v.CheckAction<string, "color value did not match the allowed format (hex, oklch, hsl, rgb, var(), HSL split, or CSS keyword)">]>, never>;
+        readonly "primary-foreground": v.SchemaWithPipe<[v.StringSchema<undefined>, v.CheckAction<string, "color value did not match the allowed format (hex, oklch, hsl, rgb, var(), HSL split, or CSS keyword)">]>;
+        readonly secondary: v.SchemaWithPipe<[v.StringSchema<undefined>, v.CheckAction<string, "color value did not match the allowed format (hex, oklch, hsl, rgb, var(), HSL split, or CSS keyword)">]>;
+        readonly "secondary-foreground": v.SchemaWithPipe<[v.StringSchema<undefined>, v.CheckAction<string, "color value did not match the allowed format (hex, oklch, hsl, rgb, var(), HSL split, or CSS keyword)">]>;
+        readonly accent: v.SchemaWithPipe<[v.StringSchema<undefined>, v.CheckAction<string, "color value did not match the allowed format (hex, oklch, hsl, rgb, var(), HSL split, or CSS keyword)">]>;
+        readonly "accent-deep": v.OptionalSchema<v.SchemaWithPipe<[v.StringSchema<undefined>, v.CheckAction<string, "color value did not match the allowed format (hex, oklch, hsl, rgb, var(), HSL split, or CSS keyword)">]>, never>;
+        readonly "accent-foreground": v.SchemaWithPipe<[v.StringSchema<undefined>, v.CheckAction<string, "color value did not match the allowed format (hex, oklch, hsl, rgb, var(), HSL split, or CSS keyword)">]>;
+        readonly muted: v.SchemaWithPipe<[v.StringSchema<undefined>, v.CheckAction<string, "color value did not match the allowed format (hex, oklch, hsl, rgb, var(), HSL split, or CSS keyword)">]>;
+        readonly "muted-foreground": v.SchemaWithPipe<[v.StringSchema<undefined>, v.CheckAction<string, "color value did not match the allowed format (hex, oklch, hsl, rgb, var(), HSL split, or CSS keyword)">]>;
+        readonly border: v.SchemaWithPipe<[v.StringSchema<undefined>, v.CheckAction<string, "color value did not match the allowed format (hex, oklch, hsl, rgb, var(), HSL split, or CSS keyword)">]>;
+        readonly input: v.SchemaWithPipe<[v.StringSchema<undefined>, v.CheckAction<string, "color value did not match the allowed format (hex, oklch, hsl, rgb, var(), HSL split, or CSS keyword)">]>;
+        readonly ring: v.SchemaWithPipe<[v.StringSchema<undefined>, v.CheckAction<string, "color value did not match the allowed format (hex, oklch, hsl, rgb, var(), HSL split, or CSS keyword)">]>;
+        readonly success: v.SchemaWithPipe<[v.StringSchema<undefined>, v.CheckAction<string, "color value did not match the allowed format (hex, oklch, hsl, rgb, var(), HSL split, or CSS keyword)">]>;
+        readonly "success-foreground": v.SchemaWithPipe<[v.StringSchema<undefined>, v.CheckAction<string, "color value did not match the allowed format (hex, oklch, hsl, rgb, var(), HSL split, or CSS keyword)">]>;
+        readonly warning: v.SchemaWithPipe<[v.StringSchema<undefined>, v.CheckAction<string, "color value did not match the allowed format (hex, oklch, hsl, rgb, var(), HSL split, or CSS keyword)">]>;
+        readonly "warning-foreground": v.SchemaWithPipe<[v.StringSchema<undefined>, v.CheckAction<string, "color value did not match the allowed format (hex, oklch, hsl, rgb, var(), HSL split, or CSS keyword)">]>;
+        readonly destructive: v.SchemaWithPipe<[v.StringSchema<undefined>, v.CheckAction<string, "color value did not match the allowed format (hex, oklch, hsl, rgb, var(), HSL split, or CSS keyword)">]>;
+        readonly "destructive-foreground": v.SchemaWithPipe<[v.StringSchema<undefined>, v.CheckAction<string, "color value did not match the allowed format (hex, oklch, hsl, rgb, var(), HSL split, or CSS keyword)">]>;
+        readonly info: v.SchemaWithPipe<[v.StringSchema<undefined>, v.CheckAction<string, "color value did not match the allowed format (hex, oklch, hsl, rgb, var(), HSL split, or CSS keyword)">]>;
+        readonly "info-foreground": v.SchemaWithPipe<[v.StringSchema<undefined>, v.CheckAction<string, "color value did not match the allowed format (hex, oklch, hsl, rgb, var(), HSL split, or CSS keyword)">]>;
+        readonly "status-online": v.SchemaWithPipe<[v.StringSchema<undefined>, v.CheckAction<string, "color value did not match the allowed format (hex, oklch, hsl, rgb, var(), HSL split, or CSS keyword)">]>;
+        readonly "status-online-foreground": v.SchemaWithPipe<[v.StringSchema<undefined>, v.CheckAction<string, "color value did not match the allowed format (hex, oklch, hsl, rgb, var(), HSL split, or CSS keyword)">]>;
+        readonly "status-offline": v.SchemaWithPipe<[v.StringSchema<undefined>, v.CheckAction<string, "color value did not match the allowed format (hex, oklch, hsl, rgb, var(), HSL split, or CSS keyword)">]>;
+        readonly "status-offline-foreground": v.SchemaWithPipe<[v.StringSchema<undefined>, v.CheckAction<string, "color value did not match the allowed format (hex, oklch, hsl, rgb, var(), HSL split, or CSS keyword)">]>;
+        readonly "status-degraded": v.SchemaWithPipe<[v.StringSchema<undefined>, v.CheckAction<string, "color value did not match the allowed format (hex, oklch, hsl, rgb, var(), HSL split, or CSS keyword)">]>;
+        readonly "status-degraded-foreground": v.SchemaWithPipe<[v.StringSchema<undefined>, v.CheckAction<string, "color value did not match the allowed format (hex, oklch, hsl, rgb, var(), HSL split, or CSS keyword)">]>;
+        readonly "status-info": v.SchemaWithPipe<[v.StringSchema<undefined>, v.CheckAction<string, "color value did not match the allowed format (hex, oklch, hsl, rgb, var(), HSL split, or CSS keyword)">]>;
+        readonly "status-info-foreground": v.SchemaWithPipe<[v.StringSchema<undefined>, v.CheckAction<string, "color value did not match the allowed format (hex, oklch, hsl, rgb, var(), HSL split, or CSS keyword)">]>;
+    }, undefined>;
+    readonly dark: v.ObjectSchema<{
+        readonly background: v.SchemaWithPipe<[v.StringSchema<undefined>, v.CheckAction<string, "color value did not match the allowed format (hex, oklch, hsl, rgb, var(), HSL split, or CSS keyword)">]>;
+        readonly foreground: v.SchemaWithPipe<[v.StringSchema<undefined>, v.CheckAction<string, "color value did not match the allowed format (hex, oklch, hsl, rgb, var(), HSL split, or CSS keyword)">]>;
+        readonly card: v.SchemaWithPipe<[v.StringSchema<undefined>, v.CheckAction<string, "color value did not match the allowed format (hex, oklch, hsl, rgb, var(), HSL split, or CSS keyword)">]>;
+        readonly "card-foreground": v.SchemaWithPipe<[v.StringSchema<undefined>, v.CheckAction<string, "color value did not match the allowed format (hex, oklch, hsl, rgb, var(), HSL split, or CSS keyword)">]>;
+        readonly popover: v.SchemaWithPipe<[v.StringSchema<undefined>, v.CheckAction<string, "color value did not match the allowed format (hex, oklch, hsl, rgb, var(), HSL split, or CSS keyword)">]>;
+        readonly "popover-foreground": v.SchemaWithPipe<[v.StringSchema<undefined>, v.CheckAction<string, "color value did not match the allowed format (hex, oklch, hsl, rgb, var(), HSL split, or CSS keyword)">]>;
+        readonly primary: v.SchemaWithPipe<[v.StringSchema<undefined>, v.CheckAction<string, "color value did not match the allowed format (hex, oklch, hsl, rgb, var(), HSL split, or CSS keyword)">]>;
+        readonly "primary-deep": v.OptionalSchema<v.SchemaWithPipe<[v.StringSchema<undefined>, v.CheckAction<string, "color value did not match the allowed format (hex, oklch, hsl, rgb, var(), HSL split, or CSS keyword)">]>, never>;
+        readonly "primary-glow": v.OptionalSchema<v.SchemaWithPipe<[v.StringSchema<undefined>, v.CheckAction<string, "color value did not match the allowed format (hex, oklch, hsl, rgb, var(), HSL split, or CSS keyword)">]>, never>;
+        readonly "primary-foreground": v.SchemaWithPipe<[v.StringSchema<undefined>, v.CheckAction<string, "color value did not match the allowed format (hex, oklch, hsl, rgb, var(), HSL split, or CSS keyword)">]>;
+        readonly secondary: v.SchemaWithPipe<[v.StringSchema<undefined>, v.CheckAction<string, "color value did not match the allowed format (hex, oklch, hsl, rgb, var(), HSL split, or CSS keyword)">]>;
+        readonly "secondary-foreground": v.SchemaWithPipe<[v.StringSchema<undefined>, v.CheckAction<string, "color value did not match the allowed format (hex, oklch, hsl, rgb, var(), HSL split, or CSS keyword)">]>;
+        readonly accent: v.SchemaWithPipe<[v.StringSchema<undefined>, v.CheckAction<string, "color value did not match the allowed format (hex, oklch, hsl, rgb, var(), HSL split, or CSS keyword)">]>;
+        readonly "accent-deep": v.OptionalSchema<v.SchemaWithPipe<[v.StringSchema<undefined>, v.CheckAction<string, "color value did not match the allowed format (hex, oklch, hsl, rgb, var(), HSL split, or CSS keyword)">]>, never>;
+        readonly "accent-foreground": v.SchemaWithPipe<[v.StringSchema<undefined>, v.CheckAction<string, "color value did not match the allowed format (hex, oklch, hsl, rgb, var(), HSL split, or CSS keyword)">]>;
+        readonly muted: v.SchemaWithPipe<[v.StringSchema<undefined>, v.CheckAction<string, "color value did not match the allowed format (hex, oklch, hsl, rgb, var(), HSL split, or CSS keyword)">]>;
+        readonly "muted-foreground": v.SchemaWithPipe<[v.StringSchema<undefined>, v.CheckAction<string, "color value did not match the allowed format (hex, oklch, hsl, rgb, var(), HSL split, or CSS keyword)">]>;
+        readonly border: v.SchemaWithPipe<[v.StringSchema<undefined>, v.CheckAction<string, "color value did not match the allowed format (hex, oklch, hsl, rgb, var(), HSL split, or CSS keyword)">]>;
+        readonly input: v.SchemaWithPipe<[v.StringSchema<undefined>, v.CheckAction<string, "color value did not match the allowed format (hex, oklch, hsl, rgb, var(), HSL split, or CSS keyword)">]>;
+        readonly ring: v.SchemaWithPipe<[v.StringSchema<undefined>, v.CheckAction<string, "color value did not match the allowed format (hex, oklch, hsl, rgb, var(), HSL split, or CSS keyword)">]>;
+        readonly success: v.SchemaWithPipe<[v.StringSchema<undefined>, v.CheckAction<string, "color value did not match the allowed format (hex, oklch, hsl, rgb, var(), HSL split, or CSS keyword)">]>;
+        readonly "success-foreground": v.SchemaWithPipe<[v.StringSchema<undefined>, v.CheckAction<string, "color value did not match the allowed format (hex, oklch, hsl, rgb, var(), HSL split, or CSS keyword)">]>;
+        readonly warning: v.SchemaWithPipe<[v.StringSchema<undefined>, v.CheckAction<string, "color value did not match the allowed format (hex, oklch, hsl, rgb, var(), HSL split, or CSS keyword)">]>;
+        readonly "warning-foreground": v.SchemaWithPipe<[v.StringSchema<undefined>, v.CheckAction<string, "color value did not match the allowed format (hex, oklch, hsl, rgb, var(), HSL split, or CSS keyword)">]>;
+        readonly destructive: v.SchemaWithPipe<[v.StringSchema<undefined>, v.CheckAction<string, "color value did not match the allowed format (hex, oklch, hsl, rgb, var(), HSL split, or CSS keyword)">]>;
+        readonly "destructive-foreground": v.SchemaWithPipe<[v.StringSchema<undefined>, v.CheckAction<string, "color value did not match the allowed format (hex, oklch, hsl, rgb, var(), HSL split, or CSS keyword)">]>;
+        readonly info: v.SchemaWithPipe<[v.StringSchema<undefined>, v.CheckAction<string, "color value did not match the allowed format (hex, oklch, hsl, rgb, var(), HSL split, or CSS keyword)">]>;
+        readonly "info-foreground": v.SchemaWithPipe<[v.StringSchema<undefined>, v.CheckAction<string, "color value did not match the allowed format (hex, oklch, hsl, rgb, var(), HSL split, or CSS keyword)">]>;
+        readonly "status-online": v.SchemaWithPipe<[v.StringSchema<undefined>, v.CheckAction<string, "color value did not match the allowed format (hex, oklch, hsl, rgb, var(), HSL split, or CSS keyword)">]>;
+        readonly "status-online-foreground": v.SchemaWithPipe<[v.StringSchema<undefined>, v.CheckAction<string, "color value did not match the allowed format (hex, oklch, hsl, rgb, var(), HSL split, or CSS keyword)">]>;
+        readonly "status-offline": v.SchemaWithPipe<[v.StringSchema<undefined>, v.CheckAction<string, "color value did not match the allowed format (hex, oklch, hsl, rgb, var(), HSL split, or CSS keyword)">]>;
+        readonly "status-offline-foreground": v.SchemaWithPipe<[v.StringSchema<undefined>, v.CheckAction<string, "color value did not match the allowed format (hex, oklch, hsl, rgb, var(), HSL split, or CSS keyword)">]>;
+        readonly "status-degraded": v.SchemaWithPipe<[v.StringSchema<undefined>, v.CheckAction<string, "color value did not match the allowed format (hex, oklch, hsl, rgb, var(), HSL split, or CSS keyword)">]>;
+        readonly "status-degraded-foreground": v.SchemaWithPipe<[v.StringSchema<undefined>, v.CheckAction<string, "color value did not match the allowed format (hex, oklch, hsl, rgb, var(), HSL split, or CSS keyword)">]>;
+        readonly "status-info": v.SchemaWithPipe<[v.StringSchema<undefined>, v.CheckAction<string, "color value did not match the allowed format (hex, oklch, hsl, rgb, var(), HSL split, or CSS keyword)">]>;
+        readonly "status-info-foreground": v.SchemaWithPipe<[v.StringSchema<undefined>, v.CheckAction<string, "color value did not match the allowed format (hex, oklch, hsl, rgb, var(), HSL split, or CSS keyword)">]>;
+    }, undefined>;
+    readonly fontUrls: v.OptionalSchema<v.ArraySchema<v.SchemaWithPipe<[v.StringSchema<undefined>, v.UrlAction<string, undefined>, v.CheckAction<string, "fontUrls must use http(s) protocol (javascript:, data:, etc. are rejected)">]>, undefined>, never>;
+}, undefined>;
+export type ThemeIssue = v.InferIssue<typeof themeSchema>;
+export interface ThemeValidationResult {
+    success: boolean;
+    issues?: ThemeIssue[];
+}
+export declare function validateTheme(theme: unknown): ThemeValidationResult;
+export declare function formatThemeIssues(themeName: string, issues: ThemeIssue[]): string;

package/dist/themes/theme-provider.d.ts

@@ -0,0 +1,82 @@
+import type { JSX, ReactNode } from "react";
+import { type Density } from "./density.js";
+import type { Theme, ThemeMode } from "./types.js";
+interface ThemeContextValue {
+    /** Active theme (full descriptor). */
+    theme: Theme;
+    /** Active mode: light or dark. */
+    mode: ThemeMode;
+    /** All available themes. */
+    themes: Theme[];
+    /** Swap the active theme by name. */
+    setTheme: (name: string) => void;
+    /** Set light/dark explicitly. */
+    setMode: (mode: ThemeMode) => void;
+    /** Toggle light <> dark. */
+    toggleMode: () => void;
+    /** Register an additional theme at runtime. */
+    registerTheme: (theme: Theme) => void;
+}
+interface ThemeProviderProps {
+    children: ReactNode;
+    /**
+     * Theme to start with. Must match the `name` of an entry in `themes`.
+     * Defaults to `"violet-forge"` for backward compat — if you don't pass
+     * `violet-forge` in `themes`, set this prop explicitly.
+     */
+    defaultTheme?: string;
+    /** Mode to start with. Defaults to `"dark"` (library is dark-first). */
+    defaultMode?: ThemeMode;
+    /**
+     * Available themes. **Required**: ThemeProvider does not auto-include any
+     * built-in theme since v0.1.0-next.0 — pass `builtinThemes` for all three
+     * Violet Forge defaults, or your own array for a slimmer bundle.
+     *
+     * Migration: consumers previously calling `<ThemeProvider>` without this
+     * prop now must pass `themes={builtinThemes}` (or use `<TheoUIProvider>`
+     * which defaults to `builtinThemes` for you).
+     */
+    themes: Theme[];
+    /**
+     * Persist selection in localStorage under this key. Pass `null` to disable.
+     * Default: "theo-ui:theme".
+     */
+    storageKey?: string | null;
+    /**
+     * Initial density. Drives `data-density` on `<html>` and the `--theo-control-h`
+     * / `--theo-control-px` CSS vars consumed by form-control `md` variants.
+     * Defaults to `"comfortable"` (36px controls — FAANG-tier modern density).
+     * Plan: faang-density-tightening (D3).
+     */
+    defaultDensity?: Density;
+    /**
+     * Respect the consumer's OS `prefers-color-scheme` preference on initial
+     * mount (D6 / T5.1). When `true` (default) and no theme-mode is stored in
+     * `localStorage[storageKey]`, the provider reads
+     * `matchMedia('(prefers-color-scheme: dark)')` and subscribes to changes.
+     * User-driven `setMode()` overrides the system signal — subsequent OS
+     * changes are ignored after the user fixes a preference.
+     *
+     * Pass `false` to force `defaultMode` regardless of the system preference.
+     * EC-12: matchMedia listener is cleaned up on unmount.
+     */
+    respectSystemMode?: boolean;
+}
+/**
+ * ThemeProvider — central registry + runtime switcher for Theo themes.
+ *
+ * Behavior:
+ *   1. On mount, injects a `<style id="theo-ui-theme-vars">` element with
+ *      one CSS block per theme (`[data-theme="<name>"] { --token: ... }`).
+ *   2. Sets `data-theme` and `data-mode` on `<html>` so any element nested
+ *      below inherits the right tokens (the Tailwind config consumes them).
+ *   3. Lazy-loads theme font URLs by injecting `<link rel="stylesheet">`.
+ *   4. Optionally persists choice in localStorage.
+ */
+declare function ThemeProvider({ children, defaultTheme, defaultMode, themes: themesProp, storageKey, defaultDensity, respectSystemMode, }: ThemeProviderProps): JSX.Element;
+/**
+ * useTheme — access theme state from any component inside <ThemeProvider>.
+ * Throws if used outside the provider — fail-fast.
+ */
+declare function useTheme(): ThemeContextValue;
+export { ThemeProvider, useTheme };

package/dist/themes/theme-script.d.ts

@@ -0,0 +1,48 @@
+/**
+ * ThemeScript — inline `<script>` for SSR-safe theme initialization.
+ *
+ * Renders a synchronous script that runs BEFORE React hydration. It reads the
+ * persisted theme + mode from localStorage (or falls back to the defaults) and
+ * sets `data-theme` / `data-mode` on `<html>`, plus the `.dark` class when
+ * mode is dark. This eliminates FOUC and avoids hydration mismatch warnings
+ * when the user's persisted choice differs from the SSR defaults.
+ *
+ * Place this in `<head>` ABOVE `<body>`. The component does not need to live
+ * inside `<ThemeProvider>`.
+ *
+ * Security: every interpolated value is passed through `safe()`, which both
+ * `JSON.stringify`s the value AND escapes `<` to `<`. The `<` escape is
+ * REQUIRED because `JSON.stringify` alone does NOT escape `/`, so a payload
+ * like `"</script><script>alert(1)</script>"` would otherwise break out of
+ * the inline `<script>` tag even though it stays inside a JS string literal.
+ * (The browser tokenizes `</script>` at the HTML layer before JS parses.)
+ *
+ * Example (Next.js App Router): see docs/design-system.md → SSR section.
+ * Pass `defaultTheme` and `defaultMode` to align with the consumer's
+ * preferred initial state. Always wrap the root in `<html
+ * suppressHydrationWarning>` to silence the expected one-render diff.
+ */
+import type { JSX } from "react";
+import type { ThemeMode } from "./types.js";
+interface ThemeScriptProps {
+    /** Theme name to apply when no persisted value exists. Default `"violet-forge"`. */
+    defaultTheme?: string;
+    /** Mode to apply when no persisted value exists. Default `"dark"`. */
+    defaultMode?: ThemeMode;
+    /**
+     * Density to apply when no persisted value exists. Default `"comfortable"`.
+     * Mirrors `ThemeProvider`'s `defaultDensity` so the inline-script and
+     * the React provider agree on the SSR-default density (and the
+     * `data-density` attribute set by this script matches what
+     * `ThemeProvider` promotes via its post-mount hydration effect).
+     */
+    defaultDensity?: "compact" | "comfortable" | "spacious";
+    /**
+     * localStorage namespace. Must match the `storageKey` passed to
+     * `<ThemeProvider>`. Default `"theo-ui:theme"`. Pass `null` to disable
+     * persistence reads (the script will always apply defaults).
+     */
+    storageKey?: string | null;
+}
+declare function ThemeScript({ defaultTheme, defaultMode, defaultDensity, storageKey, }: ThemeScriptProps): JSX.Element;
+export { ThemeScript };

package/dist/themes/theme-switcher.d.ts

@@ -0,0 +1,17 @@
+import type { JSX } from "react";
+interface ThemeSwitcherProps {
+    className?: string;
+    /** If true, renders mode toggle inline next to the theme menu. */
+    showModeToggle?: boolean;
+}
+/**
+ * ThemeSwitcher — drop-in theme + mode picker.
+ *
+ * Two affordances:
+ *   - Palette dropdown lists all registered themes with the active marked.
+ *   - Optional sun/moon button toggles light/dark.
+ *
+ * Stateless wrt itself — pulls state from `useTheme()`.
+ */
+declare function ThemeSwitcher({ className, showModeToggle }: ThemeSwitcherProps): JSX.Element;
+export { ThemeSwitcher };

package/dist/themes/types.d.ts

@@ -0,0 +1,88 @@
+/**
+ * Theo UI — Theme types.
+ *
+ * A Theme is a frozen bundle of CSS-var values that the runtime can swap by
+ * setting `data-theme="<name>"` on `<html>`. The structure mirrors what lives
+ * in tokens.css so themes can be merged without ambiguity.
+ */
+export type ThemeMode = "light" | "dark";
+export interface ColorScale {
+    background: string;
+    foreground: string;
+    card: string;
+    "card-foreground": string;
+    popover: string;
+    "popover-foreground": string;
+    primary: string;
+    /**
+     * Tonal scale variants of `primary`. Optional since T3.2 (ADR-0006).
+     * When omitted, derived in CSS from `--primary` via `oklch(from ...)`.
+     * Override per-theme by providing an explicit string.
+     */
+    "primary-deep"?: string;
+    "primary-glow"?: string;
+    "primary-foreground": string;
+    secondary: string;
+    "secondary-foreground": string;
+    accent: string;
+    /**
+     * Tonal scale variant of `accent`. Optional since T3.2 — derived in CSS
+     * when omitted. Override per-theme by providing an explicit string.
+     */
+    "accent-deep"?: string;
+    "accent-foreground": string;
+    muted: string;
+    "muted-foreground": string;
+    border: string;
+    input: string;
+    ring: string;
+    success: string;
+    "success-foreground": string;
+    warning: string;
+    "warning-foreground": string;
+    destructive: string;
+    "destructive-foreground": string;
+    info: string;
+    "info-foreground": string;
+    /**
+     * Status semantic group (D4 ADR — community-best-practices plan).
+     *
+     * Operational state colors (gateway connected/disconnected/slow/info-flag)
+     * separated from action-result semantics (success/destructive/warning/info).
+     * Defaults in built-in themes mirror their semantic counterparts; consumers
+     * may override for visually-distinct status surfaces. `defineTheme(partial)`
+     * auto-populates from semantic group when omitted.
+     */
+    "status-online": string;
+    "status-online-foreground": string;
+    "status-offline": string;
+    "status-offline-foreground": string;
+    "status-degraded": string;
+    "status-degraded-foreground": string;
+    "status-info": string;
+    "status-info-foreground": string;
+}
+export interface ThemeFonts {
+    /** Display headlines (h1-h3, hero text). */
+    display: string;
+    /** Body / UI text. */
+    body: string;
+    /** Code, mono, paths, timestamps. */
+    mono: string;
+}
+export interface Theme {
+    /** Stable id, used in `data-theme`. */
+    name: string;
+    /** Human-readable label for theme switchers. */
+    label: string;
+    /** Optional short description shown in switchers. */
+    description?: string;
+    fonts: ThemeFonts;
+    light: ColorScale;
+    dark: ColorScale;
+    /**
+     * Optional URL(s) to fetch before applying. The provider injects a `<link>`
+     * tag once per URL to load remote fonts. Already-injected URLs are deduped.
+     */
+    fontUrls?: string[];
+}

package/dist/themes/vercel-mono.d.ts

@@ -0,0 +1,11 @@
+import type { Theme } from "./types.js";
+/**
+ * Vercel Mono — razor-sharp monochrome + signature blue.
+ *
+ * Inspired by, not affiliated with Vercel. Based on Geist Design tokens
+ * (https://github.com/vercel/geist). Light = pure white + black ink + blue
+ * accent (#0070F3); dark = near-black canvas + white text + same blue.
+ *
+ * Plan: .claude/knowledge-base/plans/seven-themes-plan.md T2.1
+ */
+export declare const vercelMono: Theme;

package/dist/themes/violet-forge.d.ts

@@ -0,0 +1,12 @@
+import type { Theme } from "./types.js";
+/**
+ * Violet Forge — the default Theo theme.
+ *
+ * Identity: Theo violet electric primary (#A855F7, unified 2026-06-09),
+ * burnt sienna accent (#C96442), Vercel-style neutral surfaces
+ * (pure white light / charcoal dark), Geist Sans + Geist Mono throughout.
+ *
+ * Source of truth for `data-theme` overrides. Values mirror
+ * src/styles/tokens.css for the default `:root`.
+ */
+export declare const violetForge: Theme;