@12-apps/ui 6.17.1 → 6.18.0

package/src/provider/mui-bridge.ts

@@ -0,0 +1,141 @@
+import type { PaletteColor, Theme, ThemeOptions } from '@mui/material/styles/index.js';
+
+import { cssLengthToPx, cssTrackingToEm } from '../tokens/css-units';
+import { accentFor } from '../tokens/scales';
+import {
+  FONT_WEIGHTS,
+  TYPE_SIZES,
+  WEB_FONT_FAMILY,
+  WEB_MONOSPACE_FONT_FAMILY,
+  type UiHeadingStep,
+  type UiPaletteColor,
+  type UiTheme,
+} from '../tokens/theme';
+import { HEADING_LEVELS, headingMetrics, type HeadingLevel } from '../tokens/typography';
+
+/**
+ * THE TWO DIRECTIONS BETWEEN MUI'S THEME AND OURS. Web only.
+ *
+ * `uiThemeFromMui` is how a web component — or a shared style resolver such
+ * as `box-layout.ts` — reads the host's MUI theme in the neutral shape the
+ * native renderer reads natively. `muiThemeOptionsFrom` is the reverse, for
+ * a host that has a `UiTheme` and no MUI theme yet: `UiProvider` on the web is
+ * a MUI `ThemeProvider` fed by it.
+ *
+ * Both are field-by-field on purpose. A spread would carry MUI's extra keys
+ * across and the native side would silently depend on one.
+ */
+
+const slot = (color: PaletteColor): UiPaletteColor => ({
+  main: color.main,
+  light: color.light,
+  dark: color.dark,
+  contrastText: color.contrastText,
+});
+
+function headingSteps(theme: Theme): Record<HeadingLevel, UiHeadingStep> {
+  return Object.fromEntries(
+    HEADING_LEVELS.map((level) => {
+      const metrics = headingMetrics(theme, level);
+      return [
+        level,
+        {
+          fontSize: cssLengthToPx(metrics.fontSize, 16),
+          lineHeight: metrics.lineHeight,
+          letterSpacing: cssTrackingToEm(metrics.letterSpacing),
+          normalWeight: metrics.normalWeight,
+        },
+      ];
+    }),
+  ) as Record<HeadingLevel, UiHeadingStep>;
+}
+
+/** The host's MUI theme in the shape the native renderer reads. */
+export function uiThemeFromMui(theme: Theme): UiTheme {
+  const { palette } = theme;
+  const unit = cssLengthToPx(theme.spacing(1), 8);
+  const md = cssLengthToPx(theme.shape.borderRadius, 4);
+
+  return {
+    mode: palette.mode,
+    palette: {
+      mode: palette.mode,
+      primary: slot(palette.primary),
+      secondary: slot(palette.secondary),
+      success: slot(palette.success),
+      warning: slot(palette.warning),
+      info: slot(palette.info),
+      danger: slot(palette.error),
+      neutral: accentFor(theme, 'neutral'),
+      text: {
+        primary: palette.text.primary,
+        secondary: palette.text.secondary,
+        disabled: palette.text.disabled,
+      },
+      background: { default: palette.background.default, paper: palette.background.paper },
+      divider: palette.divider,
+      action: {
+        active: palette.action.active,
+        hover: palette.action.hover,
+        selected: palette.action.selected,
+        disabled: palette.action.disabled,
+        disabledBackground: palette.action.disabledBackground,
+        focus: palette.action.focus,
+      },
+      grey: {
+        50: palette.grey[50],
+        100: palette.grey[100],
+        200: palette.grey[200],
+        300: palette.grey[300],
+        400: palette.grey[400],
+        500: palette.grey[500],
+        600: palette.grey[600],
+        700: palette.grey[700],
+        800: palette.grey[800],
+        900: palette.grey[900],
+      },
+    },
+    spacing: (units: number) => units * unit,
+    spacingUnit: unit,
+    radius: { sm: md / 2, md, lg: md * 2, xl: md * 4, full: 9999 },
+    typography: {
+      fontFamily: theme.typography.fontFamily ?? WEB_FONT_FAMILY,
+      monospaceFontFamily: WEB_MONOSPACE_FONT_FAMILY,
+      sizes: TYPE_SIZES,
+      weights: FONT_WEIGHTS,
+      heading: headingSteps(theme),
+    },
+    zIndex: {
+      appBar: theme.zIndex.appBar,
+      drawer: theme.zIndex.drawer,
+      modal: theme.zIndex.modal,
+      snackbar: theme.zIndex.snackbar,
+      tooltip: theme.zIndex.tooltip,
+    },
+  };
+}
+
+/** A `UiTheme` as the options MUI's `createTheme` builds the same palette from. */
+export function muiThemeOptionsFrom(ui: UiTheme): ThemeOptions {
+  const { palette } = ui;
+  return {
+    palette: {
+      mode: palette.mode,
+      primary: { ...palette.primary },
+      secondary: { ...palette.secondary },
+      success: { ...palette.success },
+      warning: { ...palette.warning },
+      info: { ...palette.info },
+      error: { ...palette.danger },
+      text: { ...palette.text },
+      background: { ...palette.background },
+      divider: palette.divider,
+      action: { ...palette.action },
+      grey: { ...palette.grey },
+    },
+    shape: { borderRadius: ui.radius.md },
+    spacing: ui.spacingUnit,
+    typography: { fontFamily: ui.typography.fontFamily ?? WEB_FONT_FAMILY },
+    zIndex: { ...ui.zIndex },
+  };
+}

package/src/provider/ui-theme-context.ts

@@ -0,0 +1,13 @@
+import * as React from 'react';
+
+import type { UiTheme } from '../tokens/theme';
+
+/**
+ * The native renderer's theme channel.
+ *
+ * Only the native files read it. On the web the theme every component paints
+ * from is MUI's, reached through emotion's own context, and `use-ui-theme.ts`
+ * derives a `UiTheme` view of it — so there is exactly one source of truth per
+ * renderer rather than two that can disagree.
+ */
+export const UiThemeContext = React.createContext<UiTheme | null>(null);

package/src/provider/use-ui-theme.native.ts

@@ -0,0 +1,9 @@
+import * as React from 'react';
+
+import { UiThemeContext } from './ui-theme-context';
+import { DEFAULT_UI_THEME, type UiTheme } from '../tokens/theme';
+
+/** The theme the nearest `UiProvider` set, or the package default without one. */
+export function useUiTheme(): UiTheme {
+  return React.useContext(UiThemeContext) ?? DEFAULT_UI_THEME;
+}

package/src/provider/use-ui-theme.ts

@@ -0,0 +1,18 @@
+import { useTheme } from '@mui/material/styles/index.js';
+import * as React from 'react';
+
+import { uiThemeFromMui } from './mui-bridge';
+import type { UiTheme } from '../tokens/theme';
+
+/**
+ * The web reading of the theme: MUI's, as a `UiTheme`.
+ *
+ * Derived rather than provided on purpose. A host that already mounts its own
+ * `ThemeProvider` (every origin app does, through `@12-apps/app-shell`) gets
+ * the same numbers a MUI-styled sibling paints with, and nothing has to be
+ * mounted twice or kept in step.
+ */
+export function useUiTheme(): UiTheme {
+  const theme = useTheme();
+  return React.useMemo(() => uiThemeFromMui(theme), [theme]);
+}

package/src/tokens/color.ts

@@ -0,0 +1,163 @@
+/**
+ * COLOUR ARITHMETIC WITH NO RENDERER BEHIND IT.
+ *
+ * Every shade the web components paint comes out of MUI's colour manipulator:
+ * `lighten(main, 0.2)` is a palette's `light`, `darken(main, 0.3)` its `dark`,
+ * `alpha(main, 0.1)` the hover wash on an outline button. A native component
+ * that wants the SAME pixel has to run the SAME arithmetic, and it cannot
+ * import it — `@mui/material/styles` drags emotion and the DOM in behind it.
+ *
+ * So the arithmetic lives here, once, with nothing behind it. It is a faithful
+ * port of `@mui/system/colorManipulator` (MIT), down to the truncation:
+ * `lighten('#6366F1', 0.2)` is `rgb(130, 132, 243)` on both sides because both
+ * TRUNCATE 132.6 rather than round it. A port that rounded would be one pixel
+ * of tint away from the web on every button, forever, and nothing would flag it.
+ *
+ * `color()` space strings are deliberately unsupported: nothing in this package
+ * emits one, and a smaller surface is a smaller thing to keep identical.
+ */
+
+export type ColorFormat = 'rgb' | 'rgba' | 'hsl' | 'hsla';
+
+export interface DecomposedColor {
+  type: ColorFormat;
+  values: number[];
+}
+
+const FORMATS: readonly ColorFormat[] = ['rgb', 'rgba', 'hsl', 'hsla'];
+
+const clamp = (value: number, min = 0, max = 1): number => Math.min(Math.max(min, value), max);
+
+/** `#rgb`, `#rgba`, `#rrggbb` or `#rrggbbaa` to its `rgb()` / `rgba()` string. */
+export function hexToRgb(color: string): string {
+  const hex = color.slice(1);
+  const pair = new RegExp(`.{1,${hex.length >= 6 ? 2 : 1}}`, 'g');
+  let channels: string[] | null = hex.match(pair);
+  if (channels && channels[0]?.length === 1) {
+    channels = channels.map((channel) => channel + channel);
+  }
+  if (!channels) return '';
+
+  const parts = channels.map((channel, index) =>
+    index < 3 ? parseInt(channel, 16) : Math.round((parseInt(channel, 16) / 255) * 1000) / 1000,
+  );
+  return `rgb${channels.length === 4 ? 'a' : ''}(${parts.join(', ')})`;
+}
+
+/** Any supported colour string to its type and numeric channels. */
+export function decomposeColor(color: string): DecomposedColor {
+  if (color.charAt(0) === '#') {
+    return decomposeColor(hexToRgb(color));
+  }
+
+  const marker = color.indexOf('(');
+  const type = color.substring(0, marker) as ColorFormat;
+  if (!FORMATS.includes(type)) {
+    throw new Error(
+      `@12-apps/ui: unsupported colour "${color}". Use #nnn, #nnnnnn, rgb(), rgba(), hsl() or hsla().`,
+    );
+  }
+
+  const values = color
+    .substring(marker + 1, color.length - 1)
+    .split(',')
+    .map((value) => parseFloat(value));
+
+  return { type, values };
+}
+
+/** The inverse of {@link decomposeColor}, with MUI's channel truncation. */
+export function recomposeColor({ type, values }: DecomposedColor): string {
+  const parts: Array<number | string> = type.startsWith('rgb')
+    ? values.map((value, index) => (index < 3 ? Math.trunc(value) : value))
+    : [values[0] ?? 0, `${values[1] ?? 0}%`, `${values[2] ?? 0}%`, ...values.slice(3)];
+
+  return `${type}(${parts.join(', ')})`;
+}
+
+/** An `hsl()` / `hsla()` string to its `rgb()` / `rgba()` equivalent. */
+export function hslToRgb(color: string): string {
+  const { type, values } = decomposeColor(color);
+  const h = values[0] ?? 0;
+  const s = (values[1] ?? 0) / 100;
+  const l = (values[2] ?? 0) / 100;
+  const a = s * Math.min(l, 1 - l);
+  const f = (n: number, k = (n + h / 30) % 12): number =>
+    l - a * Math.max(Math.min(k - 3, 9 - k, 1), -1);
+
+  const rgb = [Math.round(f(0) * 255), Math.round(f(8) * 255), Math.round(f(4) * 255)];
+  if (type === 'hsla') {
+    return recomposeColor({ type: 'rgba', values: [...rgb, values[3] ?? 1] });
+  }
+  return recomposeColor({ type: 'rgb', values: rgb });
+}
+
+/** Relative luminance (WCAG 2.0), to three decimals like MUI. */
+export function getLuminance(color: string): number {
+  const decomposed = decomposeColor(color);
+  const channels = decomposed.type.startsWith('hsl')
+    ? decomposeColor(hslToRgb(color)).values
+    : decomposed.values;
+
+  const [r, g, b] = channels.slice(0, 3).map((value) => {
+    const c = value / 255;
+    return c <= 0.03928 ? c / 12.92 : ((c + 0.055) / 1.055) ** 2.4;
+  });
+
+  return Number((0.2126 * (r ?? 0) + 0.7152 * (g ?? 0) + 0.0722 * (b ?? 0)).toFixed(3));
+}
+
+/** WCAG contrast ratio between two colours, 1 to 21. */
+export function getContrastRatio(foreground: string, background: string): number {
+  const lumA = getLuminance(foreground);
+  const lumB = getLuminance(background);
+  return (Math.max(lumA, lumB) + 0.05) / (Math.min(lumA, lumB) + 0.05);
+}
+
+/** The colour with its alpha channel set to `value` (0 to 1). */
+export function alpha(color: string, value: number): string {
+  const decomposed = decomposeColor(color);
+  const type: ColorFormat = decomposed.type.endsWith('a')
+    ? decomposed.type
+    : (`${decomposed.type}a` as ColorFormat);
+  const values = decomposed.values.slice(0, 3);
+  values[3] = clamp(value);
+  return recomposeColor({ type, values });
+}
+
+/** The colour moved `coefficient` (0 to 1) of the way towards black. */
+export function darken(color: string, coefficient: number): string {
+  const decomposed = decomposeColor(color);
+  const amount = clamp(coefficient);
+  const values = [...decomposed.values];
+
+  if (decomposed.type.startsWith('hsl')) {
+    values[2] = (values[2] ?? 0) * (1 - amount);
+  } else {
+    for (let index = 0; index < 3; index += 1) {
+      values[index] = (values[index] ?? 0) * (1 - amount);
+    }
+  }
+  return recomposeColor({ type: decomposed.type, values });
+}
+
+/** The colour moved `coefficient` (0 to 1) of the way towards white. */
+export function lighten(color: string, coefficient: number): string {
+  const decomposed = decomposeColor(color);
+  const amount = clamp(coefficient);
+  const values = [...decomposed.values];
+
+  if (decomposed.type.startsWith('hsl')) {
+    values[2] = (values[2] ?? 0) + (100 - (values[2] ?? 0)) * amount;
+  } else {
+    for (let index = 0; index < 3; index += 1) {
+      values[index] = (values[index] ?? 0) + (255 - (values[index] ?? 0)) * amount;
+    }
+  }
+  return recomposeColor({ type: decomposed.type, values });
+}
+
+/** Darken a light colour or lighten a dark one, by `coefficient`. */
+export function emphasize(color: string, coefficient = 0.15): string {
+  return getLuminance(color) > 0.5 ? darken(color, coefficient) : lighten(color, coefficient);
+}

package/src/tokens/css-units.ts

@@ -0,0 +1,28 @@
+/**
+ * THE ONE READER OF CSS LENGTHS.
+ *
+ * `HEADING_SCALE` and a host's MUI overrides speak CSS — `'2rem'`, `'-0.02em'`
+ * — and both `tokens/theme.ts` and `provider/mui-bridge.ts` need them as
+ * numbers. Two private parsers drifted (one multiplied `em` by 16, one did
+ * not), so there is one, here, with the rule spelled out: a length becomes px
+ * against a 16px root, a tracking value becomes em.
+ */
+
+const ROOT_PX = 16;
+
+/** `'1.5rem'` → 24, `'1.5em'` → 24, `'20px'` → 20, `20` → 20, unparseable → `fallback`. */
+export function cssLengthToPx(value: string | number | undefined, fallback: number): number {
+  if (typeof value === 'number') return value;
+  if (value === undefined) return fallback;
+  const parsed = Number.parseFloat(value);
+  if (Number.isNaN(parsed)) return fallback;
+  return value.endsWith('rem') || value.endsWith('em') ? parsed * ROOT_PX : parsed;
+}
+
+/** `'-0.02em'` → -0.02, `'0.5px'` → 0.5 / 16, `undefined` → `undefined` ("normal"). */
+export function cssTrackingToEm(value: string | undefined): number | undefined {
+  if (value === undefined) return undefined;
+  const parsed = Number.parseFloat(value);
+  if (Number.isNaN(parsed)) return undefined;
+  return value.endsWith('px') ? parsed / ROOT_PX : parsed;
+}

package/src/tokens/heading-scale.ts

@@ -0,0 +1,87 @@
+
+/**
+ * THE THIRD VOCABULARY: the type scale.
+ *
+ * `scales.ts` opens by saying the package had both halves of every argument at
+ * once until the size and colour vocabularies were declared in one place and
+ * every component derived from them. The type scale was the one that never got
+ * that treatment — it lived as a private `LEVELS` table inside
+ * `Heading.styles.ts`, which is exactly the shape that file exists to refuse.
+ *
+ * Two things follow from it being private, and the second is the expensive one.
+ *
+ * **It could not be re-themed.** `Heading` read `theme.typography.h1.fontFamily`
+ * from the theme and then ignored the theme for every other metric, so a host
+ * calling `createTheme({ typography: { h1: { fontSize: '2rem' } } })` changed
+ * `<Typography variant="h1">` and left `<Heading level="h1">` at 48px. A design
+ * system whose type scale cannot be set by the design is not a system.
+ *
+ * **And the numbers were a landing page's.** `h1` at 3rem and `h2` at 2.5rem are
+ * hero metrics. Dropped into an operations console they put a 48px title
+ * directly above 14px body copy — a 3.4x jump with nothing in between — so
+ * product teams stopped reaching for the component. Measured in one consuming
+ * repo: `<Heading>` appeared four times in the entire codebase while raw
+ * `fontSize` appeared in dozens of files. The component was not disliked, it was
+ * unusable at app scale, and every host paid for that in hand-rolled CSS.
+ *
+ * So the defaults below are an APP scale, and `display` keeps the hero size for
+ * the screens that actually want one. A marketing page asks for `display`; a
+ * console asks for `h1` and gets something it can put on a page.
+ */
+
+/**
+ * A step on the scale.
+ *
+ * `display` is a SIZE, not a rank — see `Heading`, which renders it as `h1` so
+ * the document still gets exactly one level-one heading.
+ */
+export type HeadingLevel = 'h1' | 'h2' | 'h3' | 'h4' | 'h5' | 'h6' | 'display';
+
+/**
+ * The runtime list, declared beside the union for the reason `SIZE_VALUES`
+ * gives: a story's `argTypes.options` spelled by hand drifts from the type, and
+ * the direction it drifts is "documents less than the component accepts".
+ */
+export const HEADING_LEVELS = [
+  'display',
+  'h1',
+  'h2',
+  'h3',
+  'h4',
+  'h5',
+  'h6',
+] as const satisfies readonly HeadingLevel[];
+
+/** Everything one step of the scale decides. */
+export interface HeadingMetrics {
+  fontSize: string;
+  lineHeight: number;
+  letterSpacing?: string;
+  /**
+   * The weight this step carries when the caller asks for `normal`. A heading's
+   * "normal" is not body text's 400 — it is the weight the step is meant to
+   * carry, which gets heavier as the step gets larger.
+   */
+  normalWeight: number;
+}
+
+/**
+ * The house default, in CODE rather than in a component.
+ *
+ * ~1.15x per step from a 1rem `h6`, which keeps six distinguishable ranks inside
+ * the range an application actually uses. The old table ran 1.125rem → 4rem and
+ * spent its top three steps above anything a product screen wants.
+ */
+export const HEADING_SCALE: Record<HeadingLevel, HeadingMetrics> = {
+  // The hero size the old `h1` was really offering, under the name that says so.
+  display: { fontSize: '3rem', lineHeight: 1.05, letterSpacing: '-0.03em', normalWeight: 800 },
+  h1: { fontSize: '2rem', lineHeight: 1.2, letterSpacing: '-0.02em', normalWeight: 700 },
+  h2: { fontSize: '1.75rem', lineHeight: 1.25, letterSpacing: '-0.015em', normalWeight: 700 },
+  h3: { fontSize: '1.5rem', lineHeight: 1.3, letterSpacing: '-0.01em', normalWeight: 600 },
+  h4: { fontSize: '1.25rem', lineHeight: 1.35, letterSpacing: '-0.005em', normalWeight: 600 },
+  h5: { fontSize: '1.125rem', lineHeight: 1.4, normalWeight: 600 },
+  h6: { fontSize: '1rem', lineHeight: 1.5, normalWeight: 600 },
+};
+
+/** A host's overrides: any subset of the steps, any subset of each step's metrics. */
+export type HeadingScaleOverrides = Partial<Record<HeadingLevel, Partial<HeadingMetrics>>>;

package/src/tokens/index.native.ts

@@ -0,0 +1,9 @@
+/**
+ * `@12-apps/ui/tokens` on React Native: the vocabulary, the type scale, the
+ * theme and the colour arithmetic. NOT `accentFor` or `headingMetrics`, which
+ * read a MUI `Theme` and belong to the web build — a native component reads
+ * `useUiTheme()` from `@12-apps/ui/provider` instead.
+ */
+export * from './vocabulary';
+export * from './theme';
+export * from './color';

package/src/tokens/scales.ts

@@ -1,195 +1,20 @@
 import type { Theme } from '@mui/material/styles/index.js';
 
-/**
- * THE TWO VOCABULARIES EVERY COMPONENT SPEAKS.
- *
- * Before this file the package had both halves of every argument at once: 26
- * components sized themselves `xs|sm|md|lg|xl` and four used MUI's
- * `small|medium|large`; 14 coloured themselves `danger|neutral` and 15 used
- * MUI's `error`. Nothing enforced either, because most of these props were
- * spelled out as inline unions and a couple were plain `string`.
- *
- * That is not a tidiness problem. A caller learns the vocabulary from whichever
- * component they used first, and the wrong half is not rejected — it reaches MUI
- * as an unknown value and silently falls back. `Chip` shipped with `color?:
- * string` and MUI's `small|medium`, so `color="danger"` rendered grey and
- * `size="sm"` rendered medium; twelve live call sites were doing exactly that,
- * and every test passed because they all asserted on text.
- *
- * So the vocabulary is declared once, here, and components derive from it.
- *
- * DERIVE, DON'T COPY — AND TAKE THE WHOLE VOCABULARY. Every size prop is
- * `SizeValue` and every colour prop is `ColorValue`, with no `Extract` and no
- * `Exclude`. Handing a component a slice was tried and undone: it is the same
- * fragmentation wearing the canonical type's name, and it leaves a caller having
- * to remember which components accept `xs` and which accept `info`. Where the
- * underlying widget draws fewer steps than five, that is a rendering detail and
- * belongs at the MUI boundary below — not in the prop's type.
- *
- * A component whose size or colour is not this concept at all keeps its own type
- * — `Scrollbar`'s `thin|medium|thick` is a track width, `Sheet`'s `full` is a
- * viewport fraction, `LazyImage`'s size is pixels. Forcing those into the scale
- * would be consistency for its own sake.
- */
-
-/**
- * The house size scale.
- *
- * Abbreviated, because that is what 26 of the 30 components with a real size
- * already used and what every caller has been taught to write.
- *
- * Declared as the array and the type together so the two cannot disagree. The
- * runtime list is what Storybook `argTypes.options` and the demo grids iterate;
- * spelled by hand in each story it drifts, and it had — twelve colour lists
- * omitted `info`, so the control that documents the vocabulary offered a
- * component less than the component accepted.
- */
-/**
- * The type scale is the THIRD vocabulary, and it lives in `./typography.ts`
- * because it is metrics rather than a prop union. Re-exported here so
- * `@12-apps/ui/tokens` stays the one import path for "what words does this
- * package speak" — a second entry point is how a vocabulary gets missed.
- */
-export {
-  HEADING_LEVELS,
-  HEADING_SCALE,
-  headingMetrics,
-  type HeadingLevel,
-  type HeadingMetrics,
-  type HeadingScaleOverrides,
-} from './typography';
-
-export type SizeValue = 'xs' | 'sm' | 'md' | 'lg' | 'xl';
-
-export const SIZE_VALUES = ['xs', 'sm', 'md', 'lg', 'xl'] as const satisfies readonly SizeValue[];
+import type { ColorValue, MuiColor } from './vocabulary';
 
 /**
- * The house colour vocabulary.
- *
- * `danger` and `neutral` are OURS; the rest are MUI's own names already. That
- * sentence started life in `Button.tsx`, which is the component most callers
- * meet first and therefore the one that taught the vocabulary — so it is the one
- * the rest of the package follows.
- *
- * Components that hand these to MUI translate at the boundary (`danger` →
- * `error`, `neutral` → `default` or `inherit` depending on what the underlying
- * component calls its unaccented state). The translation must be a real mapping
- * and never a cast: a cast is precisely what let `danger` through untouched and
- * had MUI fall back to grey.
- *
- * Array and type declared together, for the reason given on {@link SIZE_VALUES}.
+ * `@12-apps/ui/tokens` keeps its whole surface here. The vocabulary itself —
+ * the size and colour unions and their runtime lists — lives in
+ * `./vocabulary`, which imports nothing, so the native renderer can read it
+ * without this file's MUI `Theme` import following it into `dist/types-native`.
  */
-export type ColorValue =
-  | 'primary'
-  | 'secondary'
-  | 'success'
-  | 'warning'
-  | 'info'
-  | 'danger'
-  | 'neutral';
-
-export const COLOR_VALUES = [
-  'primary',
-  'secondary',
-  'success',
-  'warning',
-  'info',
-  'danger',
-  'neutral',
-] as const satisfies readonly ColorValue[];
-
-/* ── Array and union, pinned to each other ────────────────────────────────── */
-
-/**
- * The arrays above are written out rather than derived, because deriving the
- * union from the array (`(typeof COLOR_VALUES)[number]`) costs the alias its
- * name: TypeScript resolves the indexed access eagerly, and every error in the
- * package stops saying `not assignable to type 'ColorValue'` and starts dumping
- * seven string literals. In a package whose entire purpose is teaching this
- * vocabulary, the name in the error message is worth keeping.
- *
- * Writing both means they could disagree, so both directions are checked here.
- * `satisfies` above catches an entry that is not a member. These catch the other
- * half — a member missing from the array — which `satisfies` cannot see and
- * which is the direction that actually bit: twelve story control lists offered
- * six colours for a vocabulary of seven, so `info` was undocumented everywhere.
- *
- * A gap makes the assignment below fail, and the error names the missing member.
- */
-type Missing<Union extends string, Listed extends string> = Exclude<Union, Listed>;
-
-const _allSizesListed: Missing<SizeValue, (typeof SIZE_VALUES)[number]> extends never
-  ? true
-  : never = true;
-
-const _allColorsListed: Missing<ColorValue, (typeof COLOR_VALUES)[number]> extends never
-  ? true
-  : never = true;
-
-void _allSizesListed;
-void _allColorsListed;
+export * from './vocabulary';
+export { headingMetrics } from './typography';
+// The renderer-neutral theme and the colour arithmetic behind it, so a web
+// host can build a `UiTheme` from the same module path a native one does.
+export * from './theme';
+export * from './color';
 
-/* ── The MUI boundary ─────────────────────────────────────────────────────── */
-
-/** What MUI calls a size. Three entries against our five. */
-export type MuiSize = 'small' | 'medium' | 'large';
-
-/**
- * The house scale collapsed onto MUI's three.
- *
- * Five onto three loses information, and it loses it at the ends on purpose:
- * `xs`/`sm` both draw small and `lg`/`xl` both draw large, because MUI has no
- * fourth and fifth step to give them. A component that genuinely needs five
- * distinct sizes styles them itself rather than routing through here — this is
- * for the ones that just forward the prop.
- */
-export const muiSize = (size: SizeValue): MuiSize => {
-  if (size === 'xs' || size === 'sm') return 'small';
-  return size === 'md' ? 'medium' : 'large';
-};
-
-/** What MUI calls a semantic colour on most components. */
-export type MuiColor = 'primary' | 'secondary' | 'success' | 'warning' | 'info' | 'error';
-
-/**
- * The house vocabulary translated for MUI, with the caller naming its neutral.
- *
- * `neutral` is the awkward one: MUI spells the unaccented state `default` on a
- * chip, `inherit` on a button and an icon button, and `grey` in the palette. So
- * the caller passes the word its own MUI component uses rather than this
- * pretending there is one answer.
- *
- * A MAPPING, NEVER A CAST. The cast is what let `danger` reach MUI untouched and
- * silently fall back to grey.
- */
-export function muiColor<N extends string>(color: ColorValue, neutralAs: N): MuiColor | N {
-  if (color === 'danger') return 'error';
-  return color === 'neutral' ? neutralAs : color;
-}
-
-/**
- * The house vocabulary as a `theme.palette` key.
- *
- * Separate from {@link muiColor} because the palette has no `default` and no
- * `inherit` — an unaccented colour there is `grey`.
- */
-export type PaletteKey = MuiColor | 'grey';
-
-export const paletteKey = (color: ColorValue): PaletteKey =>
-  color === 'danger' ? 'error' : color === 'neutral' ? 'grey' : color;
-
-/**
- * A `ColorValue` resolved to a four-stop accent from the theme.
- *
- * `paletteKey` is not enough on its own for anything that reads `.main`: MUI's
- * palette has no neutral `PaletteColor`, and `palette.grey` is a 50–900 ramp
- * with no `main`, `light`, `dark` or `contrastText` on it at all. So `neutral`
- * is resolved from the ramp here, once, instead of every component discovering
- * the same hole and branching around it.
- *
- * Typed against the theme structurally so this file does not drag in MUI's
- * `Theme` and become a dependency of everything that imports a token.
- */
 export interface Accent {
   main: string;
   light: string;