@ultimat3/ui 23.0.0 → 25.0.0

package/src/theme/brand.ts

@@ -3,30 +3,43 @@
 // level it emits. There is deliberately no SCSS `@use ... with ()` seam — two ways to change the
 // accent colour is the ambiguity axiom 1 exists to delete.
 
-import {
-  insufficientContrastError,
-  invalidBrandTokenError,
-  runtimeMissingError,
-  unknownTokenError,
-} from '../errors';
-import { contrastRatio, parseChannels } from '../tokens/contrast';
+import { insufficientContrastError, invalidBrandTokenError, runtimeMissingError } from '../errors';
+import { contrastRatio } from '../tokens/contrast';
 import { CONTRAST_PAIRS } from '../tokens/contrast-pairs';
 import {
   COLOR_ROLES,
   type ColorRole,
   colorTokens,
   type RadiusName,
-  radiusTokens,
+  SHADOW_NAMES,
+  type ShadowName,
+  shadowTokens,
   type Theme,
 } from '../tokens/tokens';
+import {
+  colorDeclarations,
+  fontDeclarations,
+  radiusDeclarations,
+  shadowDeclarations,
+} from './brand-declarations';
+import type { FontSlot, ThemePreset } from './preset-shape';
+import { THEME_PRESET_NAMES, THEME_PRESETS, type ThemePresetName } from './presets';
+
+export type { FontSlot } from './preset-shape';
+export { FONT_SLOTS } from './preset-shape';
 
-/** The two font slots `_typography.scss` emits. */
-export const FONT_SLOTS = ['sans', 'mono'] as const;
-export type FontSlot = (typeof FONT_SLOTS)[number];
+type Themed<K extends string> = Partial<Record<Theme, Partial<Record<K, string>>>>;
 
 export interface BrandInput {
+  /**
+   * A shipped palette to start from (`THEME_PRESETS`). Every other slot layers onto it role by
+   * role, so `{ preset: 'scifi', colors: { dark: { accent: … } } }` is scifi with your accent.
+   */
+  preset?: ThemePresetName | undefined;
   /** Channel overrides per theme. Omit a theme to leave it at the shipped palette. */
-  colors?: Partial<Record<Theme, Partial<Record<ColorRole, string>>>> | undefined;
+  colors?: Themed<ColorRole> | undefined;
+  /** Shadow overrides per theme, by rung (`SHADOW_NAMES`) — elevation is themed like colour. */
+  shadows?: Themed<ShadowName> | undefined;
   radius?: Partial<Record<RadiusName, string>> | undefined;
   font?: Partial<Record<FontSlot, string>> | undefined;
 }
@@ -36,50 +49,91 @@ export interface Brand {
   readonly css: string;
 }
 
-/** `0` or a number with a CSS length unit. No `calc()`, no `var()` — a scale rung is a value. */
-const LENGTH_PATTERN = /^(0|\d+(\.\d+)?(px|rem|em|ch|%))$/;
-
-/** Family names, quotes and separators only: everything a `font-family` list legitimately needs. */
-const FONT_STACK_PATTERN = /^[\w\s,'"-]{1,200}$/;
-
-const LENGTH_EXPECTED = 'a bare CSS length such as "0.5rem", "4px" or "0"';
-const STACK_EXPECTED = 'a font-family list such as "Inter, system-ui, sans-serif"';
-const CHANNELS_EXPECTED = 'space-separated RGB channels such as "31 110 178"';
-
 /**
  * Validate and freeze a brand. Every value is checked here rather than at render time, so a bad
  * override fails at the app's entry point with the role that broke it named — not as a silently
  * dropped declaration a human has to spot in devtools.
  */
 export function defineTheme(input: BrandInput): Brand {
-  const blocks: string[] = [];
-  const light = colorDeclarations(input.colors?.light, 'colors.light');
-  const dark = colorDeclarations(input.colors?.dark, 'colors.dark');
+  const base = presetOf(input.preset);
+  const colors = {
+    light: layer(base?.colors.light, input.colors?.light),
+    dark: layer(base?.colors.dark, input.colors?.dark),
+  };
+  const shadows = {
+    light: layer(base?.shadows?.light, input.shadows?.light),
+    dark: layer(base?.shadows?.dark, input.shadows?.dark),
+  };
+  const light = [
+    ...colorDeclarations(colors.light, 'colors.light'),
+    ...shadowDeclarations(shadows.light, 'shadows.light'),
+  ];
+  const dark = [
+    ...colorDeclarations(colors.dark, 'colors.dark'),
+    ...shadowDeclarations(shadows.dark, 'shadows.dark'),
+  ];
   // Measured AFTER the channels parse and BEFORE a single declaration is rendered: a palette that
   // fails AA is not a stylesheet with a warning attached, it is a refusal. The pairings are the
   // ones the framework's own palette is held to (`CONTRAST_PAIRS`), so an app cannot ship a brand
-  // the design system would have failed its own tests over.
-  assertContrast('light', input.colors?.light);
-  assertContrast('dark', input.colors?.dark);
+  // the design system would have failed its own tests over. A preset is measured as part of the
+  // palette it builds — the merged result is what renders.
+  assertContrast('light', colors.light);
+  assertContrast('dark', colors.dark);
   const root: string[] = [
     ...light,
-    ...radiusDeclarations(input.radius),
-    ...fontDeclarations(input.font),
+    ...radiusDeclarations(layer(base?.radius, input.radius)),
+    ...fontDeclarations(layer(base?.font, input.font)),
   ];
+  const blocks: string[] = [];
   if (root.length > 0) blocks.push(rule(':root', root));
 
   // `theme.scss` emits light at `:root`, dark behind the media query, and BOTH again under
   // `html[data-theme]`. A brand that only wrote `:root` would lose to those attribute rules on
   // specificity, so every level it emits is answered here, in the same order.
   if (light.length > 0) blocks.push(rule("html[data-theme='light']", light));
-  if (dark.length > 0) {
-    blocks.push(`@media (prefers-color-scheme: dark) {\n${indent(rule(':root', dark))}\n}`);
-    blocks.push(rule("html[data-theme='dark']", dark));
+  const media = [
+    ...darkMediaDeclarations('color', COLOR_ROLES, colors, colorTokens.dark),
+    ...darkMediaDeclarations('shadow', SHADOW_NAMES, shadows, shadowTokens.dark),
+  ];
+  if (media.length > 0) {
+    blocks.push(`@media (prefers-color-scheme: dark) {\n${indent(rule(':root', media))}\n}`);
   }
+  if (dark.length > 0) blocks.push(rule("html[data-theme='dark']", dark));
 
   return Object.freeze({ css: blocks.join('\n\n') });
 }
 
+/**
+ * The named preset, or `undefined` for none. Own-property lookup: a brand read from a JSON config
+ * reaches here untyped, and `'toString'` must be a refusal, not `Object.prototype.toString`.
+ */
+function presetOf(name: ThemePresetName | undefined): ThemePreset | undefined {
+  if (name === undefined) return undefined;
+  if (!Object.hasOwn(THEME_PRESETS, name)) {
+    const known = THEME_PRESET_NAMES.map((preset) => `"${preset}"`).join(', ');
+    throw invalidBrandTokenError('input', 'preset', name, `a preset @ultimat3/ui ships: ${known}`);
+  }
+  return THEME_PRESETS[name];
+}
+
+/**
+ * `overrides` on top of `base`, key by key. An `undefined` value is no override — a spread would
+ * copy it and erase the preset's value for that key, rendering the shipped default in its place.
+ */
+function layer<V extends string>(
+  base: Readonly<Partial<Record<string, V>>> | undefined,
+  overrides: Readonly<Partial<Record<string, V>>> | undefined,
+): Record<string, V> | undefined {
+  if (base === undefined && overrides === undefined) return undefined;
+  const out: Record<string, V> = {};
+  for (const source of [base, overrides]) {
+    for (const [key, value] of Object.entries(source ?? {})) {
+      if (value !== undefined) out[key] = value;
+    }
+  }
+  return out;
+}
+
 /** The exact tag to inline, after `global.scss` so the overrides land later in the cascade. */
 export function brandStyleTag(brand: Brand): string {
   return `<style>${brand.css}</style>`;
@@ -112,64 +166,26 @@ function indent(block: string): string {
 }
 
 /**
- * Ordered by the canonical role list, not by the caller's object — a brand file rendered twice
- * must be byte-identical, or every consumer's CSP hash and diff churns for nothing.
+ * The dark media `:root` must answer every token the brand's own `:root` touched. That `:root`
+ * (light) comes after `theme.scss`'s dark media `:root` at equal specificity, so a role overridden
+ * in light only would otherwise reach an OS-dark document with no `data-theme` — scripting off, or
+ * storage throwing in the boot script — on the dark palette it was never measured against. Such a
+ * token is answered with the SHIPPED dark value. Called after both scopes were validated.
  */
-function colorDeclarations(
-  overrides: Partial<Record<ColorRole, string>> | undefined,
-  scope: string,
+function darkMediaDeclarations<K extends string>(
+  prefix: string,
+  names: readonly K[],
+  scopes: {
+    readonly light: Partial<Record<string, string>> | undefined;
+    readonly dark: Partial<Record<string, string>> | undefined;
+  },
+  shippedDark: Readonly<Record<K, string>>,
 ): string[] {
-  if (overrides === undefined) return [];
-  for (const role of Object.keys(overrides)) {
-    if (!(COLOR_ROLES as readonly string[]).includes(role)) {
-      throw unknownTokenError('color', role, COLOR_ROLES);
-    }
-  }
-  const out: string[] = [];
-  for (const role of COLOR_ROLES) {
-    const value = overrides[role];
-    if (value === undefined) continue;
-    assertChannels(scope, role, value);
-    out.push(`--color-${role}: ${value};`);
-  }
-  return out;
-}
-
-function radiusDeclarations(overrides: Partial<Record<RadiusName, string>> | undefined): string[] {
-  if (overrides === undefined) return [];
-  const known = Object.keys(radiusTokens) as RadiusName[];
-  for (const name of Object.keys(overrides)) {
-    if (!(known as readonly string[]).includes(name)) {
-      throw unknownTokenError('radius', name, known, '_radius.scss');
-    }
-  }
-  const out: string[] = [];
-  for (const name of known) {
-    const value = overrides[name];
-    if (value === undefined) continue;
-    if (!LENGTH_PATTERN.test(value)) {
-      throw invalidBrandTokenError('radius', name, value, LENGTH_EXPECTED);
-    }
-    out.push(`--radius-${name}: ${value};`);
-  }
-  return out;
-}
-
-function fontDeclarations(overrides: Partial<Record<FontSlot, string>> | undefined): string[] {
-  if (overrides === undefined) return [];
-  for (const slot of Object.keys(overrides)) {
-    if (!(FONT_SLOTS as readonly string[]).includes(slot)) {
-      throw unknownTokenError('font', slot, FONT_SLOTS, '_typography.scss');
-    }
-  }
   const out: string[] = [];
-  for (const slot of FONT_SLOTS) {
-    const value = overrides[slot];
-    if (value === undefined) continue;
-    if (!FONT_STACK_PATTERN.test(value)) {
-      throw invalidBrandTokenError('font', slot, value, STACK_EXPECTED);
-    }
-    out.push(`--font-${slot}: ${value};`);
+  for (const name of names) {
+    const value =
+      scopes.dark?.[name] ?? (scopes.light?.[name] === undefined ? undefined : shippedDark[name]);
+    if (value !== undefined) out.push(`--${prefix}-${name}: ${value};`);
   }
   return out;
 }
@@ -197,11 +213,3 @@ function assertContrast(
     throw insufficientContrastError(theme, pair.what, pair.fg, pair.bg, ratio, pair.minimum);
   }
 }
-
-function assertChannels(scope: string, role: string, value: string): void {
-  try {
-    parseChannels(value);
-  } catch {
-    throw invalidBrandTokenError(scope, role, value, CHANNELS_EXPECTED);
-  }
-}

package/src/theme/context.ts

@@ -36,7 +36,7 @@ export const UI_DEFAULT_CURRENCY = 'USD';
 /**
  * Loud-miss translator: a forgotten catalog key renders ⟦key⟧, never blank.
  *
- * Written here rather than as `createTranslator({}, locale)`, and behaviourally the same call: an
+ * Written here rather than as `catalogTranslator({}, locale)`, and behaviourally the same call: an
  * empty catalog has no key, so every lookup is a miss, `has` is false, `raw` is undefined and
  * `keys` is empty — `context.test.ts` holds each of those against `@ultimat3/i18n`'s own. What
  * the spelling buys is that a browser chunk with a `UiProvider` in it no longer reaches the i18n

package/src/theme/preset-scifi.ts

@@ -0,0 +1,99 @@
+// The `scifi` preset: deep near-black panels in the dark, cool paper in the light, a cyan accent
+// that turns magenta under the pointer, glowing edges on every raised surface, and sharp corners.
+// Data, not a stylesheet — `defineTheme({ preset: 'scifi' })` renders it, and `presets.test.ts`
+// holds it to every pairing in `CONTRAST_PAIRS` plus the chart series' colour-blind floor.
+
+import type { ThemePreset } from './preset-shape';
+
+export const SCIFI_PRESET: ThemePreset = {
+  colors: {
+    light: {
+      bg: '240 245 250',
+      'bg-soft': '229 236 244',
+      surface: '247 250 253',
+      'surface-raised': '255 255 255',
+      fg: '20 28 42',
+      'fg-strong': '4 8 18',
+      'fg-muted': '70 84 104',
+      line: '176 192 212',
+      scrim: '2 4 10',
+      accent: '0 108 135',
+      'accent-strong': '168 0 124',
+      'accent-fg': '255 255 255',
+      success: '0 112 70',
+      'success-soft': '220 244 234',
+      'success-fg': '255 255 255',
+      warning: '140 82 0',
+      'warning-soft': '252 240 214',
+      'warning-fg': '255 255 255',
+      danger: '185 30 50',
+      'danger-soft': '253 228 232',
+      'danger-fg': '255 255 255',
+      info: '30 90 190',
+      'info-soft': '225 236 252',
+      'info-fg': '255 255 255',
+      'chart-1': '0 112 140',
+      'chart-2': '179 5 130',
+      'chart-3': '189 107 14',
+      'chart-4': '59 110 49',
+      'chart-5': '70 70 210',
+      'chart-6': '188 28 13',
+      'chart-7': '106 97 20',
+      'chart-8': '60 60 60',
+    },
+    dark: {
+      bg: '5 7 13',
+      'bg-soft': '9 12 21',
+      surface: '13 17 29',
+      'surface-raised': '20 26 42',
+      fg: '210 225 240',
+      'fg-strong': '240 250 255',
+      'fg-muted': '125 145 170',
+      line: '44 60 88',
+      scrim: '0 0 0',
+      accent: '0 229 255',
+      'accent-strong': '255 92 214',
+      'accent-fg': '2 8 16',
+      success: '40 230 150',
+      'success-soft': '6 36 28',
+      'success-fg': '2 16 10',
+      warning: '255 200 60',
+      'warning-soft': '40 30 6',
+      'warning-fg': '22 14 0',
+      danger: '255 95 120',
+      'danger-soft': '46 12 22',
+      'danger-fg': '26 4 10',
+      info: '110 170 255',
+      'info-soft': '10 26 50',
+      'info-fg': '2 10 24',
+      'chart-1': '48 229 255',
+      'chart-2': '238 88 205',
+      'chart-3': '170 255 90',
+      'chart-4': '255 175 26',
+      'chart-5': '148 130 255',
+      'chart-6': '255 110 90',
+      'chart-7': '88 198 148',
+      'chart-8': '204 214 216',
+    },
+  },
+  // Dark only: a black drop shadow is invisible on a near-black page, so elevation there is an
+  // accent hairline plus a halo, with the drop kept under it for depth. Light keeps the shipped
+  // rungs, whose glows already read the (now cyan) accent.
+  shadows: {
+    dark: {
+      xs: '0 0 0 1px rgb(var(--color-accent) / 0.14)',
+      sm: '0 0 0 1px rgb(var(--color-accent) / 0.18), 0 2px 10px rgb(0 0 0 / 0.6)',
+      md: '0 0 0 1px rgb(var(--color-accent) / 0.22), 0 0 18px rgb(var(--color-accent) / 0.12), 0 8px 24px rgb(0 0 0 / 0.6)',
+      lg: '0 0 0 1px rgb(var(--color-accent) / 0.26), 0 0 28px rgb(var(--color-accent) / 0.14), 0 16px 40px rgb(0 0 0 / 0.7)',
+      xl: '0 0 0 1px rgb(var(--color-accent) / 0.3), 0 0 40px rgb(var(--color-accent) / 0.16), 0 28px 64px rgb(0 0 0 / 0.75)',
+      'glow-sm': '0 0 8px rgb(var(--color-accent) / 0.6)',
+      'glow-md': '0 0 16px rgb(var(--color-accent) / 0.5)',
+      'glow-lg': '0 0 32px rgb(var(--color-accent) / 0.45)',
+      // Coloured elevation in the second accent, so a lifted card reads magenta beside cyan edges.
+      'tinted-sm': '0 2px 10px rgb(var(--color-accent-strong) / 0.3)',
+      'tinted-md': '0 6px 20px rgb(var(--color-accent-strong) / 0.34)',
+      'tinted-lg': '0 14px 40px rgb(var(--color-accent-strong) / 0.38)',
+    },
+  },
+  radius: { sm: '0.125rem', md: '0.25rem', lg: '0.375rem', xl: '0.5rem' },
+};

package/src/theme/preset-shape.ts

@@ -0,0 +1,18 @@
+// What a theme preset IS: a complete palette for both themes plus optional shadow, radius and font
+// overrides — the same slots `defineTheme()` takes, with colours made total so a preset is measured
+// alone and never leans on the default palette to pass.
+
+import type { ColorRole, RadiusName, ShadowName, Theme } from '../tokens/tokens';
+
+/** The font slots `_typography.scss` emits — `defineTheme()` validates against this list. */
+export const FONT_SLOTS = ['sans', 'mono', 'data'] as const;
+export type FontSlot = (typeof FONT_SLOTS)[number];
+
+export interface ThemePreset {
+  readonly colors: Readonly<Record<Theme, Readonly<Record<ColorRole, string>>>>;
+  readonly shadows?: Readonly<
+    Partial<Record<Theme, Readonly<Partial<Record<ShadowName, string>>>>>
+  >;
+  readonly radius?: Readonly<Partial<Record<RadiusName, string>>>;
+  readonly font?: Readonly<Partial<Record<FontSlot, string>>>;
+}

package/src/theme/presets.ts

@@ -0,0 +1,15 @@
+// The presets `defineTheme({ preset })` accepts. A preset is a BASE the app's own overrides layer
+// onto, role by role — never a mode with rules of its own — so every check the brand seam makes
+// runs over the merged result. Adding one is a row here plus its file; `presets.test.ts` measures
+// every row against the full contrast table.
+
+import { SCIFI_PRESET } from './preset-scifi';
+import type { ThemePreset } from './preset-shape';
+
+export const THEME_PRESETS = {
+  scifi: SCIFI_PRESET,
+} as const satisfies Readonly<Record<string, ThemePreset>>;
+
+export type ThemePresetName = keyof typeof THEME_PRESETS;
+
+export const THEME_PRESET_NAMES = Object.keys(THEME_PRESETS) as readonly ThemePresetName[];

package/src/theme/shadow-value.ts

@@ -0,0 +1,39 @@
+// The grammar a `defineTheme()` shadow override must match. Validated, never escaped: the value is
+// written into a `<style>` element, so the only safe answer to a `;`, a `}` or a `</style>` is a
+// refusal. Strict enough to hold that line, wide enough for every rung `_shadow.scss` ships.
+
+import { COLOR_ROLES } from '../tokens/color-tokens';
+
+/** `0`, or a signed length in a unit a shadow is written in. No `calc()`, no `var()`. */
+const LENGTH = String.raw`(?:0|-?\d+(?:\.\d+)?(?:px|rem|em))`;
+const ALPHA = String.raw`(?:0|1|0?\.\d+)`;
+const CHANNEL = String.raw`\d{1,3}`;
+/** A role reference, so a shadow can follow the theme — the shape `t.role()` compiles to. */
+const ROLE_COLOUR = String.raw`rgb\(var\(--color-([a-z0-9-]+)\) / ${ALPHA}\)`;
+const CHANNEL_COLOUR = String.raw`rgb\((${CHANNEL}) (${CHANNEL}) (${CHANNEL})(?: / ${ALPHA})?\)`;
+const LAYER = `(?:inset )?${LENGTH} ${LENGTH}(?: ${LENGTH}){0,2} (?:${ROLE_COLOUR}|${CHANNEL_COLOUR})`;
+
+const LAYER_PATTERN = new RegExp(`^${LAYER}$`);
+
+/** Long enough for five layers; a value past it is not a shadow anyone designed. */
+const MAX_LENGTH = 400;
+
+export const SHADOW_EXPECTED =
+  'a box-shadow such as "0 4px 14px rgb(17 15 13 / 0.1)" or "0 0 14px rgb(var(--color-accent) / 0.4)" — layers comma-separated, colours as rgb() over channels or a colour role, or "none"';
+
+/**
+ * Whether `value` is a shadow this seam will write. Every layer is matched whole, every channel is
+ * 0–255, and every role a layer names is a role the palette has — a `--color-brand` that resolves
+ * to nothing would render no shadow at all and no error anywhere.
+ */
+export function isShadowValue(value: string): boolean {
+  if (value === 'none') return true;
+  if (value.length === 0 || value.length > MAX_LENGTH) return false;
+  return value.split(', ').every((layer) => {
+    const match = LAYER_PATTERN.exec(layer);
+    if (match === null) return false;
+    const [, role, r, g, b] = match;
+    if (role !== undefined) return (COLOR_ROLES as readonly string[]).includes(role);
+    return [r, g, b].every((channel) => Number(channel) <= 255);
+  });
+}

package/src/theme/theme.ts

@@ -1,19 +1,26 @@
-// Theme resolution. One rule: an explicit choice in storage wins, otherwise the
-// OS decides. Every side effect goes through an injected `ThemeEnv`, so this is
-// testable without a DOM and reusable on the server.
+// Theme resolution. One rule: an explicit choice in storage wins, then the theme the boot script
+// already stamped on the document, then the app's `theme.defaultMode` (the OS for `'system'`). Every side effect
+// goes through an injected `ThemeEnv`, so this is testable without a DOM and reusable on the server.
 
+import { THEME_STORAGE_KEY } from '@ultimat3/core';
 import { invalidThemeError, runtimeMissingError } from '../errors';
 import type { Theme } from '../tokens/tokens';
 
 export type { Theme };
 
-export const THEME_STORAGE_KEY = 'ultimate.theme';
 export const THEME_ATTRIBUTE = 'data-theme';
+/** Where the boot script records `theme.defaultMode` itself — `'light'`, `'dark'` or `'system'`.
+ *  `@ultimat3/render`'s `themeScriptBody` writes `${attribute}-default`; this is that name. */
+export const THEME_DEFAULT_ATTRIBUTE = `${THEME_ATTRIBUTE}-default`;
 export const THEME_MEDIA_QUERY = '(prefers-color-scheme: dark)';
 
 /** The host capabilities theme control needs. Injected so tests need no DOM. */
 export interface ThemeEnv {
   read(): string | null;
+  /** The theme the document carries right now — what the boot script stamped, or the last apply. */
+  current(): string | null;
+  /** The app's `theme.defaultMode` as the boot stamped it, or `null` when no boot ran. */
+  appDefault(): string | null;
   write(value: string): void;
   remove(): void;
   prefersDark(): boolean;
@@ -40,9 +47,25 @@ export function osTheme(env: ThemeEnv): Theme {
   return env.prefersDark() ? 'dark' : 'light';
 }
 
-/** Resolution order: explicit stored choice -> OS preference. */
+/**
+ * What "no explicit choice" means for this app: its fixed `theme.defaultMode` when it has one, the
+ * OS when it is `'system'` or unknown. Clearing a choice and following the OS both answer this, so
+ * an app that opens dark is never flipped light by an OS change or a "system" pick.
+ */
+export function defaultTheme(env: ThemeEnv): Theme {
+  const fixed = env.appDefault();
+  return isTheme(fixed) ? fixed : osTheme(env);
+}
+
+/**
+ * Resolution order: explicit stored choice -> the theme on the document -> OS preference. The
+ * middle step is the app's default: with `theme.defaultMode: 'dark'` the boot script stamps dark
+ * on a light-OS machine, and answering the OS here made the first toggle write the theme already
+ * on screen — a click that did nothing.
+ */
 export function resolveTheme(env: ThemeEnv): Theme {
-  return storedTheme(env) ?? osTheme(env);
+  const current = env.current();
+  return storedTheme(env) ?? (isTheme(current) ? current : defaultTheme(env));
 }
 
 /** Run once on load. Idempotent — safe after the inline head script. */
@@ -60,10 +83,10 @@ export function setTheme(theme: Theme, env: ThemeEnv = browserThemeEnv()): Theme
   return theme;
 }
 
-/** Forget the explicit choice and follow the OS again. */
+/** Forget the explicit choice and return to the app's default (the OS, for `'system'`). */
 export function clearTheme(env: ThemeEnv = browserThemeEnv()): Theme {
   env.remove();
-  const theme = osTheme(env);
+  const theme = defaultTheme(env);
   env.apply(theme);
   return theme;
 }
@@ -74,12 +97,12 @@ export function toggleTheme(env: ThemeEnv = browserThemeEnv()): Theme {
 }
 
 /**
- * Follow the OS live — but only while the user has made no explicit choice.
- * Returns an unsubscribe so a component can drop it on cleanup.
+ * Follow the OS live — but only while the user has made no explicit choice AND the app's default
+ * is the OS. Returns an unsubscribe so a component can drop it on cleanup.
  */
 export function watchOsTheme(env: ThemeEnv = browserThemeEnv()): () => void {
   return env.observeOs(() => {
-    if (storedTheme(env) === null) env.apply(osTheme(env));
+    if (storedTheme(env) === null && !isTheme(env.appDefault())) env.apply(osTheme(env));
   });
 }
 
@@ -94,6 +117,8 @@ export function browserThemeEnv(): ThemeEnv {
   const media = window.matchMedia(THEME_MEDIA_QUERY);
   return {
     read: () => safeStorage(() => window.localStorage.getItem(THEME_STORAGE_KEY), null),
+    current: () => document.documentElement.getAttribute(THEME_ATTRIBUTE),
+    appDefault: () => document.documentElement.getAttribute(THEME_DEFAULT_ATTRIBUTE),
     write: (value) => safeStorage(() => window.localStorage.setItem(THEME_STORAGE_KEY, value)),
     remove: () => safeStorage(() => window.localStorage.removeItem(THEME_STORAGE_KEY)),
     prefersDark: () => media.matches,

package/src/toast/toast-store.ts

@@ -84,7 +84,7 @@ function defaultEnv(): ToastEnv {
   return typeof document === 'undefined' ? INERT_TOAST_ENV : browserToastEnv();
 }
 
-export function createToastStore(env: ToastEnv = defaultEnv()): ToastStore {
+export function toastStore(env: ToastEnv = defaultEnv()): ToastStore {
   const holds = new Set<ToastHold>();
   const listeners = new Set<(queue: ToastQueue) => void>();
   let queue: ToastQueue = EMPTY_TOAST_QUEUE;

package/src/toast/use-toasts.ts

@@ -1,4 +1,4 @@
-// The reactive shell over `createToastStore`, and the whole of what it adds: the queue lands in a
+// The reactive shell over `toastStore`, and the whole of what it adds: the queue lands in a
 // signal, so `<Toaster>` re-renders when a message arrives or a dwell runs out.
 //
 // The subscription lives in an EFFECT, which is the package's one seam for DOM-only work: a server

package/src/tokens/_colors.scss

@@ -1,6 +1,10 @@
 // Canonical colour token source. Semantic roles only, stored as space-separated
 // RGB channels so `rgb(var(--color-x) / 0.5)` composites without a second token.
 // `tokens.ts` mirrors these values; `x verify` fails if the two drift.
+//
+// `chart-1` … `chart-8` are the categorical series: Okabe–Ito hues, darkened for the light page and
+// lifted for the dark one until each clears 3:1 on every surface and every pair stays apart under
+// protan/deutan/tritan simulation (`contrast.test.ts`, `colour-vision.test.ts`).
 
 $light: (
   bg: 253 246 240,
@@ -27,6 +31,14 @@ $light: (
   info: 31 110 178,
   info-soft: 224 239 252,
   info-fg: 255 255 255,
+  chart-1: 0 107 170,
+  chart-2: 189 107 14,
+  chart-3: 0 125 90,
+  chart-4: 189 44 16,
+  chart-5: 170 70 140,
+  chart-6: 47 135 195,
+  chart-7: 118 97 18,
+  chart-8: 60 60 60,
 );
 
 $dark: (
@@ -54,6 +66,14 @@ $dark: (
   info: 96 170 240,
   info-soft: 22 38 56,
   info-fg: 12 20 30,
+  chart-1: 105 201 255,
+  chart-2: 230 153 0,
+  chart-3: 0 167 113,
+  chart-4: 236 111 60,
+  chart-5: 203 126 189,
+  chart-6: 124 153 252,
+  chart-7: 246 234 72,
+  chart-8: 181 181 180,
 );
 
 /// The tone vocabulary, in the order components expose it. Mirrors `TONES` in

package/src/tokens/_effects.scss

@@ -0,0 +1,59 @@
+// Surface effects a dashboard opts into: a glowing edge and a grid/scanline ground. Paired with
+// the `scifi` preset (`defineTheme({ preset: 'scifi' })`) and meaningful without it — every colour
+// is a role and every glow a shadow token, so each follows whatever palette the page resolved.
+// Nothing here animates, so there is no motion for `prefers-reduced-motion` to take away.
+
+@use 'colors';
+@use 'shadow';
+@use 'space';
+@use 'stroke';
+
+/// A hairline ring in the accent plus a glow rung, as one `box-shadow`. For a live tile, a focused
+/// panel, a selected series. Forced-colours mode drops box shadows itself; the `border` an
+/// element already has is what remains there, which is why this draws no border of its own.
+@mixin glow-edge($glow: 'glow-sm', $alpha: 0.55) {
+  box-shadow:
+    inset 0 0 0 stroke.stroke(hairline) colors.role('accent', $alpha),
+    shadow.shadow($glow);
+}
+
+/// A faint accent grid on one spacing pitch, with optional horizontal scanlines over it: the
+/// "instrument panel" ground. Only `background-image` and `background-size` are written, so the
+/// element's own `background-color` shows through. Withdrawn under `prefers-contrast: more` and
+/// `forced-colors: active`, where texture behind text is noise and not atmosphere.
+@mixin grid-texture($pitch: space.space(6), $alpha: 0.08, $scanlines: true) {
+  $grid-x: linear-gradient(
+    90deg,
+    colors.role('accent', $alpha) stroke.stroke(hairline),
+    transparent stroke.stroke(hairline)
+  );
+  $grid-y: linear-gradient(
+    180deg,
+    colors.role('accent', $alpha) stroke.stroke(hairline),
+    transparent stroke.stroke(hairline)
+  );
+
+  @if $scanlines {
+    background-image:
+      repeating-linear-gradient(
+        180deg,
+        colors.role('fg', $alpha * 0.5) 0 stroke.stroke(hairline),
+        transparent stroke.stroke(hairline) stroke.stroke(heavy)
+      ),
+      $grid-x,
+      $grid-y;
+    background-size:
+      auto,
+      $pitch $pitch,
+      $pitch $pitch;
+  } @else {
+    background-image: $grid-x, $grid-y;
+    background-size:
+      $pitch $pitch,
+      $pitch $pitch;
+  }
+
+  @media (prefers-contrast: more), (forced-colors: active) {
+    background-image: none;
+  }
+}