@halftone-ds/tokens 1.1.0 → 1.3.0

package/lib/theme/fix.mjs

@@ -10,6 +10,14 @@
  *
  * It checks the STRICT set (tones on muted/accent too). A moved token becomes a literal hex for that
  * mode, and every move is reported as { token, mode, from, to } so the picker can show it.
+ *
+ * A system's hand-made choices are never moved; each is a { light: Set, dark: Set } of token names:
+ *   locked   a role mapped by hand: the fixer changes nothing about it (no label flip, no nudge)
+ *   pinned   a role on an edited step: as a label it may still flip between the neutrals, but its colour is
+ *            never nudged off the step
+ * The fixer still flips a generated label on a fixed fill, and moves generated ink off a fixed surface. It never
+ * moves a fill to suit a hand-picked label (that would move every surface the fill is). A pairing it leaves
+ * failing is reported in `warnings` as { mode, label, fg, bg, ratio, threshold, locked }.
  */
 import { contrast, hexToOklchParts } from '../color.mjs';
 import { contrastPairs } from '../contrast.mjs';
@@ -37,9 +45,10 @@ function nudge(hex, dir, ok) {
  * semantic: { name: { light, dark } } of references or hex; lookup: (value) → hex.
  * Returns { semantic, adjustments } — a new map, the input is not touched.
  */
-export function fixContrast(semantic, lookup) {
+export function fixContrast(semantic, lookup, { locked, pinned } = {}) {
   const out = Object.fromEntries(Object.entries(semantic).map(([k, v]) => [k, { ...v }]));
   const adjustments = [];
+  const warnings = [];
 
   for (const mode of ['light', 'dark']) {
     const original = Object.fromEntries(Object.entries(out).map(([k, v]) => [k, lookup(v[mode])]));
@@ -48,39 +57,83 @@ export function fixContrast(semantic, lookup) {
     const set = (name, value) => {
       out[name][mode] = value;
     };
+    const lockedHere = locked?.[mode] ?? new Set();
+    const pinnedHere = pinned?.[mode] ?? new Set();
+    const isLocked = (name) => lockedHere.has(name);
+    // Its colour stays: locked, or on an edited step.
+    const isFixed = (name) => lockedHere.has(name) || pinnedHere.has(name);
+    // Pairings left as they are: only a locked colour could fix them.
+    const accepted = new Set();
+    const accept = (f) => accepted.add(f.label);
+    // Without locks, a pairing nothing fixes is a bug (it throws, as it always has); with them, a warning.
+    const cannot = (f) => {
+      if (!lockedHere.size && !pinnedHere.size) throw new Error(`fixContrast: cannot fix ${f.label} (${mode})`);
+      accept(f);
+    };
 
-    for (let pass = 0; pass < MAX_PASSES; pass++) {
+    for (let pass = 0; pass < MAX_PASSES; ) {
       const hex = hexNow();
-      const [f] = failing(contrastPairs(hex, mode, { strict: true }));
+      const [f] = failing(contrastPairs(hex, mode, { strict: true })).filter((p) => !accepted.has(p.label));
       if (!f) break;
 
       if (f.fgName === `${f.bgName}-foreground`) {
         // 1. A label on its own fill.
         const [best] = FOREGROUND_CHOICES.map((ref) => ({ ref, ratio: contrast(lookup(ref), hex[f.bgName]) })).sort((a, b) => b.ratio - a.ratio);
-        if (best.ratio >= f.threshold && out[f.fgName][mode] !== best.ref) {
+        if (!isLocked(f.fgName) && best.ratio >= f.threshold && out[f.fgName][mode] !== best.ref) {
           set(f.fgName, best.ref);
+          pass++;
+          continue;
+        }
+        if (isFixed(f.bgName) || isLocked(f.fgName)) {
+          accept(f);
           continue;
         }
         const label = lookup(best.ref);
         // A light label (it reads on black) needs a darker fill; a dark label a lighter one.
         const dir = contrast(label, '#000000') > contrast(label, '#ffffff') ? -1 : 1;
         const moved = nudge(hex[f.bgName], dir, (c) => contrast(label, c) >= f.threshold);
-        if (!moved) throw new Error(`fixContrast: cannot fix ${f.label} (${mode})`);
+        if (!moved) {
+          cannot(f);
+          continue;
+        }
         set(f.fgName, best.ref);
         moveFill(f.bgName, moved);
+        pass++;
         continue;
       }
 
       // 2 and 3: move the ink until every pairing it takes part in as ink passes.
       const ink = f.fgName;
-      const asInk = (candidate) => failing(contrastPairs({ ...hex, [ink]: candidate }, mode, { strict: true, fg: ink })).length === 0;
+      if (isFixed(ink)) {
+        accept(f);
+        continue;
+      }
+      const asInk = (candidate) =>
+        failing(contrastPairs({ ...hex, [ink]: candidate }, mode, { strict: true, fg: ink })).filter((p) => !accepted.has(p.label)).length === 0;
       const moved = nudge(hex[ink], away, asInk);
-      if (!moved) throw new Error(`fixContrast: cannot fix ${f.label} (${mode})`);
+      if (!moved) {
+        cannot(f);
+        continue;
+      }
       moveFill(ink, moved);
+      pass++;
     }
 
-    const left = failing(contrastPairs(hexNow(), mode, { strict: true }));
+    const all = failing(contrastPairs(hexNow(), mode, { strict: true }));
+    const left = all.filter((p) => !accepted.has(p.label));
     if (left.length) throw new Error(`fixContrast: ${left[0].label} still fails in ${mode} after ${MAX_PASSES} passes`);
+    // The strict set can name a pairing twice (muted-foreground on muted): warn once.
+    for (const p of all.filter((p, i) => all.findIndex((q) => q.label === p.label) === i)) {
+      warnings.push({
+        mode,
+        label: p.label,
+        fg: p.fgName,
+        bg: p.bgName,
+        ratio: Number(p.ratio.toFixed(2)),
+        threshold: p.threshold,
+        locked: [p.fgName, p.bgName].filter(isFixed),
+      });
+    }
 
     for (const [name, before] of Object.entries(original)) {
       const after = lookup(out[name][mode]);
@@ -91,9 +144,9 @@ export function fixContrast(semantic, lookup) {
       const was = lookup(out[name][mode]);
       set(name, hex);
       if (name === 'primary') {
-        for (const linked of BRAND_LINKED) if (lookup(out[linked][mode]) === was) set(linked, hex);
+        for (const linked of BRAND_LINKED) if (!isFixed(linked) && lookup(out[linked][mode]) === was) set(linked, hex);
       }
     }
   }
-  return { semantic: out, adjustments };
+  return { semantic: out, adjustments, warnings };
 }

package/lib/theme/fonts.mjs

@@ -13,6 +13,8 @@
  *   system      the platform's own font for its role: nothing to load
  *   weights     the static weights we load (400–700); a class asking for another snaps to the nearest
  *   expoPrefix  the export prefix of the @expo-google-fonts package (Inter_600SemiBold → 'Inter')
+ *   fontsource  'static' when only @fontsource/<id> exists; every other family has @fontsource-variable/<id>
+ *               (for a shadcn project: lib/theme/shadcn.mjs shadcnFont)
  */
 export const FONTS = [
   { id: 'system', family: 'System', category: 'sans', weights: [400, 500, 600, 700, 800], system: true },
@@ -35,7 +37,7 @@ export const FONTS = [
   { id: 'system-mono', family: 'Menlo', category: 'mono', weights: [400, 500, 600, 700], system: true },
   { id: 'jetbrains-mono', family: 'JetBrains Mono', category: 'mono', weights: [400, 500, 600, 700], expoPrefix: 'JetBrainsMono' },
   { id: 'geist-mono', family: 'Geist Mono', category: 'mono', weights: [400, 500, 600, 700], expoPrefix: 'GeistMono' },
-  { id: 'ibm-plex-mono', family: 'IBM Plex Mono', category: 'mono', weights: [400, 500, 600, 700], expoPrefix: 'IBMPlexMono' },
+  { id: 'ibm-plex-mono', family: 'IBM Plex Mono', category: 'mono', weights: [400, 500, 600, 700], expoPrefix: 'IBMPlexMono', fontsource: 'static' },
   { id: 'roboto-mono', family: 'Roboto Mono', category: 'mono', weights: [400, 500, 600, 700], expoPrefix: 'RobotoMono' },
   { id: 'fira-code', family: 'Fira Code', category: 'mono', weights: [400, 500, 600, 700], expoPrefix: 'FiraCode' },
   { id: 'source-code-pro', family: 'Source Code Pro', category: 'mono', weights: [400, 500, 600, 700], expoPrefix: 'SourceCodePro' },
@@ -43,6 +45,19 @@ export const FONTS = [
 
 export const fontById = (id) => FONTS.find((f) => f.id === id);
 
+/**
+ * A font for any Google Fonts family (a system's fonts can be any): its curated entry, or one made from the
+ * name the way @expo-google-fonts and next/font name it ('Inter Tight' → inter-tight, InterTight_600SemiBold,
+ * Inter_Tight), loading 400–700. A family without one of those weights fails to load; pick weights in the Studio.
+ */
+export function fontByFamily(family) {
+  const name = String(family).trim();
+  const curated = FONTS.find((f) => f.family.toLowerCase() === name.toLowerCase());
+  if (curated) return curated;
+  const id = name.toLowerCase().replace(/[^a-z0-9]+/g, '-').replace(/^-+|-+$/g, '');
+  return { id, family: name, category: 'sans', weights: [400, 500, 600, 700], expoPrefix: name.replace(/[^A-Za-z0-9]/g, '') };
+}
+
 /** The nearest loaded weight of a font to the one a class asks for. */
 export function nearestWeight(font, weight) {
   return font.weights.reduce((best, w) => (Math.abs(w - weight) < Math.abs(best - weight) ? w : best), font.weights[0]);

package/lib/theme/generate.mjs

@@ -3,29 +3,72 @@
  * the browser for the live picker, the CLI runs it to commit a theme into tokens.json.
  *
  *   generateTheme(recipe, base)  base = the app's tokens.json (status ramps, radius steps come from it)
- *     → { recipe, code, primitives, semantic, resolved, radius, type, adjustments }
+ *     → { recipe, code, primitives, semantic, resolved, radius, type, adjustments, warnings }
  *
- * Status colours (success, warning, danger, info) are not themed in v1; they come from `base`.
+ * A recipe doesn't theme the status colours (success, warning, danger, info): they come from `base`. A system
+ * document does (lib/system/generate.mjs), through `colors`, the hook below that only generateSystem uses:
+ *   colors.ramps     { brand?, neutral?, danger?, … }: finished ramps in place of the recipe's (or base's)
+ *   colors.anchor    the brand seed's step; colors.anchors the status seeds' steps
+ *   colors.roles     { name: { light?, dark? } } references or hex chosen by hand: never moved by the fixer
+ *   colors.edited    { ramp: [steps] } edited by hand: a role on one keeps its colour (a warning if it fails)
+ * Without it, the theme is exactly the recipe's.
  */
 import { fixContrast } from './fix.mjs';
 import { encodeRecipe } from './codec.mjs';
 import { fontById } from './fonts.mjs';
-import { BORDER, DENSITY, DEPTH, FLOW, LEADING, normalizeRecipe, RADIUS, STROKE, typeScale } from './recipe.mjs';
+import { componentLayer } from './components.mjs';
+import { BORDER, BUTTON, DENSITY, DEPTH, FIELD, fieldWidth, FLOW, LEADING, normalizeRecipe, RADIUS, resolveTextStyles, STROKE, textEdits, typeScale } from './recipe.mjs';
 import { anchorStep, brandRamp, neutralRamp } from './ramp.mjs';
 import { resolvedMap } from './refs.mjs';
-import { semanticColors } from './semantic.mjs';
+import { BRAND_LINKED, semanticColors, styleColors } from './semantic.mjs';
 
 
 const ramp = (values) => Object.fromEntries(Object.entries(values).map(([step, $value]) => [step, { $type: 'color', $value }]));
+const STATUS = ['danger', 'success', 'warning', 'info'];
+const modes = () => ({ light: new Set(), dark: new Set() });
+
+/** Role overrides on top of a semantic map; the tokens that share primary's step follow a primary override. */
+function withRoles(colors, roles, linked = false) {
+  if (!roles) return colors;
+  const out = Object.fromEntries(Object.entries(colors).map(([k, v]) => [k, { ...v }]));
+  for (const mode of ['light', 'dark']) {
+    const primary = roles.primary?.[mode];
+    if (linked && primary !== undefined) for (const name of BRAND_LINKED) if (!roles[name]?.[mode] && out[name]?.[mode] === colors.primary[mode]) out[name][mode] = primary;
+    for (const [name, value] of Object.entries(roles)) if (name in out && value[mode] !== undefined) out[name][mode] = value[mode];
+  }
+  return out;
+}
+
+/**
+ * Which colours the fixer leaves alone, per mode: `locked` = mapped by hand (and what follows a hand-mapped
+ * primary), `pinned` = on an edited step. `from` locks a style colour that is a locked base colour (a solid
+ * button is the primary).
+ */
+function locks(colors, { roles = {}, edited = {} }, from) {
+  const locked = modes();
+  const pinned = modes();
+  const editedRef = new Set(Object.entries(edited).flatMap(([name, steps]) => steps.map((step) => `{primitive.color.${name}.${step}}`)));
+  for (const mode of ['light', 'dark']) {
+    for (const [name, value] of Object.entries(colors)) {
+      if (roles[name]?.[mode] !== undefined) locked[mode].add(name);
+      else if (roles.primary?.[mode] !== undefined && BRAND_LINKED.includes(name) && value[mode] === roles.primary[mode]) locked[mode].add(name);
+      else if (from && !(name in from.colors) && Object.entries(from.colors).some(([base, v]) => from.locked[mode].has(base) && v[mode] === value[mode])) locked[mode].add(name);
+      else if (editedRef.has(value[mode])) pinned[mode].add(name);
+    }
+  }
+  return { locked, pinned };
+}
 
 /** The theme for a recipe, on top of `base` (a tokens.json object). `fix: false` skips the contrast fixer. */
-export function generateTheme(input, base, { fix = true } = {}) {
+export function generateTheme(input, base, { fix = true, colors: system } = {}) {
   const recipe = normalizeRecipe(input);
-  const brand = brandRamp(recipe.brand);
-  const neutral = neutralRamp(recipe.neutral, recipe.brand);
+  const brand = system?.ramps?.brand ?? brandRamp(recipe.brand);
+  const neutral = system?.ramps?.neutral ?? neutralRamp(recipe.neutral, recipe.brand);
+  const status = Object.fromEntries(STATUS.filter((name) => system?.ramps?.[name]).map((name) => [name, system.ramps[name]]));
+  const statusTokens = Object.fromEntries(Object.entries(status).map(([name, values]) => [name, ramp(values)]));
 
   // Primitive lookup: the base primitives with this theme's ramps swapped in.
-  const primitive = { ...base.primitive, color: { ...base.primitive.color, brand: ramp(brand), neutral: ramp(neutral) } };
+  const primitive = { ...base.primitive, color: { ...base.primitive.color, brand: ramp(brand), neutral: ramp(neutral), ...statusTokens } };
   const prim = resolvedMap({ primitive }, 'light');
   const lookup = (value) => {
     if (typeof value !== 'string' || !value.startsWith('{')) return value;
@@ -34,9 +77,22 @@ export function generateTheme(input, base, { fix = true } = {}) {
     return hex;
   };
 
-  let colors = semanticColors(anchorStep(recipe.brand));
+  const anchor = system?.anchor ?? anchorStep(recipe.brand);
+  let colors = withRoles(semanticColors(anchor, system?.anchors), system?.roles, true);
+  const baseLocks = locks(colors, system ?? {});
   let adjustments = [];
-  if (fix) ({ semantic: colors, adjustments } = fixContrast(colors, lookup));
+  let warnings = [];
+  if (fix) ({ semantic: colors, adjustments, warnings } = fixContrast(colors, lookup, baseLocks));
+  // The styles' colours build on the fixed ones, then get their own check (a soft button's ink, a field's line).
+  const fixed = colors;
+  colors = { ...colors, ...withRoles(styleColors(recipe, anchor, colors), system?.roles) };
+  if (fix) {
+    const styled = fixContrast(colors, lookup, locks(colors, system ?? {}, { colors: fixed, locked: baseLocks.locked }));
+    colors = styled.semantic;
+    adjustments = [...adjustments, ...styled.adjustments];
+    // The second pass sees every pairing again: keep each warning once.
+    warnings = styled.warnings;
+  }
 
   const radiusRef = RADIUS[recipe.radius];
   const radiusValue = typeof radiusRef === 'string' ? `{primitive.radius.${radiusRef}}` : radiusRef;
@@ -57,10 +113,18 @@ export function generateTheme(input, base, { fix = true } = {}) {
     measure: Number(recipe.measure),
   };
 
-  return {
+  const borderWidth = BORDER[recipe.border];
+  const btn = BUTTON[recipe.button];
+  const fld = FIELD[recipe.field];
+  const button = { alpha: btn.alpha, border: btn.border, edge: btn.edge };
+  const field = { alpha: fld.alpha, border: fieldWidth(fld.border, borderWidth), edge: fieldWidth(fld.edge, borderWidth), inset: fld.inset };
+  // rounded-md is the radius × md / lg (resolve.mjs); a field's radius is that or square.
+  const md = lookup('{primitive.radius.md}') / lookup('{primitive.radius.lg}');
+
+  const theme = {
     recipe,
     code: encodeRecipe(recipe),
-    primitives: { brand, neutral },
+    primitives: { brand, neutral, ...status },
     fonts: { heading: font(recipe.font.heading), body: font(recipe.font.body), mono: font(recipe.font.mono) },
     semantic: {
       color: colors,
@@ -76,8 +140,45 @@ export function generateTheme(input, base, { fix = true } = {}) {
     resolved,
     radius,
     radiusControl: lookup(controlRadius),
-    borderWidth: BORDER[recipe.border],
+    borderWidth,
+    button,
+    field: { ...field, radius: lookup(radiusValue) * md * fld.round, radiusBottom: lookup(radiusValue) * md * fld.roundBottom },
     stroke: STROKE[recipe.stroke],
     adjustments,
+    warnings,
   };
+  return withComponents(theme, base);
+}
+
+/**
+ * The theme with its component layer (lib/theme/components.mjs): semantic.component (the tokens) and `components`
+ * (resolved). Built from the theme's own corners, density, border, styles, text styles and colours, so
+ * generateSystem calls it again once a system's edits are in, with the system's `components` as `overrides`.
+ */
+export function withComponents(theme, base, overrides = {}) {
+  const primitive = { ...base.primitive, color: { ...base.primitive.color, ...Object.fromEntries(Object.entries(theme.primitives).map(([name, values]) => [name, ramp(values)])) } };
+  const prim = resolvedMap({ primitive }, 'light');
+  const lg = prim['primitive.radius.lg'];
+  const edited = theme.semantic.radius;
+  const fld = FIELD[theme.recipe.field];
+  const { tokens, shape } = componentLayer({
+    styles: { button: theme.recipe.button, field: theme.recipe.field },
+    controls: theme.recipe.controls,
+    corner: (name) => (typeof edited[name] === 'number' ? edited[name] : (theme.radius * prim[`primitive.radius.${name}`]) / lg),
+    density: theme.density,
+    borderWidth: theme.borderWidth,
+    button: theme.button,
+    field: { ...theme.field, round: fld.round, roundBottom: fld.roundBottom },
+    textStyles: resolveTextStyles(theme.type, textEdits(theme.semantic.type)),
+    type: theme.type,
+    hex: (ref, mode) => {
+      const name = /^\{semantic\.color\.(.+)\}$/.exec(ref)?.[1];
+      if (name) return theme.resolved[mode][name];
+      const value = prim[ref.slice(1, -1)];
+      if (value === undefined) throw new Error(`generateTheme: ${ref} is not in the base tokens`);
+      return value;
+    },
+    overrides,
+  });
+  return { ...theme, semantic: { ...theme.semantic, component: tokens }, components: shape };
 }

package/lib/theme/index.d.mts

@@ -1,4 +1,7 @@
 /** Types for @halftone-ds/tokens/theme (index.mjs). */
+import type { HalftoneSystem } from '../system/index.mjs';
+// Systems (lib/system): also @halftone-ds/tokens/system.
+export * from '../system/index.mjs';
 
 export type Neutral = 'zinc' | 'neutral' | 'slate' | 'stone' | 'gray' | 'brand';
 export type Radius = 'none' | 'sm' | 'md' | 'lg' | 'xl' | '2xl';
@@ -11,7 +14,13 @@ export type Size = '16' | '14' | '15' | '18';
 export type Leading = 'normal' | 'tight' | 'relaxed';
 export type Flow = 'normal' | 'tight' | 'loose';
 export type Measure = '70' | '60' | '80' | '90';
+export type ButtonStyle = 'solid' | 'soft' | 'outline' | 'raised';
+export type FieldStyle = 'outline' | 'filled' | 'underline';
 export type Mode = 'light' | 'dark';
+export type CvdType = 'protanopia' | 'deuteranopia' | 'tritanopia';
+/** A pair of tones as one vision sees them: `fg` and `bg` are the simulated hex of `a` and `b`. */
+export type PairDistance = { a: string; b: string; vision: CvdType | 'none'; fg: string; bg: string; deltaE: number };
+export type CvdWarning = PairDistance & { mode: Mode };
 
 export type Recipe = {
   v: number;
@@ -28,22 +37,31 @@ export type Recipe = {
   leading: Leading;
   flow: Flow;
   measure: Measure;
+  /** The primary button's style. */
+  button: ButtonStyle;
+  /** Text fields' style (inputs, text areas, select triggers). */
+  field: FieldStyle;
   preset?: string;
 };
 export type RecipeInput = Partial<Omit<Recipe, 'font'>> & { font?: Partial<Recipe['font']> };
 
 export type Adjustment = { token: string; mode: Mode; from: string; to: string };
+/** A pairing the contrast fixer left failing because a colour in it was chosen by hand (a system's role or step). */
+export type ThemeWarning = { mode: Mode; label: string; fg: string; bg: string; ratio: number; threshold: number; locked: string[] };
 
 export type Theme = {
   recipe: Recipe;
   code: string;
-  primitives: { brand: Record<string, string>; neutral: Record<string, string> };
+  /** brand and neutral, plus a status ramp a system seeded or edited. */
+  primitives: { brand: Record<string, string>; neutral: Record<string, string> } & Partial<Record<'danger' | 'success' | 'warning' | 'info', Record<string, string>>>;
   semantic: Record<string, unknown>;
   /** Semantic colours as hex per mode, kebab-case names (`primary-foreground`). */
   resolved: Record<Mode, Record<string, string>>;
   /** Base radius in px. */
   radius: number;
   adjustments: Adjustment[];
+  /** Always empty for a recipe; a system's hand-picked colours that fail contrast. */
+  warnings: ThemeWarning[];
   /** Font families by role ('' = system; mono 'Menlo' = the platform monospace). */
   fonts: { heading: string; body: string; mono: string };
   /** The typeset: size (px), scale (size / 16), leading, leadingFactor (leading / 1.75), flow (em), measure (ch). */
@@ -52,13 +70,84 @@ export type Theme = {
   borderWidth: number;
   stroke: number;
   density: { sm: number; md: number; lg: number; x: number; scale: number };
+  /** The button style's numbers: fill opacity, border and bottom edge (px). */
+  button: { alpha: number; border: number; edge: number };
+  /** The field style's numbers: fill opacity per mode, border and bottom edge (px), radii (px), inset (0 or 1). */
+  field: { alpha: Record<Mode, number>; border: number; edge: number; inset: number; radius: number; radiusBottom: number };
+  /** The component layer (Button, Chip, Badge, Input), resolved: what both kits draw. */
+  components: ComponentShapes;
   [key: string]: unknown;
 };
 
+export type ComponentName = 'button' | 'chip' | 'badge' | 'input';
+export type Corner = 'sm' | 'md' | 'lg' | 'xl' | '2xl' | 'full';
+export type ComponentSlot = 'fill' | 'label' | 'border' | 'pressed';
+/** A component colour as drawn: its role (null for a style's ramp step), hex and opacity per mode. */
+export type ComponentColor = {
+  role: string | null;
+  light: string;
+  dark: string;
+  alpha: Record<Mode, number>;
+  ref?: Record<Mode, string>;
+  /** Set in the system (not the default). */
+  edited?: boolean;
+  /** Pressed derived from the fill, a ring from the border. */
+  derived?: boolean;
+};
+export type ComponentVariant = Partial<Record<ComponentSlot | 'ring', ComponentColor>> & { borderWidth?: number; edgeWidth?: number };
+export type ComponentShape = {
+  style?: string;
+  /** The Foundations corner it follows, or null when set in px. */
+  corner?: Corner | null;
+  /** px (9999 = a pill); Input: the top corners. */
+  radius: number;
+  radiusBottom?: number;
+  /** Heights (px) by size. */
+  h: Partial<Record<'sm' | 'md' | 'lg', number>>;
+  /** Horizontal padding (px) by size. */
+  x: Partial<Record<'sm' | 'md' | 'lg', number>>;
+  /** Font role, size and line height (px), tracking (em); `style` the text style it follows. */
+  text: { style?: string; font: 'heading' | 'body' | 'mono'; size: number; leading: number; tracking: number };
+  variants: Record<string, ComponentVariant>;
+};
+export type ComponentShapes = Record<ComponentName, ComponentShape>;
+export type ComponentDefinition = {
+  prefix: string;
+  label: string;
+  styles: string[];
+  sizes: Array<'sm' | 'md' | 'lg' | 'x'>;
+  variants: Record<string, ComponentSlot[]>;
+  text: string;
+};
+export const COMPONENT_NAMES: ComponentName[];
+export const COMPONENTS: Record<ComponentName, ComponentDefinition>;
+export const CORNERS: Corner[];
+export const SLOTS: ComponentSlot[];
+export const SLOT_VAR: Record<ComponentSlot | 'ring', string>;
+/** The touch-target floor (px) the mobile kit applies on phones. */
+export const TOUCH_TARGET: number;
+export function defaultCorner(name: ComponentName, options?: { controls?: string; style?: string }): Corner;
+export function defaultStyle(name: ComponentName, recipe?: Partial<Recipe>): string;
+export function fittedLeading(style: string): number;
+export function componentVars(shape: ComponentShapes, format: 'hsl' | 'oklch', convert: (hex: string) => string, font?: (role: string) => string): Record<Mode, Record<string, string>>;
+export function componentVarNames(): string[];
+export function componentColors(shape: ComponentShapes, css: (key: string, alpha: boolean) => string): Record<string, string>;
+export function componentPairs(
+  shape: ComponentShapes,
+  mode: Mode,
+  background: string,
+  blend: (hex: string, base: string, alpha: number) => string
+): Array<{ component: ComponentName; variant: string; label: string; fg: string; bg: string; fgRole: string | null; bgRole: string | null }>;
+/** Every variant's label on its fill, both modes: rows like contrastReport's, with the component and variant. */
+export function componentContrast(shape: ComponentShapes, background: Record<Mode, string>): Array<ContrastPair & { component: ComponentName; variant: string }>;
+
 export type TypeScale = { size: number; scale: number; leading: number; leadingFactor: number; flow: number; measure: number };
 export type Font = { id: string; family: string; category: 'sans' | 'serif' | 'display' | 'mono'; weights: number[]; expoPrefix?: string; hidden?: boolean; system?: boolean };
 export type Preset = { id: string; name: string; description: string; recipe: RecipeInput };
-export type ThemeStatus = { applied: false } | { applied: true; code: string; recipe: Recipe; drift: string[] };
+export type ThemeStatus =
+  | { applied: false }
+  /** code is null for a system with overrides; system is set when a system document was applied. */
+  | { applied: true; code: string | null; recipe: Recipe; system?: HalftoneSystem; drift: string[] };
 export type TokensJson = Record<string, unknown> & { primitive: Record<string, unknown>; semantic: Record<string, unknown> };
 
 export const RECIPE_VERSION: number;
@@ -75,14 +164,20 @@ export const OPTIONS: {
   leading: Leading[];
   flow: Flow[];
   measure: Measure[];
+  button: ButtonStyle[];
+  field: FieldStyle[];
 };
 export const TYPESET_KEYS: ['size', 'leading', 'flow', 'measure'];
+export const STYLE_KEYS: ['button', 'field'];
 export const LEADING: Record<Leading, number>;
 export const FLOW: Record<Flow, number>;
 export const FONTS: Font[];
 export const PRESETS: Preset[];
 export const BRAND_RAMPS: Record<string, Record<string, string>>;
 export const THEME_EXTENSION: string;
+export const CVD_TYPES: CvdType[];
+export const DISTINCT_PAIRS: [string, string][];
+export const MIN_DELTA_E: number;
 
 export function normalizeRecipe(input?: RecipeInput): Recipe;
 export function sameRecipe(a: RecipeInput, b: RecipeInput): boolean;
@@ -91,12 +186,81 @@ export function encodeRecipe(recipe: RecipeInput): string;
 export function decodeRecipe(code: string): Recipe;
 export function isThemeCode(value: unknown): boolean;
 export function fontById(id: string): Font | undefined;
+/** The curated font for a family, or one made from any Google Fonts family name (400–700). */
+export function fontByFamily(family: string): Font;
 export function googleFontsHref(ids: string[]): string | null;
 export function presetById(id: string): Preset | undefined;
 export function defaultTypeset(recipe: Recipe): boolean;
+export function defaultStyles(recipe: Recipe): boolean;
 export function typeVars(type: TypeScale): Record<string, string>;
+export type TextStyleName = 'h1' | 'h2' | 'h3' | 'h4' | 'lead' | 'p' | 'large' | 'small' | 'muted' | 'code' | 'blockquote';
+export type TextFontRole = 'heading' | 'body' | 'mono';
+/** A text style as drawn: size and lineHeight px, leading × size, tracking em; edited: a system changed it. */
+export type DrawnTextStyle = { font: TextFontRole; weight: number; size: number; leading: number; tracking: number; lineHeight: number; edited: boolean };
+export const TEXT_STYLES: TextStyleName[];
+export const TEXT_DEFAULTS: Record<TextStyleName, { font: TextFontRole; weight: number; size: number; leading: number | 'prose'; tracking: number }>;
+/** A system's edited styles from a semantic.type group (a theme's, or a token file's DTCG one). */
+export function textEdits(group?: Record<string, unknown>): Partial<Record<TextStyleName, Partial<Omit<DrawnTextStyle, 'lineHeight' | 'edited'>>>>;
+export function resolveTextStyles(type: TypeScale, edits?: ReturnType<typeof textEdits>): Record<TextStyleName, DrawnTextStyle>;
+export function themeTextStyles(theme: Theme): Record<TextStyleName, DrawnTextStyle>;
+/** --type-<style>-{size,leading,weight,tracking} (+ -font on the web) in a kit's units. */
+export function textStyleVars(styles: Record<string, DrawnTextStyle>, format: 'hsl' | 'oklch', font?: (role: TextFontRole) => string): Record<string, string>;
+export function styleVars(styles: Pick<Theme, 'button' | 'field'>, format: 'hsl' | 'oklch'): Record<Mode, Record<string, string>>;
 export function themeVars(theme: Theme, format: 'hsl' | 'oklch'): Record<Mode, Record<string, string>>;
 export function themeHex(theme: Theme): Record<Mode, Record<string, string>>;
 export function themeCss(theme: Theme, options?: { format?: 'hsl' | 'oklch'; light?: string; dark?: string }): string;
 export function applyRecipe(tokens: TokensJson, recipe: RecipeInput): { tokens: TokensJson; theme: Theme };
 export function themeStatus(tokens: TokensJson): ThemeStatus;
+
+/** One pairing the contrast gate checks: `fg` on `bg` in one mode, its WCAG ratio and the threshold it must clear. */
+export type ContrastPair = { mode: Mode; label: string; fgName: string; bgName: string; fg: string; bg: string; threshold: number; ratio: number };
+/** A ContrastPair for a table: `pass` against its WCAG threshold, and `apca`, the advisory APCA Lc (signed). */
+export type ContrastRow = ContrastPair & { pass: boolean; apca: number };
+
+/** WCAG 2.1 AA for text (4.5) and for icons and other non-text (3). */
+export const AA: number;
+export const AA_NON_TEXT: number;
+export function contrastPairs(hex: Record<string, string>, mode: Mode, options?: { strict?: boolean; fg?: string }): ContrastPair[];
+/** Every pairing the build checks (strict by default), light then dark. `hex` is a theme's `resolved`. */
+export function contrastReport(hex: Partial<Record<Mode, Record<string, string>>>, options?: { strict?: boolean }): ContrastRow[];
+/** APCA Lc of `text` on `background` (APCA-W3 0.0.98G-4g). Advisory: it never fails the build. */
+export function apcaContrast(text: string, background: string): number;
+export function simulateCvd(hex: string, type: CvdType | 'none' | null | undefined): string;
+export function pairDistances(hex: Record<string, string>, type: CvdType | 'none', pairs?: [string, string][]): PairDistance[];
+export function cvdWarnings(resolved: Partial<Record<Mode, Record<string, string>>>, options?: { pairs?: [string, string][]; threshold?: number }): CvdWarning[];
+export function describeCvdWarnings(warnings: CvdWarning[]): string[];
+
+/** A decoded shadcn/ui preset code (ui.shadcn.com/create). */
+export type ShadcnPreset = {
+  version: 'a' | 'b';
+  style: string;
+  baseColor: string;
+  theme: string;
+  chartColor: string;
+  iconLibrary: string;
+  font: string;
+  fontHeading: string;
+  radius: string;
+  menuAccent: string;
+  menuColor: string;
+};
+/** A shadcn registry item (registry:theme or registry:font), as JSON. */
+export type ShadcnRegistryItem = {
+  $schema: string;
+  name: string;
+  title?: string;
+  description?: string;
+  type: 'registry:theme' | 'registry:font';
+  registryDependencies?: string[];
+  cssVars?: { theme?: Record<string, string>; light?: Record<string, string>; dark?: Record<string, string> };
+  font?: { family: string; provider: 'google'; import: string; variable: string; subsets?: string[]; weight?: string[]; dependency?: string };
+};
+export function isShadcnPresetCode(s: unknown): s is string;
+export function decodeShadcnPreset(code: string): ShadcnPreset | null;
+export function encodeShadcnPreset(preset: Partial<ShadcnPreset>): string;
+/** The nearest Halftone recipe for a shadcn preset, and a note for each value it approximated or dropped. */
+export function recipeFromShadcn(preset: ShadcnPreset): { recipe: Recipe; notes: string[] };
+export const SHADCN_FONTS_URL: string;
+export function shadcnTheme(theme: Theme, options?: { name?: string; title?: string; description?: string; fontsUrl?: string }): ShadcnRegistryItem;
+export function shadcnFont(id: string, role?: 'body' | 'heading' | 'mono'): ShadcnRegistryItem | null;
+export function shadcnFontPath(id: string, role: 'body' | 'heading' | 'mono'): string;

package/lib/theme/index.mjs

@@ -5,10 +5,40 @@
  */
 export { generateTheme } from './generate.mjs';
 export { encodeRecipe, decodeRecipe, isThemeCode } from './codec.mjs';
-export { DEFAULT_RECIPE, defaultTypeset, FLOW, LEADING, OPTIONS, normalizeRecipe, sameRecipe, RECIPE_VERSION, TYPESET_KEYS } from './recipe.mjs';
-export { FONTS, fontById, googleFontsHref } from './fonts.mjs';
+export { DEFAULT_RECIPE, defaultStyles, defaultTypeset, FLOW, LEADING, OPTIONS, normalizeRecipe, sameRecipe, RECIPE_VERSION, resolveTextStyles, STYLE_KEYS, TEXT_DEFAULTS, TEXT_STYLES, textEdits, TYPESET_KEYS } from './recipe.mjs';
+export { FONTS, fontByFamily, fontById, googleFontsHref } from './fonts.mjs';
 export { PRESETS, presetById } from './presets.mjs';
-export { themeVars, themeCss, themeHex, typeVars } from './vars.mjs';
+export { styleVars, textStyleVars, themeTextStyles, themeVars, themeCss, themeHex, typeVars } from './vars.mjs';
 export { applyRecipe, themeStatus, THEME_EXTENSION } from './apply.mjs';
+// Systems (lib/system): also @halftone-ds/tokens/system.
+export * from '../system/index.mjs';
 export { BRAND_RAMPS } from './palettes.mjs';
+export {
+  decodeShadcnPreset,
+  encodeShadcnPreset,
+  isShadcnPresetCode,
+  recipeFromShadcn,
+  SHADCN_FONTS_URL,
+  shadcnFont,
+  shadcnFontPath,
+  shadcnTheme,
+} from './shadcn.mjs';
+export { CVD_TYPES, cvdWarnings, describeCvdWarnings, DISTINCT_PAIRS, MIN_DELTA_E, pairDistances, simulateCvd } from '../cvd.mjs';
 
+export { AA, AA_NON_TEXT, componentContrast, contrastPairs, contrastReport } from '../contrast.mjs';
+export {
+  COMPONENT_NAMES,
+  COMPONENTS,
+  componentColors,
+  componentPairs,
+  componentVarNames,
+  componentVars,
+  CORNERS,
+  defaultCorner,
+  defaultStyle,
+  fittedLeading,
+  SLOT_VAR,
+  SLOTS,
+  TOUCH_TARGET,
+} from './components.mjs';
+export { apcaContrast } from '../apca.mjs';