@12-apps/ui 6.17.0 → 6.18.0

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;

package/src/tokens/theme.ts

@@ -0,0 +1,334 @@
+import { darken, getContrastRatio, lighten } from './color';
+import { cssLengthToPx, cssTrackingToEm } from './css-units';
+import { HEADING_SCALE, type HeadingLevel } from './heading-scale';
+
+import type { SizeValue } from './vocabulary';
+
+/**
+ * THE THEME BOTH RENDERERS READ.
+ *
+ * On the web every component styles itself from MUI's `Theme`, which is built
+ * by the host (`@12-apps/app-shell`'s `createAppTheme` in the origin apps) and
+ * reaches a component through emotion's context. React Native has no emotion,
+ * no CSS and no MUI, so a native `Button` needs the same decisions — the
+ * palette, the spacing unit, the radius, the type scale — from somewhere that
+ * does not import a renderer.
+ *
+ * This is that somewhere. `UiTheme` is a plain object of numbers and colour
+ * strings. `createUiTheme` derives it the way MUI's `createPalette` derives its
+ * own: a `light` shade is `lighten(main, 0.2)`, a `dark` shade `darken(main,
+ * 0.3)`, `contrastText` flips at a 3:1 ratio against `rgba(0, 0, 0, 0.87)`.
+ * Same seeds in, same shades out, on both sides — that is the whole basis for
+ * a native button being the web button's colour and not a near miss.
+ *
+ * Numbers are in px on the web and dp on native; both are the CSS-pixel unit
+ * a design is drawn in, so a `fontSize: 16` here IS `1rem` in a web style
+ * and `16` in a `StyleSheet`. The web components keep their `rem` strings and
+ * derive them from these numbers where the two meet (see `px()` below and the
+ * `*.metrics.ts` file beside each ported component).
+ *
+ * `danger` and `neutral` are this package's names (see `./scales`); `danger`
+ * is MUI's `error` and `neutral` is drawn from the grey ramp the way
+ * `Button.styles.ts` has always drawn it.
+ */
+
+export type UiThemeMode = 'light' | 'dark';
+
+export interface UiPaletteColor {
+  main: string;
+  light: string;
+  dark: string;
+  contrastText: string;
+}
+
+export type UiGreyStep = 50 | 100 | 200 | 300 | 400 | 500 | 600 | 700 | 800 | 900;
+
+export interface UiPalette {
+  mode: UiThemeMode;
+  primary: UiPaletteColor;
+  secondary: UiPaletteColor;
+  success: UiPaletteColor;
+  warning: UiPaletteColor;
+  info: UiPaletteColor;
+  danger: UiPaletteColor;
+  neutral: UiPaletteColor;
+  text: { primary: string; secondary: string; disabled: string };
+  background: { default: string; paper: string };
+  divider: string;
+  action: {
+    active: string;
+    hover: string;
+    selected: string;
+    disabled: string;
+    disabledBackground: string;
+    focus: string;
+  };
+  grey: Record<UiGreyStep, string>;
+}
+
+/** One step of the body scale: `fontSize` in px, `lineHeight` as a ratio. */
+export interface UiTypeStep {
+  fontSize: number;
+  lineHeight: number;
+}
+
+export type UiFontWeight = 'light' | 'normal' | 'medium' | 'semibold' | 'bold';
+
+export interface UiHeadingStep extends UiTypeStep {
+  /** In em, so it scales with the step. `undefined` is "normal". */
+  letterSpacing?: number;
+  normalWeight: number;
+}
+
+export interface UiTypography {
+  /**
+   * Native has no fallback stacks: a font is either installed and named, or
+   * `undefined` and the platform's own. The web default is MUI's Roboto stack.
+   */
+  fontFamily: string | undefined;
+  monospaceFontFamily: string | undefined;
+  sizes: Record<SizeValue, UiTypeStep>;
+  weights: Record<UiFontWeight, number>;
+  heading: Record<HeadingLevel, UiHeadingStep>;
+}
+
+export interface UiTheme {
+  mode: UiThemeMode;
+  palette: UiPalette;
+  /** MUI's `theme.spacing(n)`: `n` units of {@link UiTheme.spacingUnit}, in px. */
+  spacing: (units: number) => number;
+  spacingUnit: number;
+  /** `md` is MUI's `shape.borderRadius`; the others are its halves and doubles. */
+  radius: { sm: number; md: number; lg: number; xl: number; full: number };
+  typography: UiTypography;
+  zIndex: { appBar: number; drawer: number; modal: number; snackbar: number; tooltip: number };
+}
+
+/** A seed for one palette slot: a hex `main`, or any subset of the four shades. */
+export type UiPaletteSeed = string | Partial<UiPaletteColor>;
+
+export interface UiThemeOptions {
+  mode?: UiThemeMode;
+  palette?: Partial<{
+    primary: UiPaletteSeed;
+    secondary: UiPaletteSeed;
+    success: UiPaletteSeed;
+    warning: UiPaletteSeed;
+    info: UiPaletteSeed;
+    danger: UiPaletteSeed;
+    background: Partial<UiPalette['background']>;
+  }>;
+  typography?: Partial<Pick<UiTypography, 'fontFamily' | 'monospaceFontFamily'>>;
+  spacingUnit?: number;
+}
+
+const ROOT_FONT_PX = 16;
+
+/** The px value as the rem string the web components write. */
+export const px = (value: number): string => `${value / ROOT_FONT_PX}rem`;
+
+/** MUI's `createPalette` defaults, exactly. */
+const TONAL_OFFSET = 0.2;
+const CONTRAST_THRESHOLD = 3;
+const DARK_TEXT_PRIMARY = 'rgba(0, 0, 0, 0.87)';
+const LIGHT_TEXT_PRIMARY = '#fff';
+
+export const GREY: Record<UiGreyStep, string> = {
+  50: '#fafafa',
+  100: '#f5f5f5',
+  200: '#eeeeee',
+  300: '#e0e0e0',
+  400: '#bdbdbd',
+  500: '#9e9e9e',
+  600: '#757575',
+  700: '#616161',
+  800: '#424242',
+  900: '#212121',
+};
+
+/**
+ * The platform's own seeds. The pair `@12-apps/ui`'s Storybook preview and
+ * `@12-apps/app-shell`'s `DEFAULT_THEME_TOKENS` both carry — keep the three in
+ * step if the design tokens change.
+ */
+export const DEFAULT_BRAND: Record<UiThemeMode, { primary: string; secondary: string }> = {
+  light: { primary: '#6366F1', secondary: '#8B5CF6' },
+  dark: { primary: '#818CF8', secondary: '#A78BFA' },
+};
+
+/** MUI's semantic defaults per mode. These are declared shades, not derived. */
+const SEMANTIC_DEFAULTS: Record<
+  UiThemeMode,
+  Record<'success' | 'warning' | 'info' | 'danger', UiPaletteColor>
+> = {
+  light: {
+    success: { main: '#2e7d32', light: '#4caf50', dark: '#1b5e20', contrastText: '#fff' },
+    warning: { main: '#ed6c02', light: '#ff9800', dark: '#e65100', contrastText: '#fff' },
+    info: { main: '#0288d1', light: '#03a9f4', dark: '#01579b', contrastText: '#fff' },
+    danger: { main: '#d32f2f', light: '#ef5350', dark: '#c62828', contrastText: '#fff' },
+  },
+  dark: {
+    success: { main: '#66bb6a', light: '#81c784', dark: '#388e3c', contrastText: DARK_TEXT_PRIMARY },
+    warning: { main: '#ffa726', light: '#ffb74d', dark: '#f57c00', contrastText: DARK_TEXT_PRIMARY },
+    info: { main: '#29b6f6', light: '#4fc3f7', dark: '#0288d1', contrastText: DARK_TEXT_PRIMARY },
+    danger: { main: '#f44336', light: '#e57373', dark: '#d32f2f', contrastText: '#fff' },
+  },
+};
+
+const MODE_DEFAULTS: Record<
+  UiThemeMode,
+  Pick<UiPalette, 'text' | 'background' | 'divider' | 'action'>
+> = {
+  light: {
+    text: { primary: DARK_TEXT_PRIMARY, secondary: 'rgba(0, 0, 0, 0.6)', disabled: 'rgba(0, 0, 0, 0.38)' },
+    background: { default: '#fff', paper: '#fff' },
+    divider: 'rgba(0, 0, 0, 0.12)',
+    action: {
+      active: 'rgba(0, 0, 0, 0.54)',
+      hover: 'rgba(0, 0, 0, 0.04)',
+      selected: 'rgba(0, 0, 0, 0.08)',
+      disabled: 'rgba(0, 0, 0, 0.26)',
+      disabledBackground: 'rgba(0, 0, 0, 0.12)',
+      focus: 'rgba(0, 0, 0, 0.12)',
+    },
+  },
+  dark: {
+    text: { primary: '#fff', secondary: 'rgba(255, 255, 255, 0.7)', disabled: 'rgba(255, 255, 255, 0.5)' },
+    background: { default: '#121212', paper: '#121212' },
+    divider: 'rgba(255, 255, 255, 0.12)',
+    action: {
+      active: '#fff',
+      hover: 'rgba(255, 255, 255, 0.08)',
+      selected: 'rgba(255, 255, 255, 0.16)',
+      disabled: 'rgba(255, 255, 255, 0.3)',
+      disabledBackground: 'rgba(255, 255, 255, 0.12)',
+      focus: 'rgba(255, 255, 255, 0.12)',
+    },
+  },
+};
+
+/**
+ * MUI's `getContrastText`: white where white reads at 3:1 on the colour, the
+ * light mode's dark ink otherwise. (MUI's source spells the white as the DARK
+ * palette's `text.primary`, which is what made it easy to read backwards.)
+ */
+export function contrastText(background: string): string {
+  return getContrastRatio(background, LIGHT_TEXT_PRIMARY) >= CONTRAST_THRESHOLD
+    ? LIGHT_TEXT_PRIMARY
+    : DARK_TEXT_PRIMARY;
+}
+
+/**
+ * MUI's `augmentColor` for a custom colour: derive whatever shade the seed
+ * left out. `light` is one tonal offset up, `dark` one and a half down.
+ */
+export function augmentColor(seed: UiPaletteSeed): UiPaletteColor {
+  const partial = typeof seed === 'string' ? { main: seed } : seed;
+  const main = partial.main ?? partial.light ?? partial.dark;
+  if (!main) {
+    throw new Error('@12-apps/ui: a palette seed needs at least a `main` colour.');
+  }
+  return {
+    main,
+    light: partial.light ?? lighten(main, TONAL_OFFSET),
+    dark: partial.dark ?? darken(main, TONAL_OFFSET * 1.5),
+    contrastText: partial.contrastText ?? contrastText(main),
+  };
+}
+
+const semantic = (
+  mode: UiThemeMode,
+  key: 'success' | 'warning' | 'info' | 'danger',
+  seed: UiPaletteSeed | undefined,
+): UiPaletteColor => (seed === undefined ? SEMANTIC_DEFAULTS[mode][key] : augmentColor(seed));
+
+/** `neutral` as `accentFor` in `./scales` has always drawn it: three greys and white. */
+export const NEUTRAL: UiPaletteColor = {
+  main: GREY[600],
+  light: GREY[400],
+  dark: GREY[800],
+  contrastText: '#fff',
+};
+
+/** The body scale `Text` renders, in px. `Text.tsx`'s rem map is this, divided by 16. */
+export const TYPE_SIZES: Record<SizeValue, UiTypeStep> = {
+  xs: { fontSize: 12, lineHeight: 1.2 },
+  sm: { fontSize: 14, lineHeight: 1.3 },
+  md: { fontSize: 16, lineHeight: 1.5 },
+  lg: { fontSize: 18, lineHeight: 1.4 },
+  xl: { fontSize: 20, lineHeight: 1.3 },
+};
+
+export const FONT_WEIGHTS: Record<UiFontWeight, number> = {
+  light: 300,
+  normal: 400,
+  medium: 500,
+  semibold: 600,
+  bold: 700,
+};
+
+// `HEADING_SCALE` speaks CSS, this theme speaks numbers; `./css-units` is the
+// one place that conversion is written.
+const HEADING_STEPS = Object.fromEntries(
+  Object.entries(HEADING_SCALE).map(([level, metrics]) => [
+    level,
+    {
+      fontSize: cssLengthToPx(metrics.fontSize, ROOT_FONT_PX),
+      lineHeight: metrics.lineHeight,
+      letterSpacing: cssTrackingToEm(metrics.letterSpacing),
+      normalWeight: metrics.normalWeight,
+    },
+  ]),
+) as Record<HeadingLevel, UiHeadingStep>;
+
+export const WEB_FONT_FAMILY = '"Roboto", "Helvetica", "Arial", sans-serif';
+export const WEB_MONOSPACE_FONT_FAMILY = 'Monaco, Menlo, "Ubuntu Mono", "Courier New", monospace';
+
+/**
+ * Build the theme. Every field is derived here so a host that changes one
+ * seed gets every dependent shade recomputed, on both renderers, identically.
+ */
+export function createUiTheme(options: UiThemeOptions = {}): UiTheme {
+  const mode = options.mode ?? 'light';
+  const seeds = options.palette ?? {};
+  const brand = DEFAULT_BRAND[mode];
+  const defaults = MODE_DEFAULTS[mode];
+  const spacingUnit = options.spacingUnit ?? 8;
+
+  const palette: UiPalette = {
+    mode,
+    primary: augmentColor(seeds.primary ?? brand.primary),
+    secondary: augmentColor(seeds.secondary ?? brand.secondary),
+    success: semantic(mode, 'success', seeds.success),
+    warning: semantic(mode, 'warning', seeds.warning),
+    info: semantic(mode, 'info', seeds.info),
+    danger: semantic(mode, 'danger', seeds.danger),
+    neutral: NEUTRAL,
+    text: defaults.text,
+    background: { ...defaults.background, ...seeds.background },
+    divider: defaults.divider,
+    action: defaults.action,
+    grey: GREY,
+  };
+
+  return {
+    mode,
+    palette,
+    spacing: (units: number) => units * spacingUnit,
+    spacingUnit,
+    radius: { sm: 2, md: 4, lg: 8, xl: 16, full: 9999 },
+    typography: {
+      fontFamily: options.typography?.fontFamily,
+      monospaceFontFamily: options.typography?.monospaceFontFamily,
+      sizes: TYPE_SIZES,
+      weights: FONT_WEIGHTS,
+      heading: HEADING_STEPS,
+    },
+    zIndex: { appBar: 1100, drawer: 1200, modal: 1300, snackbar: 1400, tooltip: 1500 },
+  };
+}
+
+/** The palette slot a house colour name resolves to. */
+export type UiPaletteKey = 'primary' | 'secondary' | 'success' | 'warning' | 'info' | 'danger' | 'neutral';
+
+export const DEFAULT_UI_THEME: UiTheme = createUiTheme();

package/src/tokens/typography.ts

@@ -1,91 +1,14 @@
 import type { Theme } from '@mui/material/styles/index.js';
 
-/**
- * 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';
+import { HEADING_SCALE, type HeadingLevel, type HeadingMetrics, type HeadingScaleOverrides } from './heading-scale';
 
 /**
- * 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".
+ * The MUI half of the type scale: the theme augmentation and the reader that
+ * merges a host's overrides. The scale itself is in `./heading-scale`, which
+ * imports nothing, so `src/tokens/theme.ts` and the native renderer read it
+ * without dragging MUI's `Theme` into `dist/types-native`.
  */
-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>>>;
+export * from './heading-scale';
 
 /**
  * The theme channel, under our OWN key rather than MUI's `typography.h1…h6`.