@appinternalleads/ui 0.2.0

package/src/sheets/records.ts

@@ -0,0 +1,138 @@
+import { inferColumns } from '../components/directory/contract';
+import type { Checklist } from '../components/checklist/contract';
+import type { ColumnDef, DataRow } from '../components/onboarding/data-view/contract';
+import type { SheetTable } from './csv';
+import { LIST_MAX_ITEMS, type SheetMapping } from './bind';
+
+/**
+ * **A sheet as records** — for the components whose input IS rows rather than a list inside a
+ * config: Table and Grid (every row a record, every column a column), and Checklist (every row a
+ * task). Column types are discovered with the same `inferColumns` Directory uses, so a sheet reads
+ * the same way everywhere.
+ */
+
+const MONEY = /^[\s]*[$£€]/;
+const CURRENCY: Record<string, string> = { $: 'USD', '£': 'GBP', '€': 'EUR' };
+const URL_SHAPE = /^https?:\/\//i;
+const num = (s: string) => Number(s.replace(/[\s,$£€%]/g, ''));
+
+/** A sheet → Table / Grid columns and rows. The first column is the title, as the data-view contract says. */
+export function dataRowsFromSheet(table: SheetTable): { columns: ColumnDef[]; rows: DataRow[] } {
+  const clean = table.rows.filter(r => r.some(c => c.trim() !== ''));
+  const found = inferColumns(table.headers, clean);
+  const used = new Set<string>();
+  const columns: ColumnDef[] = found.map((c, i) => {
+    let id = c.key.toLowerCase().replace(/[^a-z0-9]+/g, '_').replace(/^_|_$/g, '') || `col_${i + 1}`;
+    while (used.has(id)) id = `${id}_${i + 1}`;
+    used.add(id);
+    const values = clean.map(r => (r[i] ?? '').trim()).filter(Boolean);
+    const col: ColumnDef = { id, label: c.label, type: 'text', width: Math.min(260, Math.max(110, c.label.length * 9 + 40)) };
+    if (i === 0) return col;
+    if (values.length && values.every(v => URL_SHAPE.test(v))) return { ...col, type: 'link', href: '', external: true };
+    if (values.length && values.every(v => MONEY.test(v) && Number.isFinite(num(v)))) {
+      return { ...col, type: 'currency', currency: CURRENCY[values[0]!.trim()[0]!] ?? 'USD' };
+    }
+    if (c.type === 'number') return { ...col, type: 'number' };
+    if (c.type === 'date') return { ...col, type: 'date' };
+    if (c.type === 'enum' || c.type === 'boolean') {
+      return { ...col, type: 'status', tones: Object.fromEntries((c.distinctValues ?? [...new Set(values)]).map(v => [v, 'plain' as const])) };
+    }
+    return col;
+  });
+  const rows: DataRow[] = clean.map((r, ri) => {
+    const row: DataRow = { id: `r${ri + 1}` };
+    columns.forEach((col, ci) => {
+      const raw = (r[ci] ?? '').trim();
+      if (raw === '') { row[col.id] = null; return; }
+      row[col.id] = col.type === 'number' || col.type === 'currency' ? num(raw)
+        : col.type === 'date' ? Date.parse(raw)
+        : raw;
+    });
+    return row;
+  });
+  return { columns, rows };
+}
+
+const norm = (s: string) => s.toLowerCase().replace(/[^a-z0-9]/g, '');
+
+/** The checklist fields a sheet fills, as a person reads them. */
+export const CHECKLIST_LABELS: Record<string, string> = { title: 'Task', section: 'Section', description: 'Description', required: 'Required', assignee: 'Assignee', done: 'Done' };
+
+/** The type each checklist column holds. */
+export const CHECKLIST_TYPES: Record<string, string> = { title: 'text', section: 'text', description: 'text', required: 'yes/no', assignee: 'text', done: 'yes/no' };
+const YES = /^(y|yes|true|1|x|✓|✔|done|complete|completed)$/i;
+const NO = /^(n|no|false|0|optional)$/i;
+
+/**
+ * A sheet → a checklist: one row per task. Columns (any order, any case): **Task** or **Title**
+ * (required), **Section**, **Description**, **Required** (no / optional → optional), **Assignee**
+ * (a person id the host's people boundary resolves), **Done**. A column named exactly wins; failing
+ * that, one whose name ends with it ("Book title" → Title). Rows keep the sheet's order; a new
+ * Section value starts a new section. At most `maxTasks` rows are read.
+ */
+export function checklistFromSheet(
+  table: SheetTable,
+  base: { id: string; title: string; description?: string },
+  opts: { maxTasks?: number; mapping?: SheetMapping } = {},
+): { checklist: Checklist; missing: string[]; total: number; used: number; columns: { header: string; field: string; fixed?: boolean; manual?: boolean }[]; mappingErrors: string[] } {
+  const mapping = opts.mapping ?? {};
+  const mappingErrors: string[] = [];
+  const fixed: Record<string, string> = {};
+  /* A field assigned by hand — a column, a value for every row, or nothing — wins over the names below. */
+  const col = (field: string, ...names: string[]) => {
+    if (field in mapping) {
+      const to = mapping[field];
+      if (to === null) return -1;
+      if (typeof to === 'object') { fixed[field] = to.value; return -1; }
+      const i = table.headers.findIndex(h => h.trim().toLowerCase() === (to ?? '').trim().toLowerCase());
+      if (i < 0) mappingErrors.push(`${CHECKLIST_LABELS[field] ?? field} is assigned the column “${to}”, which the sheet does not have.`);
+      return i;
+    }
+    const exact = table.headers.findIndex(h => names.includes(norm(h)));
+    return exact >= 0 ? exact : table.headers.findIndex(h => names.some(n => norm(h).endsWith(n)));
+  };
+  const c = { title: col('title', 'task', 'title', 'name'), section: col('section', 'section', 'group', 'phase'), description: col('description', 'description', 'details', 'notes'), required: col('required', 'required'), assignee: col('assignee', 'assignee', 'assigneeid', 'owner'), done: col('done', 'done', 'complete', 'completed', 'status') };
+  const missing = c.title < 0 && fixed.title === undefined ? ['Task (or Title)'] : [];
+  const sections: Checklist['sections'] = [];
+  const at = (r: string[], i: number) => (i >= 0 ? (r[i] ?? '').trim() : '');
+  const value = (r: string[], field: keyof typeof c) => (fixed[field] !== undefined ? fixed[field]!.trim() : at(r, c[field]));
+  const all = table.rows.filter(r => r.some(x => x.trim() !== ''));
+  const rows = all.slice(0, opts.maxTasks ?? LIST_MAX_ITEMS);
+  rows.forEach((r, i) => {
+    const title = value(r, 'title');
+    if (!title) return;
+    const sectionTitle = value(r, 'section');
+    let section = sections[sections.length - 1];
+    if (!section || (section.title ?? '') !== sectionTitle) {
+      section = { id: `s${sections.length + 1}`, ...(sectionTitle ? { title: sectionTitle } : {}), tasks: [] };
+      sections.push(section);
+    }
+    const req = value(r, 'required');
+    const assignee = value(r, 'assignee');
+    const description = value(r, 'description');
+    section.tasks.push({
+      id: `t${i + 1}`,
+      title,
+      ...(description ? { description } : {}),
+      done: YES.test(value(r, 'done')),
+      ...(req && NO.test(req) ? { required: false } : {}),
+      ...(assignee ? { assigneeId: assignee } : {}),
+    });
+  });
+  const columns = [
+    ...(Object.entries(c) as [string, number][]).filter(([, i]) => i >= 0).sort((a, b) => a[1] - b[1])
+      .map(([field, i]) => ({ header: table.headers[i]!, field, ...(field in mapping ? { manual: true } : {}) })),
+    ...Object.entries(fixed).map(([field, v]) => ({ header: `“${v}” in every row`, field, fixed: true, manual: true })),
+  ];
+  return { checklist: { ...base, sections: sections.length ? sections : [{ id: 's1', tasks: [] }] }, missing, total: all.length, used: rows.length, columns, mappingErrors };
+}
+
+/** A checklist → the sheet `checklistFromSheet` reads — the template to start from. */
+export function sheetFromChecklist(checklist: Checklist): SheetTable {
+  return {
+    headers: ['Section', 'Task', 'Description', 'Required', 'Assignee', 'Done'],
+    rows: checklist.sections.flatMap(s => s.tasks.map(t => [
+      s.title ?? '', t.title, t.description ?? '', t.required === false ? 'no' : 'yes', t.assigneeId ?? '', t.done ? 'yes' : 'no',
+    ])),
+  };
+}

package/src/tokens/DsProvider.tsx

@@ -0,0 +1,281 @@
+import React, { createContext, useCallback, useContext, useMemo, useState } from 'react';
+import { Platform, type BackgroundImageValue } from 'react-native';
+import {
+  edgeFor,
+  focusEdgeFor,
+  liftFor,
+  paletteFor,
+  substrateFor,
+  radii,
+  solariumRadii,
+  type Colors,
+  type Mode,
+  type Surface,
+  type Theme,
+} from './tokens';
+import {
+  actionColorsFor,
+  defaultDensityFor,
+  DENSITIES,
+  type ActionColors,
+  type Density,
+  type DensityName,
+} from './profile';
+
+/**
+ * ONE thing the user picks — typeface — and one the device decides, the surface.
+ *
+ * Mode and accent used to live here too. Warm paper has one accent and one mode, so both
+ * are gone; the provider is what it always should have been, which is where the material
+ * is resolved so no screen ever inlines a shadow.
+ *
+ * **Two shipped preferences were removed by this shift and both are real losses:** the
+ * five user accents (Pine, Azure, Violet, Magenta, Amber) and dark mode. Restoring the
+ * accents means re-scoping `accentFill` / `accentInk` / `accentTint`, and each new accent
+ * needs its own tint at the same lightness as `#F7E7DE` — a tint even slightly too dark
+ * stops reading as paper, which is the actual work.
+ */
+
+export type TypefaceName = 'system' | 'humanist' | 'serif';
+
+/** See `Ds.headings`. */
+export type Headings = 'title' | 'screen';
+
+export type Typeface = {
+  label: string;
+  note: string;
+  /** undefined = the platform's own face. */
+  sans: string | undefined;
+  mono: string;
+};
+
+/**
+ * The mono face. On the web, the Solarium handoffs' stack — `ui-monospace` (SF Mono on Apple
+ * platforms), then SF Mono and Menlo by name, then the generic `monospace` (which alone resolves
+ * to Courier in most browsers). Native takes one family name, not a stack, so it names one.
+ */
+export const MONO_STACK_WEB = "ui-monospace, 'SF Mono', Menlo, monospace";
+const MONO = Platform.select({ ios: 'Menlo', android: 'monospace', web: MONO_STACK_WEB, default: 'monospace' });
+
+export const TYPEFACES: Record<TypefaceName, Typeface> = {
+  system: {
+    label: 'System',
+    note: 'The platform’s own face. What the design assumes.',
+    sans: undefined,
+    mono: MONO,
+  },
+  humanist: {
+    label: 'Humanist',
+    note: 'Warmer, wider letterforms. Falls back to the system face on Android.',
+    /* On the web, the Solarium onboarding handoff's stack: Avenir Next where the OS has it, then
+       Nunito Sans — which the HOST loads (the library ships no font files; 0.2.0 lists them as an
+       open dependency) — then Trebuchet and the system face. Native names one family. */
+    sans: Platform.OS === 'android' ? undefined
+      : Platform.OS === 'web' ? "'Avenir Next', 'Nunito Sans', 'Trebuchet MS', system-ui, sans-serif"
+      : 'Avenir Next',
+    mono: MONO,
+  },
+  serif: {
+    label: 'Serif',
+    note: 'Georgia on iOS, the platform serif on Android.',
+    sans: Platform.OS === 'android' ? 'serif' : 'Georgia',
+    mono: MONO,
+  },
+};
+
+type Ds = {
+  /** There is one mode. Kept on the context so call sites compile — see `tokens.ts`. */
+  mode: Mode;
+  surface: Surface;
+  /** Which palette this app is painted in. `paper` unless the app asked for otherwise. */
+  theme: Theme;
+  colors: Colors;
+  /** Lift-1: rows, cards, sheets. The compatibility name most components ask for. */
+  edge: string;
+  /** Lift-2: the tab bar and nav bar. */
+  edge2: string;
+  /** Lift-3: dialogs. */
+  edge3: string;
+  /** Focus darkens the field hairline. There is no colour ring anywhere in this system. */
+  focusEdge: string;
+  /**
+   * The page gradient — the warmth of the paper, full-bleed, never interactive.
+   *
+   * **Empty when the app asked for a flat page**, which is a real state and not a missing
+   * value: `experimental_backgroundImage: []` draws no layers, so the `backgroundColor`
+   * beneath it is the page. Read it through `useSubstrateStyle()` rather than testing it.
+   */
+  substrate: readonly BackgroundImageValue[];
+  /**
+   * **Lift-1 and lift-2, on the context rather than imported.**
+   *
+   * `lift1` and `lift2` are still exported from `tokens.ts` as module constants, and they
+   * cannot be theme-aware: they are evaluated at import time, before an app has had the
+   * chance to say which theme it wants. Reading them from here is what makes a component
+   * follow the theme, so a screen moves from the import to these fields as it is reskinned.
+   */
+  lift1: string;
+  lift2: string;
+  /** The radius ladder for this theme. Solarium's rungs differ; see `solariumRadii`. */
+  radii: typeof radii | typeof solariumRadii;
+  /**
+   * **Which heading rungs the shared chrome renders** — `AppHeader`'s title and the mono
+   * eyebrow on `SectionHeader`/`SectionLabel`.
+   *
+   * `title` is v2's 22px title and 12px eyebrow, which canvas-app and Build keep. `screen` is
+   * the KeyShort handoff's 32px `screenTitle` and 10px/0.12em `eyebrowDense`, on every screen
+   * alike. A provider knob for the same reason `theme` and `page` are: one package serves
+   * three apps, and a rung change in a component shared by 26 files is an app's decision,
+   * not the design system's. D4/D5 in the KeyShort task board.
+   */
+  headings: Headings;
+  /** The primary action's fill, its hover, its ink, and the switch tracks. */
+  action: ActionColors;
+  /** Row and control sizing. Web `default`, native `comfortable`, unless the app said. */
+  densityName: DensityName;
+  density: Density;
+  fonts: Typeface;
+  typeface: TypefaceName;
+  /** Pass null to go back to following the system. */
+  setTypeface: (t: TypefaceName) => void;
+};
+
+/** No layers, so `useSubstrateStyle`'s `backgroundColor` is the whole page. */
+const FLAT_PAGE: readonly BackgroundImageValue[] = Object.freeze([]);
+
+const DsContext = createContext<Ds | null>(null);
+
+const isTypeface = (v: string): v is TypefaceName => v in TYPEFACES;
+
+/**
+ * The system setting is deliberately NOT read. Warm neutrals do not invert — flipping this
+ * ink ramp against a dark ground gives muddy khaki, not a dark theme, and a dark page is
+ * not paper, it is glass. A dark theme here is a separate ramp, not a transform, and until
+ * it exists a dark system setting is answered by staying light.
+ */
+const MODE: Mode = 'light';
+
+/**
+ * Where the typeface choice is kept, supplied by the app.
+ *
+ * The design system deliberately does NOT reach for storage itself. It used to read MMKV
+ * directly, which was fine while there was one app and became wrong the moment there were
+ * two: that store is keyed `keyboard-app`, so a shared design system reading it would have
+ * had one app persisting into the other's preferences.
+ *
+ * Omit it and the choice simply doesn't survive a relaunch — the right default for a
+ * consumer that has no opinion, and never a crash.
+ */
+export type TypefaceStore = {
+  read: () => string | undefined;
+  write: (t: TypefaceName) => void;
+};
+
+export function DsProvider({
+  children,
+  typefaceStore,
+  theme = 'paper',
+  page = 'flat',
+  headings = 'title',
+  density,
+}: {
+  children: React.ReactNode;
+  typefaceStore?: TypefaceStore;
+  /** Heading rungs for the shared chrome — see `Ds.headings`. Defaults to v2's, so an app that
+   *  says nothing is untouched. */
+  headings?: Headings;
+  /**
+   * **Which palette to paint in. Defaults to `paper`, so Key and Build are untouched.**
+   *
+   * A prop rather than a build-time constant because this package is one copy across three
+   * apps — see the `Theme` note in `tokens.ts`. Ambi passes `solarium`; an app that says
+   * nothing keeps exactly the system it has today.
+   */
+  theme?: Theme;
+  /**
+   * **Whether this app's page carries the theme's gradient, or is the flat ground.**
+   *
+   * A second per-app knob for the same reason as `theme`, and it exists because the page turns
+   * out to be an APP's decision rather than a palette's. Solarium's own ground is the flat
+   * `--ground`; the vertical gradient under `solarium` is Ambi's, specified by its handoff so
+   * that warmth collects under a composer pinned to the bottom of the screen. Key has a tab bar
+   * there, not a composer, and its handoff paints the page flat — so on Key the gradient reads
+   * as an unexplained pink wash across the lower third.
+   *
+   * **`flat` is the default (S3b, 12 Sep 2026, product decision) — inverted from `gradient`.**
+   * Solarium's own base page is flat; Ambi's gradient is Ambi's own addition on top of it, so an
+   * app that asks for nothing now gets the palette's actual ground rather than a design choice
+   * that happens to belong to one specific app. This DID repaint every consumer that was
+   * silently relying on the old default without saying so — not just the canvas app the
+   * decision named. Both Ambi (`canvas-app/App.tsx`) and Build (`turbo-waddle-building/App.tsx`)
+   * now pass `page="gradient"` explicitly to hold their exact prior appearance; Key already
+   * passed `page="flat"` explicitly and is unaffected either way.
+   */
+  page?: 'gradient' | 'flat';
+  /** Row and control density. Omit for the platform default. */
+  density?: DensityName;
+}) {
+  const [typeface, setTypefaceState] = useState<TypefaceName>(() => {
+    const saved = typefaceStore?.read();
+    return saved && isTypeface(saved) ? saved : 'system';
+  });
+
+  const surface: Surface = Platform.OS === 'android' ? 'android' : 'ios';
+
+  const densityName = density ?? defaultDensityFor(Platform.OS);
+
+  const setTypeface = useCallback(
+    (next: TypefaceName) => {
+      typefaceStore?.write(next);
+      setTypefaceState(next);
+    },
+    [typefaceStore],
+  );
+
+  const value = useMemo<Ds>(() => {
+    const colors = paletteFor(MODE, surface, theme);
+    return {
+      mode: MODE,
+      surface,
+      theme,
+      colors,
+      edge: edgeFor(MODE, surface, theme),
+      edge2: liftFor(surface, 2, theme),
+      edge3: liftFor(surface, 3, theme),
+      focusEdge: focusEdgeFor(MODE),
+      substrate: page === 'flat' ? FLAT_PAGE : substrateFor(MODE, theme),
+      lift1: liftFor(surface, 1, theme),
+      lift2: liftFor(surface, 2, theme),
+      radii: theme === 'solarium' ? solariumRadii : radii,
+      headings,
+      action: actionColorsFor(colors),
+      densityName,
+      density: DENSITIES[densityName],
+      fonts: TYPEFACES[typeface],
+      typeface,
+      setTypeface,
+    };
+  }, [surface, theme, page, headings, densityName, typeface, setTypeface]);
+
+  return <DsContext.Provider value={value}>{children}</DsContext.Provider>;
+}
+
+export function useDs(): Ds {
+  const ctx = useContext(DsContext);
+  if (!ctx) throw new Error('useDs must be used inside <DsProvider>');
+  return ctx;
+}
+
+/**
+ * **Override density for one subtree, keeping everything else the provider says.** A component's
+ * `density` prop is the host's presentation choice for that one component; wrapping it in a second
+ * `DsProvider` would also reset its theme and page. `undefined` inherits.
+ */
+export function DensityScope({ density, children }: { density?: DensityName; children: React.ReactNode }) {
+  const parent = useDs();
+  const value = useMemo<Ds>(
+    () => (density === undefined || density === parent.densityName ? parent : { ...parent, densityName: density, density: DENSITIES[density] }),
+    [parent, density],
+  );
+  return <DsContext.Provider value={value}>{children}</DsContext.Provider>;
+}

package/src/tokens/HueProvider.tsx

@@ -0,0 +1,22 @@
+import { createContext, useContext, type ReactNode } from 'react';
+import { HUE, type Hue, type HueSet } from './hue';
+
+/**
+ * The hue scope — what `.h-sky` was.
+ *
+ * **`neutral` is the fallback, so a hue-reading component mounted outside any scope still
+ * renders.** Solarium's CSS makes the same choice with a `:root` default; without it the
+ * component would read `undefined` and paint nothing, which looks like a broken build rather
+ * than a missing wrapper.
+ */
+const HueContext = createContext<Hue>('neutral');
+
+export function HueProvider({ hue, children }: { hue: Hue; children: ReactNode }) {
+  return <HueContext.Provider value={hue}>{children}</HueContext.Provider>;
+}
+
+/** The current hue's four values. The generic read — a descendant never names its own hue. */
+export function useHue(): HueSet & { name: Hue } {
+  const name = useContext(HueContext);
+  return { ...HUE[name], name };
+}

package/src/tokens/contrast.ts

@@ -0,0 +1,28 @@
+/**
+ * WCAG 2.1 relative luminance and contrast ratio.
+ *
+ * Lives beside the tokens rather than in the tests, because the palette is the thing being
+ * measured and a ratio computed somewhere else is a ratio that can disagree with it.
+ */
+
+function channel(v: number): number {
+  const c = v / 255;
+  return c <= 0.03928 ? c / 12.92 : ((c + 0.055) / 1.055) ** 2.4;
+}
+
+export function luminance(hex: string): number {
+  const m = /^#?([0-9a-f]{6})$/i.exec(hex.trim());
+  if (!m?.[1]) throw new Error(`Not a 6-digit hex: ${hex}`);
+  const n = parseInt(m[1], 16);
+  return (
+    0.2126 * channel((n >> 16) & 255) +
+    0.7152 * channel((n >> 8) & 255) +
+    0.0722 * channel(n & 255)
+  );
+}
+
+/** Rounded to two places, which is the precision the handoff states its own numbers in. */
+export function contrast(a: string, b: string): number {
+  const [x, y] = [luminance(a), luminance(b)].sort((p, q) => q - p) as [number, number];
+  return Math.round(((x + 0.05) / (y + 0.05)) * 100) / 100;
+}

package/src/tokens/glass.ts

@@ -0,0 +1,46 @@
+import { type ViewStyle } from 'react-native';
+import { useDs } from './DsProvider';
+import { fieldEdge } from './tokens';
+
+/**
+ * Paper, not glass.
+ *
+ * This file used to return a translucent fill and a four-sided specular rim. Both are gone:
+ * the page is paper now, so depth is a real drop shadow plus a hairline, and every raised
+ * surface is the same white. A card tinted away from the page reads as a highlight, and
+ * once everything is highlighted nothing is.
+ *
+ * The names survive so the screens built against them keep working — that was the bet the
+ * token layer made, and it held.
+ */
+
+/** A raised surface: rows, cards, sheets. Radius and padding are the caller's. */
+export function useGlassStyle(): ViewStyle {
+  const { colors, edge } = useDs();
+  return { backgroundColor: colors.surface1, boxShadow: edge };
+}
+
+/**
+ * An input. **A field is a hole in the paper, not an object on it, so it never lifts** —
+ * this returns the field edge, not a lift.
+ *
+ * `focused` darkens the hairline from 9% to 28% and nothing else: the edge IS the focus
+ * indicator, and there is no colour focus ring anywhere in this system. It has to stay
+ * visible at 200% text size.
+ */
+export function useFieldStyle(focused = false, error = false): ViewStyle {
+  const { colors } = useDs();
+  return {
+    backgroundColor: colors.surface1,
+    boxShadow: error ? fieldEdge.error : focused ? fieldEdge.focus : fieldEdge.default,
+  };
+}
+
+/** A disabled field, or an inset well. The one surface that is not white. */
+export function useSunkenStyle(): ViewStyle {
+  const { colors } = useDs();
+  return {
+    backgroundColor: colors.surfaceSunken,
+    boxShadow: 'inset 0 0 0 1px rgba(42,39,36,0.08)',
+  };
+}

package/src/tokens/hue.ts

@@ -0,0 +1,107 @@
+/**
+ * **Solarium's hue system — six families, four values each.**
+ *
+ * Its own README calls the two-line recipe "the whole system": a class sets four CSS variables
+ * on a container and every descendant reads *the current hue* generically.
+ *
+ * ```
+ * .h-sky   sets  --h  --hd  --hs  --on
+ * .tile         background var(--hs), color var(--hd)   resting
+ * .tile.on      background var(--h),  color var(--on)   active
+ * ```
+ *
+ * **React Native has no cascade, so the container becomes a provider and `var(--h)` becomes
+ * `useHue()`.** That is the translation SPEC §3.1 accepted as the cost of one core, and it is the
+ * part the token port could not carry — `tokens.ts` holds solarium's individual hues, but a hue
+ * is only a system when a descendant can read it without being told which one it is in.
+ *
+ * **Hue means CATEGORY, never state.** Success and warning are mint and apricot and live outside
+ * this system entirely — a category that turns green because something succeeded has stopped
+ * being a category.
+ */
+
+export const HUES = ['coral', 'butter', 'clay', 'sky', 'lilac', 'neutral'] as const;
+export type Hue = (typeof HUES)[number];
+
+/** `h` the mid rung · `hd` deep, for ink · `hs` soft, the resting ground · `on` ink on `h`. */
+export type HueSet = { h: string; hd: string; hs: string; on: string };
+
+export const HUE: Record<Hue, HueSet> = {
+  coral: { h: '#C1552C', hd: '#A8461F', hs: '#F6E3D7', on: '#FFFFFF' },
+  /**
+   * **Butter is the exception: its `on` is a dark brown, not white.** White on `#E9B949` is
+   * unreadable, and a system that returned `#fff` here uniformly would be wrong exactly once —
+   * which is the hardest kind of wrong to notice.
+   */
+  butter: { h: '#E9B949', hd: '#7D5F14', hs: '#FAF0D2', on: '#4D3B0B' },
+  clay: { h: '#D98E73', hd: '#96502F', hs: '#F9E8E0', on: '#FFFFFF' },
+  sky: { h: '#6E9FC4', hd: '#39648A', hs: '#E6EEF5', on: '#FFFFFF' },
+  lilac: { h: '#9C8FD0', hd: '#5F5099', hs: '#EEEBF7', on: '#FFFFFF' },
+  neutral: { h: '#B9B7AD', hd: '#6B6D63', hs: '#F1EFE7', on: '#FFFFFF' },
+};
+
+/**
+ * **Fixed assignments. A category keeps its hue across the entire product.**
+ *
+ * Never picked for visual balance on a given screen — that is what makes the colour mean
+ * something rather than decorate something.
+ */
+export const DESTINATION_HUE = {
+  Chat: 'butter',
+  'Work Canvas': 'coral',
+  Automations: 'lilac',
+  'My Emails': 'lilac',
+  'My Designs': 'sky',
+  Playground: 'sky',
+  Dashboards: 'clay',
+  Settings: 'neutral',
+} as const satisfies Record<string, Hue>;
+
+/**
+ * **Data and block types, each to its hue — all ten, transcribed from
+ * `solarium/src/components/ui/hue.ts`.** This held only `schedule` and `date` until the Building
+ * Blocks handoff (2026-09-23), whose `threshold-flow/1` schema resolves a component's hue from a
+ * `type` in exactly this set.
+ *
+ * **`action` is coral, and that is not the same thing as `kind.action` being butter.** The
+ * handoff listed this as open; Solarium's own source answers it. `kind.action` is a KeyShort
+ * shortcut kind drawn in the lightning tile's butter — a different vocabulary that happens to
+ * share a word. A `type: 'action'` block is the primary-action category, and coral is the hue
+ * Solarium reserves for that.
+ */
+export const TYPE_HUE = {
+  schedule: 'butter',
+  date: 'butter',
+  action: 'coral',
+  automation: 'lilac',
+  email: 'lilac',
+  agent: 'lilac',
+  file: 'sky',
+  design: 'sky',
+  data: 'clay',
+  unclassified: 'neutral',
+} as const satisfies Record<string, Hue>;
+
+export type DataType = keyof typeof TYPE_HUE;
+export const DATA_TYPES = Object.keys(TYPE_HUE) as DataType[];
+
+/**
+ * A block's hue: from its `type`, with `hue` as an explicit override.
+ *
+ * The override is allowed and warned about, as the schema says — a category repainted for one
+ * screen is a category that no longer means anything, so a disagreement is surfaced in
+ * development rather than silently honoured. No `type` and no `hue` is `neutral`, the same
+ * fallback `HueProvider` uses.
+ */
+/* Guarded: a web bundle with no `process` shim must not throw on a colour lookup. */
+function isProduction(): boolean {
+  return typeof process !== 'undefined' && process.env?.NODE_ENV === 'production';
+}
+
+export function hueForType(type?: DataType, hue?: Hue): Hue {
+  const fromType = type ? TYPE_HUE[type] : undefined;
+  if (hue && fromType && hue !== fromType && !isProduction()) {
+    console.warn(`[solarium] hue "${hue}" overrides TYPE_HUE.${type} ("${fromType}").`);
+  }
+  return hue ?? fromType ?? 'neutral';
+}

package/src/tokens/index.ts

@@ -0,0 +1,20 @@
+/**
+ * The token layer, ported verbatim from `canvas-app/packages/ds` — the canonical copy.
+ *
+ * **This directory holds the only hex literals in the package.** Everything else references a
+ * token by name, and the ESLint rule in §9 of SPEC.md makes that checkable rather than
+ * aspirational. If you are about to write a colour anywhere else, you want a token instead.
+ */
+export * from './tokens';
+export {
+  DensityScope, DsProvider, useDs, TYPEFACES,
+  type Typeface, type TypefaceName, type TypefaceStore,
+} from './DsProvider';
+export { useFieldStyle, useGlassStyle, useSunkenStyle } from './glass';
+export { contrast, luminance } from './contrast';
+export { HUE, HUES, DESTINATION_HUE, TYPE_HUE, DATA_TYPES, hueForType, type DataType, type Hue, type HueSet } from './hue';
+export { HueProvider, useHue } from './HueProvider';
+export {
+  DATA_REVEAL, MOTION, OUTPUT_MOTION_TIMINGS, motionFor, actionColorsFor, DENSITIES, defaultDensityFor,
+  type MotionTokens, type ActionColors, type Density, type DensityName,
+} from './profile';