@sero-ai/ui 0.2.0 → 0.2.1

package/src/components/ui/search-input.tsx

@@ -7,34 +7,33 @@ interface SearchInputProps extends React.ComponentProps<"input"> {
   containerClassName?: string
   endAdornment?: React.ReactNode
   iconClassName?: string
+  ref?: React.Ref<HTMLInputElement>
 }
 
-const SearchInput = React.forwardRef<HTMLInputElement, SearchInputProps>(
-  ({ containerClassName, className, endAdornment, iconClassName, ...props }, ref) => {
-    return (
-      <div
-        data-slot="search-input"
-        className={cn("flex items-center gap-2 px-3", containerClassName)}
-      >
-        <SearchIcon
-          data-slot="search-input-icon"
-          className={cn("text-muted-foreground size-3.5 shrink-0", iconClassName)}
-        />
-        <input
-          ref={ref}
-          data-slot="search-input-control"
-          className={cn(
-            "placeholder:text-muted-foreground h-9 w-full min-w-0 bg-transparent pl-1.5 text-xs text-foreground outline-none disabled:cursor-not-allowed disabled:opacity-50",
-            className
-          )}
-          {...props}
-        />
-        {endAdornment}
-      </div>
-    )
-  }
-)
-
-SearchInput.displayName = "SearchInput"
+function SearchInput({ containerClassName, className, endAdornment, iconClassName, placeholder, "aria-label": ariaLabel, ref, ...props }: SearchInputProps) {
+  return (
+    <div
+      data-slot="search-input"
+      className={cn("flex items-center gap-2 px-3", containerClassName)}
+    >
+      <SearchIcon
+        data-slot="search-input-icon"
+        className={cn("text-muted-foreground size-3.5 shrink-0", iconClassName)}
+      />
+      <input
+        aria-label={ariaLabel ?? (typeof placeholder === "string" ? placeholder : "Search")}
+        placeholder={placeholder}
+        ref={ref}
+        data-slot="search-input-control"
+        className={cn(
+          "placeholder:text-muted-foreground h-9 w-full min-w-0 bg-transparent pl-1.5 text-xs text-foreground outline-none disabled:cursor-not-allowed disabled:opacity-50",
+          className
+        )}
+        {...props}
+      />
+      {endAdornment}
+    </div>
+  )
+}
 
 export { SearchInput }

package/src/components/ui/slider.tsx

@@ -20,6 +20,11 @@ function Slider({
           : [min, max],
     [value, defaultValue, min, max]
   )
+  const thumbKeysRef = React.useRef<string[]>([])
+  while (thumbKeysRef.current.length < _values.length) {
+    thumbKeysRef.current.push(`thumb-${thumbKeysRef.current.length}`)
+  }
+  const thumbKeys = thumbKeysRef.current.slice(0, _values.length)
 
   return (
     <SliderPrimitive.Root
@@ -47,10 +52,10 @@ function Slider({
           )}
         />
       </SliderPrimitive.Track>
-      {Array.from({ length: _values.length }, (_, index) => (
+      {_values.map((_, index) => (
         <SliderPrimitive.Thumb
           data-slot="slider-thumb"
-          key={index}
+          key={thumbKeys[index]}
           className="border-primary ring-ring/50 block size-4 shrink-0 rounded-full border bg-white shadow-sm transition-[color,box-shadow] hover:ring-4 focus-visible:ring-4 focus-visible:outline-hidden disabled:pointer-events-none disabled:opacity-50"
         />
       ))}

package/src/components/ui/textarea.tsx

@@ -2,9 +2,11 @@ import * as React from "react"
 
 import { cn } from "../../lib/utils"
 
-function Textarea({ className, ...props }: React.ComponentProps<"textarea">) {
+function Textarea({ className, placeholder, "aria-label": ariaLabel, ...props }: React.ComponentProps<"textarea">) {
   return (
     <textarea
+      aria-label={ariaLabel ?? (typeof placeholder === "string" ? placeholder : undefined)}
+      placeholder={placeholder}
       data-slot="textarea"
       className={cn(
         "border-input placeholder:text-muted-foreground focus-visible:border-ring focus-visible:ring-ring/50 aria-invalid:ring-destructive/20 dark:aria-invalid:ring-destructive/40 aria-invalid:border-destructive dark:bg-input/30 flex field-sizing-content min-h-16 w-full rounded-md border bg-transparent px-3 py-2 text-base shadow-xs transition-[color,box-shadow] outline-none focus-visible:ring-[3px] disabled:cursor-not-allowed disabled:opacity-50 md:text-sm",

package/src/components/ui/toggle-group.tsx

@@ -56,7 +56,7 @@ function ToggleGroupItem({
   ...props
 }: React.ComponentProps<typeof ToggleGroupPrimitive.Item> &
   VariantProps<typeof toggleVariants>) {
-  const context = React.useContext(ToggleGroupContext)
+  const context = React.use(ToggleGroupContext)
 
   return (
     <ToggleGroupPrimitive.Item

package/src/components/ui/tree.tsx

@@ -20,7 +20,7 @@ const TreeContext = React.createContext<TreeContextValue>({
 });
 
 function useTreeContext<T = any>() {
-  return React.useContext(TreeContext) as TreeContextValue<T>;
+  return React.use(TreeContext) as TreeContextValue<T>;
 }
 
 interface TreeProps extends React.HTMLAttributes<HTMLDivElement> {
@@ -61,7 +61,7 @@ interface TreeItemProps<T = any>
 }
 
 /**
- * TreeItem — full-width row button.
+ * TreeItem, full-width row button.
  *
  * The row carries hover / selected / drag-target backgrounds so the
  * highlight spans edge-to-edge (VSCode-style). Indentation is applied
@@ -140,7 +140,7 @@ interface TreeItemLabelProps<T = any>
 }
 
 /**
- * TreeItemLabel — content wrapper inside a TreeItem.
+ * TreeItemLabel, content wrapper inside a TreeItem.
  *
  * Layout-only (chevron + children). Background lives on the parent
  * TreeItem so it spans the full row width.

package/src/index.ts

@@ -14,6 +14,9 @@ export { cn } from "./lib/utils";
 // ── Hooks ──
 export { useIsMobile } from "./hooks/use-mobile";
 
+// ── Theme ──
+export * from "./theme";
+
 // ── UI Components ──
 export * from "./components/ui/accordion";
 export * from "./components/ui/alert-dialog";

package/src/styles/globals.css

@@ -22,7 +22,7 @@
   /* Border (light) */
   --border-subtle: #d4d8e0;
   --border-default: #bcc1cc;
-  --border-focus: #6366f1;
+  --border-focus: #059669;
 
   /* Text (light) */
   --text-primary: #0f1117;
@@ -30,10 +30,26 @@
   --text-muted: #6b7280;
   --text-inverse: #fafafa;
 
-  /* Accent (indigo) — brand accent colour used by Sero components */
-  --accent-primary: #6366f1;
-  --accent-hover: #818cf8;
-  --accent-muted: #6366f11a;
+  /* Brand colours — product identity, actions, active UI */
+  --brand-primary: #059669;
+  --brand-primary-hover: #047857;
+  --brand-primary-foreground: #ffffff;
+  --brand-primary-muted: color-mix(in srgb, var(--brand-primary) 10%, transparent);
+  --brand-primary-subtle: color-mix(in srgb, var(--brand-primary) 15%, transparent);
+  --brand-primary-faint: color-mix(in srgb, var(--brand-primary) 3%, transparent);
+  --brand-primary-border: color-mix(in srgb, var(--brand-primary) 20%, transparent);
+  --brand-secondary: #7c3aed;
+  --brand-secondary-hover: #6d28d9;
+  --brand-secondary-foreground: #ffffff;
+  --brand-secondary-muted: color-mix(in srgb, var(--brand-secondary) 10%, transparent);
+  --brand-secondary-subtle: color-mix(in srgb, var(--brand-secondary) 15%, transparent);
+  --brand-secondary-faint: color-mix(in srgb, var(--brand-secondary) 3%, transparent);
+  --brand-secondary-border: color-mix(in srgb, var(--brand-secondary) 20%, transparent);
+
+  /* Legacy accent / syntax accent */
+  --accent-primary: var(--brand-secondary);
+  --accent-hover: var(--brand-secondary-hover);
+  --accent-muted: var(--brand-secondary-muted);
   --accent-code: #7c3aed;
 
   /* Status — solid */
@@ -79,10 +95,10 @@
   --voice-processing-muted: rgba(6, 182, 212, 0.15);
 
   /* Semantic colours — indigo accent for notifications/banners */
-  --banner-primary: #6366f1;
-  --banner-primary-muted: rgba(99, 102, 241, 0.10);
-  --banner-primary-subtle: rgba(99, 102, 241, 0.15);
-  --banner-primary-border: rgba(99, 102, 241, 0.20);
+  --banner-primary: var(--brand-secondary);
+  --banner-primary-muted: color-mix(in srgb, var(--banner-primary) 10%, transparent);
+  --banner-primary-subtle: color-mix(in srgb, var(--banner-primary) 15%, transparent);
+  --banner-primary-border: color-mix(in srgb, var(--banner-primary) 20%, transparent);
 
   /* Thinking / reasoning gradients */
   --gradient-thinking-high: linear-gradient(135deg, rgba(245, 158, 11, 0.20), rgba(239, 68, 68, 0.20));
@@ -131,15 +147,15 @@
      shadcn component (Dialog, Command, Dropdown, Tooltip, …)
      automatically follows theme changes.
      NOTE: --accent here is the shadcn "hover/selection bg",
-     NOT the brand accent colour (that's --accent-primary). */
+     NOT a brand colour (use --brand-primary/secondary). */
   --background: var(--bg-base);
   --foreground: var(--text-primary);
   --card: var(--bg-surface);
   --card-foreground: var(--text-primary);
   --popover: var(--bg-elevated);
   --popover-foreground: var(--text-primary);
-  --primary: var(--text-primary);
-  --primary-foreground: var(--text-inverse);
+  --primary: var(--brand-primary);
+  --primary-foreground: var(--brand-primary-foreground);
   --secondary: var(--bg-surface);
   --secondary-foreground: var(--text-primary);
   --muted: var(--bg-muted);
@@ -157,8 +173,8 @@
   --chart-5: oklch(0.769 0.188 70.08);
   --sidebar: var(--bg-surface);
   --sidebar-foreground: var(--text-primary);
-  --sidebar-primary: var(--accent-primary);
-  --sidebar-primary-foreground: var(--text-inverse);
+  --sidebar-primary: var(--brand-primary);
+  --sidebar-primary-foreground: var(--brand-primary-foreground);
   --sidebar-accent: var(--bg-elevated);
   --sidebar-accent-foreground: var(--text-primary);
   --sidebar-border: var(--border-subtle);
@@ -208,6 +224,38 @@
   --radius-4xl: calc(var(--radius) + 16px);
   --color-background: var(--background);
   --color-foreground: var(--foreground);
+  --color-brand-primary: var(--brand-primary);
+  --color-brand-primary-foreground: var(--brand-primary-foreground);
+  --color-brand-primary-muted: var(--brand-primary-muted);
+  --color-brand-primary-subtle: var(--brand-primary-subtle);
+  --color-brand-primary-faint: var(--brand-primary-faint);
+  --color-brand-primary-border: var(--brand-primary-border);
+  --color-brand-secondary: var(--brand-secondary);
+  --color-brand-secondary-foreground: var(--brand-secondary-foreground);
+  --color-brand-secondary-muted: var(--brand-secondary-muted);
+  --color-brand-secondary-subtle: var(--brand-secondary-subtle);
+  --color-brand-secondary-faint: var(--brand-secondary-faint);
+  --color-brand-secondary-border: var(--brand-secondary-border);
+  --color-status-success: var(--status-success);
+  --color-status-success-muted: var(--status-success-muted);
+  --color-status-success-subtle: var(--status-success-subtle);
+  --color-status-success-faint: var(--status-success-faint);
+  --color-status-success-border: var(--status-success-border);
+  --color-status-warning: var(--status-warning);
+  --color-status-warning-muted: var(--status-warning-muted);
+  --color-status-warning-subtle: var(--status-warning-subtle);
+  --color-status-warning-faint: var(--status-warning-faint);
+  --color-status-warning-border: var(--status-warning-border);
+  --color-status-error: var(--status-error);
+  --color-status-error-muted: var(--status-error-muted);
+  --color-status-error-subtle: var(--status-error-subtle);
+  --color-status-error-faint: var(--status-error-faint);
+  --color-status-error-border: var(--status-error-border);
+  --color-status-info: var(--status-info);
+  --color-status-info-muted: var(--status-info-muted);
+  --color-status-info-subtle: var(--status-info-subtle);
+  --color-status-info-faint: var(--status-info-faint);
+  --color-status-info-border: var(--status-info-border);
   --color-card: var(--card);
   --color-card-foreground: var(--card-foreground);
   --color-popover: var(--popover);
@@ -250,6 +298,7 @@
   /* Border (dark) */
   --border-subtle: #27272a;
   --border-default: #3f3f46;
+  --border-focus: #34d399;
 
   /* Text (dark) */
   --text-primary: #fafafa;
@@ -257,10 +306,26 @@
   --text-muted: #71717a;
   --text-inverse: #09090b;
 
-  /* Accent (dark) */
-  --accent-primary: #818cf8;
-  --accent-hover: #a5b4fc;
-  --accent-muted: #6366f133;
+  /* Brand colours (dark) */
+  --brand-primary: #34d399;
+  --brand-primary-hover: #6ee7b7;
+  --brand-primary-foreground: #052e1c;
+  --brand-primary-muted: color-mix(in srgb, var(--brand-primary) 10%, transparent);
+  --brand-primary-subtle: color-mix(in srgb, var(--brand-primary) 15%, transparent);
+  --brand-primary-faint: color-mix(in srgb, var(--brand-primary) 3%, transparent);
+  --brand-primary-border: color-mix(in srgb, var(--brand-primary) 20%, transparent);
+  --brand-secondary: #c4b5fd;
+  --brand-secondary-hover: #ddd6fe;
+  --brand-secondary-foreground: #1e1038;
+  --brand-secondary-muted: color-mix(in srgb, var(--brand-secondary) 10%, transparent);
+  --brand-secondary-subtle: color-mix(in srgb, var(--brand-secondary) 15%, transparent);
+  --brand-secondary-faint: color-mix(in srgb, var(--brand-secondary) 3%, transparent);
+  --brand-secondary-border: color-mix(in srgb, var(--brand-secondary) 20%, transparent);
+
+  /* Legacy accent / syntax accent (dark) */
+  --accent-primary: var(--brand-secondary);
+  --accent-hover: var(--brand-secondary-hover);
+  --accent-muted: var(--brand-secondary-muted);
   --accent-code: #c4b5fd;
 
   /* Status — solid (dark) */
@@ -306,10 +371,10 @@
   --voice-processing-muted: rgba(34, 211, 238, 0.15);
 
   /* Banner / notifications (dark) */
-  --banner-primary: #818cf8;
-  --banner-primary-muted: rgba(129, 140, 248, 0.10);
-  --banner-primary-subtle: rgba(129, 140, 248, 0.15);
-  --banner-primary-border: rgba(129, 140, 248, 0.20);
+  --banner-primary: var(--brand-secondary);
+  --banner-primary-muted: color-mix(in srgb, var(--banner-primary) 10%, transparent);
+  --banner-primary-subtle: color-mix(in srgb, var(--banner-primary) 15%, transparent);
+  --banner-primary-border: color-mix(in srgb, var(--banner-primary) 20%, transparent);
 
   /* Thinking gradients (dark) */
   --gradient-thinking-high: linear-gradient(135deg, rgba(245, 158, 11, 0.20), rgba(239, 68, 68, 0.20));
@@ -331,8 +396,8 @@
   --card-foreground: var(--text-primary);
   --popover: var(--bg-elevated);
   --popover-foreground: var(--text-primary);
-  --primary: var(--text-primary);
-  --primary-foreground: var(--text-inverse);
+  --primary: var(--brand-primary);
+  --primary-foreground: var(--brand-primary-foreground);
   --secondary: var(--bg-surface);
   --secondary-foreground: var(--text-primary);
   --muted: var(--bg-muted);
@@ -350,8 +415,8 @@
   --chart-5: oklch(0.645 0.246 16.439);
   --sidebar: var(--bg-surface);
   --sidebar-foreground: var(--text-primary);
-  --sidebar-primary: var(--accent-primary);
-  --sidebar-primary-foreground: var(--text-inverse);
+  --sidebar-primary: var(--brand-primary);
+  --sidebar-primary-foreground: var(--brand-primary-foreground);
   --sidebar-accent: var(--bg-elevated);
   --sidebar-accent-foreground: var(--text-primary);
   --sidebar-border: var(--border-subtle);

package/src/styles/plugin.css

@@ -0,0 +1,4 @@
+@import "./globals.css";
+
+/* Federated Sero plugins should import this file, then add plugin-local
+   @source directives. It keeps Tailwind 4 token names aligned with the shell. */

package/src/theme/apply-theme.ts

@@ -0,0 +1,250 @@
+import type {
+  ColorTokens,
+  ThemePreset,
+} from './types';
+
+// ── Token → CSS Variable Mapping ─────────────────────────────
+
+/** Maps ColorTokens keys to their CSS custom property names. */
+const COLOR_TOKEN_TO_CSS: Record<keyof ColorTokens, string> = {
+  bgBase: '--bg-base',
+  bgSurface: '--bg-surface',
+  bgElevated: '--bg-elevated',
+  bgOverlay: '--bg-overlay',
+  bgMuted: '--bg-muted',
+  borderSubtle: '--border-subtle',
+  borderDefault: '--border-default',
+  borderFocus: '--border-focus',
+  textPrimary: '--text-primary',
+  textSecondary: '--text-secondary',
+  textMuted: '--text-muted',
+  textInverse: '--text-inverse',
+  brandPrimary: '--brand-primary',
+  brandPrimaryHover: '--brand-primary-hover',
+  brandPrimaryForeground: '--brand-primary-foreground',
+  brandSecondary: '--brand-secondary',
+  brandSecondaryHover: '--brand-secondary-hover',
+  brandSecondaryForeground: '--brand-secondary-foreground',
+  accentPrimary: '--accent-primary',
+  accentHover: '--accent-hover',
+  accentMuted: '--accent-muted',
+  accentCode: '--accent-code',
+  statusSuccess: '--status-success',
+  statusWarning: '--status-warning',
+  statusError: '--status-error',
+  statusInfo: '--status-info',
+  collabPrimary: '--collab-primary',
+  voiceRecording: '--voice-recording',
+  voiceProcessing: '--voice-processing',
+  bannerPrimary: '--banner-primary',
+};
+
+/**
+ * Derived opacity variants generated from base semantic colours.
+ * Each entry is [css-var-name, base-token-key, percentage].
+ */
+const DERIVED_OPACITY_VARS: Array<[string, keyof ColorTokens, number]> = [
+  ['--brand-primary-muted', 'brandPrimary', 10],
+  ['--brand-primary-subtle', 'brandPrimary', 15],
+  ['--brand-primary-faint', 'brandPrimary', 3],
+  ['--brand-primary-border', 'brandPrimary', 20],
+  ['--brand-secondary-muted', 'brandSecondary', 10],
+  ['--brand-secondary-subtle', 'brandSecondary', 15],
+  ['--brand-secondary-faint', 'brandSecondary', 3],
+  ['--brand-secondary-border', 'brandSecondary', 20],
+  ['--status-success-muted', 'statusSuccess', 10],
+  ['--status-success-subtle', 'statusSuccess', 15],
+  ['--status-success-faint', 'statusSuccess', 3],
+  ['--status-success-border', 'statusSuccess', 20],
+  ['--status-warning-muted', 'statusWarning', 10],
+  ['--status-warning-subtle', 'statusWarning', 15],
+  ['--status-warning-faint', 'statusWarning', 3],
+  ['--status-warning-border', 'statusWarning', 20],
+  ['--status-error-muted', 'statusError', 10],
+  ['--status-error-subtle', 'statusError', 15],
+  ['--status-error-faint', 'statusError', 3],
+  ['--status-error-border', 'statusError', 20],
+  ['--status-info-muted', 'statusInfo', 10],
+  ['--status-info-subtle', 'statusInfo', 15],
+  ['--status-info-faint', 'statusInfo', 3],
+  ['--status-info-border', 'statusInfo', 20],
+  ['--collab-primary-muted', 'collabPrimary', 10],
+  ['--collab-primary-subtle', 'collabPrimary', 15],
+  ['--collab-primary-border', 'collabPrimary', 20],
+  ['--voice-recording-muted', 'voiceRecording', 20],
+  ['--voice-processing-muted', 'voiceProcessing', 15],
+  ['--banner-primary-muted', 'bannerPrimary', 10],
+  ['--banner-primary-subtle', 'bannerPrimary', 15],
+  ['--banner-primary-border', 'bannerPrimary', 20],
+];
+
+export interface ApplyThemeOptions {
+  loadFont?: (fontStack: string) => void;
+}
+
+function tint(color: string, percentage: number): string {
+  return `color-mix(in srgb, ${color} ${percentage}%, transparent)`;
+}
+
+// ── Apply / Reset ────────────────────────────────────────────
+
+/** Apply a theme preset for the given mode. */
+export function applyThemePreset(
+  preset: ThemePreset,
+  mode: 'light' | 'dark',
+  options: ApplyThemeOptions = {},
+): void {
+  const root = document.documentElement;
+  const colors = mode === 'dark' ? preset.colors.dark : preset.colors.light;
+
+  for (const [key, cssVar] of Object.entries(COLOR_TOKEN_TO_CSS)) {
+    const value = colors[key as keyof ColorTokens];
+    if (value) root.style.setProperty(cssVar, value);
+  }
+
+  for (const [cssVar, baseKey, percentage] of DERIVED_OPACITY_VARS) {
+    const baseColor = colors[baseKey];
+    if (baseColor) root.style.setProperty(cssVar, tint(baseColor, percentage));
+  }
+
+  if (preset.typography?.fontSans) {
+    options.loadFont?.(preset.typography.fontSans);
+    root.style.setProperty('--font-sans', preset.typography.fontSans);
+  }
+  if (preset.typography?.fontMono) {
+    options.loadFont?.(preset.typography.fontMono);
+    root.style.setProperty('--font-mono', preset.typography.fontMono);
+  }
+  if (preset.typography?.fontSizeBase) {
+    root.style.setProperty('--font-size-base', preset.typography.fontSizeBase);
+  }
+
+  if (preset.spacing?.md) {
+    const mdPx = parseFloat(preset.spacing.md);
+    if (Number.isFinite(mdPx) && mdPx > 0) {
+      root.style.setProperty('--spacing', `${(mdPx / 3).toFixed(3)}px`);
+    }
+  }
+
+  if (preset.radius?.md) {
+    root.style.setProperty('--radius', preset.radius.md);
+  }
+
+  root.classList.toggle('dark', mode === 'dark');
+}
+
+/** All CSS custom properties managed by the theme engine. */
+const ALL_MANAGED_VARS = [
+  ...Object.values(COLOR_TOKEN_TO_CSS),
+  ...DERIVED_OPACITY_VARS.map(([v]) => v),
+  '--font-sans',
+  '--font-mono',
+  '--font-size-base',
+  '--spacing',
+  '--radius',
+];
+
+/** Remove all inline theme overrides, reverting to CSS defaults. */
+export function resetTheme(): void {
+  const root = document.documentElement;
+  for (const cssVar of ALL_MANAGED_VARS) {
+    root.style.removeProperty(cssVar);
+  }
+}
+
+// ── Validation ───────────────────────────────────────────────
+
+const LEGACY_REQUIRED_COLOR_KEYS: Array<keyof ColorTokens> = [
+  'bgBase', 'bgSurface', 'bgElevated', 'bgOverlay', 'bgMuted',
+  'borderSubtle', 'borderDefault', 'borderFocus',
+  'textPrimary', 'textSecondary', 'textMuted', 'textInverse',
+  'accentPrimary', 'accentHover', 'accentMuted', 'accentCode',
+  'statusSuccess', 'statusWarning', 'statusError', 'statusInfo',
+  'collabPrimary', 'voiceRecording', 'voiceProcessing', 'bannerPrimary',
+];
+
+/** Validate that a value looks like a CSS colour. */
+function isColorValue(v: unknown): v is string {
+  if (typeof v !== 'string') return false;
+  return /^(#[0-9a-fA-F]{3,8}|rgba?\(|oklch\(|hsla?\(|color-mix\()/.test(v.trim());
+}
+
+function optionalColor(o: Record<string, unknown>, key: keyof ColorTokens): string | undefined {
+  const value = o[key];
+  return isColorValue(value) ? value : undefined;
+}
+
+function normaliseColorTokens(obj: unknown): ColorTokens | null {
+  if (!obj || typeof obj !== 'object') return null;
+  const o = obj as Record<string, unknown>;
+  if (!LEGACY_REQUIRED_COLOR_KEYS.every((k) => isColorValue(o[k]))) return null;
+
+  const legacy = o as Record<keyof ColorTokens, string>;
+  return {
+    ...legacy,
+    brandPrimary: optionalColor(o, 'brandPrimary') ?? legacy.statusSuccess,
+    brandPrimaryHover: optionalColor(o, 'brandPrimaryHover') ?? legacy.statusSuccess,
+    brandPrimaryForeground: optionalColor(o, 'brandPrimaryForeground') ?? legacy.textInverse,
+    brandSecondary: optionalColor(o, 'brandSecondary') ?? legacy.accentCode,
+    brandSecondaryHover: optionalColor(o, 'brandSecondaryHover') ?? legacy.accentHover,
+    brandSecondaryForeground: optionalColor(o, 'brandSecondaryForeground') ?? legacy.textInverse,
+  };
+}
+
+function sanitiseTypography(raw: unknown): ThemePreset['typography'] | undefined {
+  if (!raw || typeof raw !== 'object') return undefined;
+  const o = raw as Record<string, unknown>;
+  const result: Record<string, string> = {};
+  for (const key of ['fontSans', 'fontMono', 'fontSizeBase'] as const) {
+    if (typeof o[key] === 'string') result[key] = o[key];
+  }
+  return Object.keys(result).length > 0 ? result : undefined;
+}
+
+function sanitiseSpacing(raw: unknown): ThemePreset['spacing'] | undefined {
+  if (!raw || typeof raw !== 'object') return undefined;
+  const o = raw as Record<string, unknown>;
+  const result: Record<string, string> = {};
+  for (const key of ['xs', 'sm', 'md', 'lg', 'xl'] as const) {
+    if (typeof o[key] === 'string') result[key] = o[key];
+  }
+  return Object.keys(result).length > 0 ? result : undefined;
+}
+
+function sanitiseRadius(raw: unknown): ThemePreset['radius'] | undefined {
+  if (!raw || typeof raw !== 'object') return undefined;
+  const o = raw as Record<string, unknown>;
+  const result: Record<string, string> = {};
+  for (const key of ['sm', 'md', 'lg'] as const) {
+    if (typeof o[key] === 'string') result[key] = o[key];
+  }
+  return Object.keys(result).length > 0 ? result : undefined;
+}
+
+/** Validate and normalise an unknown value into a ThemePreset. */
+export function validateThemePreset(data: unknown): ThemePreset | null {
+  if (!data || typeof data !== 'object') return null;
+  const d = data as Record<string, unknown>;
+
+  if (typeof d.id !== 'string' || !d.id) return null;
+  if (typeof d.name !== 'string' || !d.name) return null;
+  if (d.version !== 1) return null;
+
+  const colors = d.colors as Record<string, unknown> | undefined;
+  const light = normaliseColorTokens(colors?.light);
+  const dark = normaliseColorTokens(colors?.dark);
+  if (!light || !dark) return null;
+
+  return {
+    id: d.id,
+    name: d.name,
+    description: typeof d.description === 'string' ? d.description : undefined,
+    author: typeof d.author === 'string' ? d.author : undefined,
+    version: 1,
+    builtin: d.builtin === true,
+    colors: { light, dark },
+    typography: sanitiseTypography(d.typography),
+    spacing: sanitiseSpacing(d.spacing),
+    radius: sanitiseRadius(d.radius),
+  };
+}

package/src/theme/index.ts

@@ -0,0 +1,2 @@
+export * from './types';
+export * from './apply-theme';