@halftone-ds/tokens 1.2.0 → 1.3.1

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

@@ -45,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, BUTTON, DENSITY, DEPTH, FIELD, fieldWidth, 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, styleColors } 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,16 +77,21 @@ export function generateTheme(input, base, { fix = true } = {}) {
     return hex;
   };
 
-  const anchor = anchorStep(recipe.brand);
-  let colors = semanticColors(anchor);
+  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).
-  colors = { ...colors, ...styleColors(recipe, anchor, colors) };
+  const fixed = colors;
+  colors = { ...colors, ...withRoles(styleColors(recipe, anchor, colors), system?.roles) };
   if (fix) {
-    const styled = fixContrast(colors, lookup);
+    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];
@@ -70,16 +118,13 @@ export function generateTheme(input, base, { fix = true } = {}) {
   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 };
-  // As tokens: widths named apart from the colours (semantic.color.button-edge is a colour).
-  const buttonTokens = { alpha: button.alpha, 'border-width': button.border, 'edge-width': button.edge };
-  const fieldTokens = { alpha: field.alpha, 'border-width': field.border, 'edge-width': field.edge, round: fld.round, 'round-bottom': fld.roundBottom, inset: field.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}');
 
-  return {
+  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,
@@ -89,8 +134,6 @@ export function generateTheme(input, base, { fix = true } = {}) {
       shadow: DEPTH[recipe.depth],
       density: { scale: density.scale, control: { sm: density.sm, md: density.md, lg: density.lg, x: density.x } },
       type,
-      button: buttonTokens,
-      field: fieldTokens,
     },
     density,
     type: typeScale(type),
@@ -102,5 +145,40 @@ export function generateTheme(input, base, { fix = true } = {}) {
     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';
@@ -43,17 +46,22 @@ export type Recipe = {
 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). */
@@ -66,13 +74,80 @@ export type Theme = {
   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;
@@ -111,11 +186,25 @@ 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>>;

package/lib/theme/index.mjs

@@ -5,11 +5,13 @@
  */
 export { generateTheme } from './generate.mjs';
 export { encodeRecipe, decodeRecipe, isThemeCode } from './codec.mjs';
-export { DEFAULT_RECIPE, defaultStyles, defaultTypeset, FLOW, LEADING, OPTIONS, normalizeRecipe, sameRecipe, RECIPE_VERSION, STYLE_KEYS, 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 { styleVars, 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,
@@ -23,5 +25,20 @@ export {
 } from './shadcn.mjs';
 export { CVD_TYPES, cvdWarnings, describeCvdWarnings, DISTINCT_PAIRS, MIN_DELTA_E, pairDistances, simulateCvd } from '../cvd.mjs';
 
-export { AA, AA_NON_TEXT, contrastPairs, contrastReport } from '../contrast.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';

package/lib/theme/presets.mjs

@@ -1,6 +1,6 @@
 /**
  * Starting points by personality. Each is a full recipe, typeset included; the picker starts from one and tweaks.
- * Drafts — review them in the docs studio (/themes) and adjust here. Order is the gallery order.
+ * Drafts — review them in Studio on the docs site (/studio) and adjust here. Order is the gallery order.
  */
 export const PRESETS = [
   {

package/lib/theme/ramp.mjs

@@ -32,38 +32,64 @@ export function curatedRamp(seed) {
   return Object.entries(BRAND_RAMPS).find(([, ramp]) => ramp[600] === hex)?.[0] ?? null;
 }
 
+/** The step nearest a lightness, in a lightness table. */
+const nearestStep = (L, table) => STEPS.reduce((best, s) => (Math.abs(table[s] - L) < Math.abs(table[best] - L) ? s : best), '600');
+
 /** The step a seed sits on: its curated 600, or the generated step nearest its lightness. */
 export function anchorStep(seed) {
   if (curatedRamp(seed)) return '600';
-  const [L] = hexToOklchParts(seed);
-  return STEPS.reduce((best, s) => (Math.abs(LIGHTNESS[s] - L) < Math.abs(LIGHTNESS[best] - L) ? s : best), '600');
+  return nearestStep(hexToOklchParts(seed)[0], LIGHTNESS);
 }
 
-/** { 50: '#…', …, 950: '#…' } for a brand seed. */
-export function brandRamp(seed) {
-  const curated = curatedRamp(seed);
-  if (curated) return { ...BRAND_RAMPS[curated] };
-
+/**
+ * The 11 steps around a seed, in OKLCH, with the seed exactly on `anchor`.
+ *   lightness, chroma   the profile per step (chroma is relative: scaled so the anchor keeps the seed's chroma)
+ *   auto                the anchor nearest the seed's lightness: the seed's offset fades out over three steps
+ *   forced              any other anchor: each side is stretched between the seed and its end of the profile,
+ *                       which keeps the ramp in order however far the seed is from its step
+ */
+function seededRamp(seed, anchor, lightness, chroma) {
   const [Ls, Cs, Hs] = hexToOklchParts(seed);
-  const anchor = anchorStep(seed);
   const ai = STEPS.indexOf(anchor);
-  const dL = Ls - LIGHTNESS[anchor];
-  const chromaScale = Cs / CHROMA[anchor];
+  const auto = nearestStep(Ls, lightness) === anchor;
+  const dL = Ls - lightness[anchor];
+  const chromaScale = chroma[anchor] ? Cs / chroma[anchor] : 0;
+  // Forced: the ends of the ramp, kept a little beyond the seed so a step never repeats it.
+  const top = Math.min(1, Math.max(lightness[STEPS[0]], Ls + 0.01 * ai));
+  const bottom = Math.max(0, Math.min(lightness[STEPS.at(-1)], Ls - 0.01 * (STEPS.length - 1 - ai)));
   const ramp = {};
   STEPS.forEach((s, i) => {
     if (s === anchor) {
       ramp[s] = seed.toLowerCase();
       return;
     }
-    // The seed's offset from the target lightness fades out over three steps either side, which keeps
-    // neighbours in order (|dL| is at most half the gap to the next step).
-    const fade = Math.max(0, 1 - Math.abs(i - ai) / 3);
-    const L = LIGHTNESS[s] + dL * fade;
-    ramp[s] = toGamutHex([L, CHROMA[s] * chromaScale, Hs]);
+    let L;
+    if (auto) {
+      // The seed's offset from the target lightness fades out over three steps either side, which keeps
+      // neighbours in order (|dL| is at most half the gap to the next step).
+      const fade = Math.max(0, 1 - Math.abs(i - ai) / 3);
+      L = lightness[s] + dL * fade;
+    } else {
+      const end = i < ai ? STEPS[0] : STEPS.at(-1);
+      const t = (lightness[s] - lightness[anchor]) / (lightness[end] - lightness[anchor]);
+      L = Ls + t * ((i < ai ? top : bottom) - Ls);
+    }
+    ramp[s] = toGamutHex([L, chroma[s] * chromaScale, Hs]);
   });
   return ramp;
 }
 
+/**
+ * { 50: '#…', …, 950: '#…' } for a seed. `anchor` pins the seed to another step than its nearest one (the
+ * studio's "pinned step"); a curated seed with any other anchor is generated like any seed.
+ */
+export function brandRamp(seed, { anchor } = {}) {
+  const curated = curatedRamp(seed);
+  if (curated && (!anchor || anchor === '600')) return { ...BRAND_RAMPS[curated] };
+  const [L] = hexToOklchParts(seed);
+  return seededRamp(seed, anchor ?? nearestStep(L, LIGHTNESS), LIGHTNESS, CHROMA);
+}
+
 const TINT_CHROMA = { 50: 0.003, 100: 0.005, 200: 0.008, 300: 0.012, 400: 0.02, 500: 0.024, 600: 0.022, 700: 0.02, 800: 0.016, 900: 0.014, 950: 0.012 };
 
 /** The 13-step neutral: 0 (white), the 11 steps, 1000 (black). */
@@ -80,3 +106,17 @@ export function neutralRamp(kind, seed) {
   ramp[1000] = '#000000';
   return ramp;
 }
+
+/** Zinc's lightness per step: a neutral seed's ramp keeps the grey ramps' range (950 is near black). */
+const NEUTRAL_LIGHTNESS = Object.fromEntries(STEPS.map((s) => [s, hexToOklchParts(NEUTRAL_RAMPS.zinc[s])[0]]));
+
+/** The step a neutral seed sits on: the zinc step nearest its lightness. */
+export const neutralAnchorStep = (seed) => nearestStep(hexToOklchParts(seed)[0], NEUTRAL_LIGHTNESS);
+
+/**
+ * The 13-step neutral for a custom seed (any grey, or any colour as a tint): zinc's lightness, the tint's
+ * chroma profile scaled to the seed, the seed exactly on its step.
+ */
+export function neutralSeedRamp(seed, { anchor } = {}) {
+  return { 0: '#ffffff', ...seededRamp(seed, anchor ?? neutralAnchorStep(seed), NEUTRAL_LIGHTNESS, TINT_CHROMA), 1000: '#000000' };
+}