@halftone-ds/tokens 1.0.0 → 1.2.0

package/lib/theme/codec.mjs

@@ -3,23 +3,26 @@
  * read out, paste into a terminal or a URL.
  *
  *   ht1-  12 characters, 60 bits: a theme with the default typeset (every code made before the typeset)
- *   ht2-  16 characters, 80 bits: any theme
+ *   ht2-  16 characters, 80 bits: a theme with the default styles (solid buttons, outline fields)
+ *   ht3-  18 characters, 90 bits: any theme
  *
- *   bits  field                                   ht1   ht2
- *          recipe version (RECIPE_VERSION)          4     4
- *          brand hex                               24    24
- *          neutral, radius, controls            3+3+1 3+3+1   (option indexes, recipe.mjs)
- *          heading, body (, mono)                 5+5 6+6+6   (indexes into FONTS, fonts.mjs)
- *          stroke, depth, density, border     2+2+2+2 2+2+2+2
- *          size, leading, flow, measure             –  3+3+3+3
- *          checksum (payload mod 127)               7     7   a typo is caught instead of making another theme
+ *   bits  field                                   ht1   ht2   ht3
+ *          recipe version (RECIPE_VERSION)          4     4     4
+ *          brand hex                               24    24    24
+ *          neutral, radius, controls            3+3+1 3+3+1 3+3+1   (option indexes, recipe.mjs)
+ *          heading, body (, mono)                 5+5 6+6+6 6+6+6   (indexes into FONTS, fonts.mjs)
+ *          stroke, depth, density, border     2+2+2+2 2+2+2+2 2+2+2+2
+ *          size, leading, flow, measure             –  3+3+3+3 3+3+3+3
+ *          button, field                            –     –   2+2
+ *          reserved (zero: room for more styles)    –     –     6
+ *          checksum (payload mod 127)               7     7     7   a typo is caught instead of making another theme
  *
- * encodeRecipe writes ht1 whenever it can, so a theme that doesn't touch the typeset keeps the code it
- * always had (and older halftone-tokens can read it). The preset name is not in the code: a code is the theme,
+ * encodeRecipe writes the shortest code that holds the theme (ht1, then ht2, then ht3), so a theme keeps the
+ * code it always had and older halftone-tokens can read it. The preset name is not in the code: a code is the theme,
  * whichever preset it started from.
  */
 import { FONTS } from './fonts.mjs';
-import { defaultTypeset, normalizeRecipe, OPTIONS, RECIPE_VERSION } from './recipe.mjs';
+import { defaultStyles, defaultTypeset, normalizeRecipe, OPTIONS, RECIPE_VERSION } from './recipe.mjs';
 
 const ALPHABET = '0123456789ABCDEFGHJKMNPQRSTVWXYZ';
 const LAYOUT = [
@@ -39,18 +42,24 @@ const TYPESET = [
   ['flow', 3],
   ['measure', 3],
 ];
+const STYLES = [
+  ['button', 2],
+  ['field', 2],
+];
+const RESERVED = 6;
 /** Per format: prefix, characters, font width, whether the typeset is in it. */
 const FORMATS = {
-  ht1: { prefix: 'ht1-', chars: 12, font: 5, typeset: false },
-  ht2: { prefix: 'ht2-', chars: 16, font: 6, typeset: true },
+  ht1: { prefix: 'ht1-', chars: 12, font: 5, typeset: false, styles: false },
+  ht2: { prefix: 'ht2-', chars: 16, font: 6, typeset: true, styles: false },
+  ht3: { prefix: 'ht3-', chars: 18, font: 6, typeset: true, styles: true },
 };
 
 const fontIndex = (id) => FONTS.findIndex((f) => f.id === id);
 
 export function encodeRecipe(input) {
   const r = normalizeRecipe(input);
-  const ht1 = defaultTypeset(r) && fontIndex(r.font.heading) < 32 && fontIndex(r.font.body) < 32;
-  const format = ht1 ? FORMATS.ht1 : FORMATS.ht2;
+  const ht1 = defaultStyles(r) && defaultTypeset(r) && fontIndex(r.font.heading) < 32 && fontIndex(r.font.body) < 32;
+  const format = ht1 ? FORMATS.ht1 : defaultStyles(r) ? FORMATS.ht2 : FORMATS.ht3;
   let bits = BigInt(r.v);
   const push = (value, width) => {
     if (value < 0 || value >= 2 ** width) throw new Error(`encodeRecipe: ${value} does not fit in ${width} bits`);
@@ -63,6 +72,10 @@ export function encodeRecipe(input) {
   if (format.typeset) push(fontIndex(r.font.mono), format.font);
   for (const [key, width] of TAIL) push(OPTIONS[key].indexOf(r[key]), width);
   if (format.typeset) for (const [key, width] of TYPESET) push(OPTIONS[key].indexOf(r[key]), width);
+  if (format.styles) {
+    for (const [key, width] of STYLES) push(OPTIONS[key].indexOf(r[key]), width);
+    push(0, RESERVED);
+  }
   bits = (bits << 7n) | (bits % 127n);
 
   let out = '';
@@ -76,13 +89,13 @@ export function encodeRecipe(input) {
 /** Code → recipe. Throws on a malformed code, a bad checksum or an unknown version. */
 export function decodeRecipe(code) {
   const clean = String(code).trim().toUpperCase();
-  const format = /^HT2/.test(clean) ? FORMATS.ht2 : FORMATS.ht1;
-  const raw = clean.replace(/^HT[12]-?/, '').replace(/[IL]/g, '1').replace(/O/g, '0').replace(/-/g, '');
-  if (!/^HT[12]/.test(clean) && /^HT\d/.test(clean)) {
+  const format = /^HT3/.test(clean) ? FORMATS.ht3 : /^HT2/.test(clean) ? FORMATS.ht2 : FORMATS.ht1;
+  const raw = clean.replace(/^HT[123]-?/, '').replace(/[IL]/g, '1').replace(/O/g, '0').replace(/-/g, '');
+  if (!/^HT[123]/.test(clean) && /^HT\d/.test(clean)) {
     throw new Error(`"${code}" is a newer theme code than this halftone-tokens reads. Update @halftone-ds/tokens.`);
   }
   if (!new RegExp(`^[0-9A-HJKMNP-TV-Z]{${format.chars}}$`).test(raw)) {
-    throw new Error(`"${code}" is not a theme code (expected ht1- and 12 characters, or ht2- and 16)`);
+    throw new Error(`"${code}" is not a theme code (expected ht1- and 12 characters, ht2- and 16, or ht3- and 18)`);
   }
   let bits = 0n;
   for (const ch of raw) bits = (bits << 5n) | BigInt(ALPHABET.indexOf(ch));
@@ -106,7 +119,9 @@ export function decodeRecipe(code) {
     return f.id;
   };
   const fields = (list) => Object.fromEntries([...list].reverse().map(([key, width]) => [key, opt(key, width)]));
-  // Read back to front.
+  // Read back to front. Reserved bits set means a newer halftone-tokens wrote styles this one doesn't know.
+  if (format.styles && pull(RESERVED) !== 0) throw new Error(`"${code}" is a newer theme code than this halftone-tokens reads. Update @halftone-ds/tokens.`);
+  const styles = format.styles ? fields(STYLES) : {};
   const typeset = format.typeset ? fields(TYPESET) : {};
   const tail = fields(TAIL);
   const mono = format.typeset ? font(format.font) : undefined;
@@ -116,7 +131,7 @@ export function decodeRecipe(code) {
   const brand = '#' + pull(24).toString(16).padStart(6, '0');
   const v = Number(bits);
   if (v !== RECIPE_VERSION) throw new Error(`"${code}" is a version ${v} theme; this halftone-tokens reads version ${RECIPE_VERSION}. Update @halftone-ds/tokens.`);
-  return normalizeRecipe({ v, brand, ...head, font: { heading, body, ...(mono ? { mono } : {}) }, ...tail, ...typeset });
+  return normalizeRecipe({ v, brand, ...head, font: { heading, body, ...(mono ? { mono } : {}) }, ...tail, ...typeset, ...styles });
 }
 
-export const isThemeCode = (value) => /^(ht1-?[0-9a-z]{12}|ht2-?[0-9a-z]{16})$/i.test(String(value).trim());
+export const isThemeCode = (value) => /^(ht1-?[0-9a-z]{12}|ht2-?[0-9a-z]{16}|ht3-?[0-9a-z]{18})$/i.test(String(value).trim());

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' },

package/lib/theme/generate.mjs

@@ -10,10 +10,10 @@
 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 { BORDER, BUTTON, DENSITY, DEPTH, FIELD, fieldWidth, FLOW, LEADING, normalizeRecipe, RADIUS, STROKE, typeScale } from './recipe.mjs';
 import { anchorStep, brandRamp, neutralRamp } from './ramp.mjs';
 import { resolvedMap } from './refs.mjs';
-import { semanticColors } from './semantic.mjs';
+import { semanticColors, styleColors } from './semantic.mjs';
 
 
 const ramp = (values) => Object.fromEntries(Object.entries(values).map(([step, $value]) => [step, { $type: 'color', $value }]));
@@ -34,9 +34,17 @@ export function generateTheme(input, base, { fix = true } = {}) {
     return hex;
   };
 
-  let colors = semanticColors(anchorStep(recipe.brand));
+  const anchor = anchorStep(recipe.brand);
+  let colors = semanticColors(anchor);
   let adjustments = [];
   if (fix) ({ semantic: colors, adjustments } = fixContrast(colors, lookup));
+  // 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) };
+  if (fix) {
+    const styled = fixContrast(colors, lookup);
+    colors = styled.semantic;
+    adjustments = [...adjustments, ...styled.adjustments];
+  }
 
   const radiusRef = RADIUS[recipe.radius];
   const radiusValue = typeof radiusRef === 'string' ? `{primitive.radius.${radiusRef}}` : radiusRef;
@@ -57,6 +65,17 @@ export function generateTheme(input, base, { fix = true } = {}) {
     measure: Number(recipe.measure),
   };
 
+  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 };
+  // 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 {
     recipe,
     code: encodeRecipe(recipe),
@@ -70,13 +89,17 @@ 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),
     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,
   };

package/lib/theme/index.d.mts

@@ -11,7 +11,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,6 +34,10 @@ 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']> };
@@ -52,6 +62,10 @@ 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 };
   [key: string]: unknown;
 };
 
@@ -75,14 +89,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;
@@ -94,9 +114,64 @@ export function fontById(id: string): Font | undefined;
 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 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,23 @@
  */
 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 { 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 { PRESETS, presetById } from './presets.mjs';
-export { themeVars, themeCss, themeHex, typeVars } from './vars.mjs';
+export { styleVars, themeVars, themeCss, themeHex, typeVars } from './vars.mjs';
 export { applyRecipe, themeStatus, THEME_EXTENSION } from './apply.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, contrastPairs, contrastReport } from '../contrast.mjs';
+export { apcaContrast } from '../apca.mjs';

package/lib/theme/presets.mjs

@@ -12,20 +12,20 @@ export const PRESETS = [
   {
     id: 'editorial',
     name: 'Editorial',
-    description: 'Serif headlines, rust ink, hairlines and almost no rounding.',
-    recipe: { brand: '#9a3412', neutral: 'stone', radius: 'sm', controls: 'match', font: { heading: 'fraunces', body: 'inter', mono: 'ibm-plex-mono' }, stroke: 'thin', depth: 'flat', density: 'comfortable', border: 'hairline', size: '18', leading: 'relaxed', flow: 'normal', measure: '70' },
+    description: 'Serif headlines, rust ink, hairlines, underlined fields and almost no rounding.',
+    recipe: { brand: '#9a3412', neutral: 'stone', radius: 'sm', controls: 'match', font: { heading: 'fraunces', body: 'inter', mono: 'ibm-plex-mono' }, stroke: 'thin', depth: 'flat', density: 'comfortable', border: 'hairline', size: '18', leading: 'relaxed', flow: 'normal', measure: '70', button: 'solid', field: 'underline' },
   },
   {
     id: 'soft',
     name: 'Soft',
-    description: 'Lavender, generous radius, brand-tinted greys and room to breathe.',
-    recipe: { brand: '#8b5cf6', neutral: 'brand', radius: '2xl', controls: 'pill', font: { heading: 'plus-jakarta-sans', body: 'plus-jakarta-sans', mono: 'geist-mono' }, stroke: 'regular', depth: 'soft', density: 'spacious', border: 'hairline', size: '16', leading: 'relaxed', flow: 'loose', measure: '60' },
+    description: 'Lavender, generous radius, tinted buttons, filled fields and room to breathe.',
+    recipe: { brand: '#8b5cf6', neutral: 'brand', radius: '2xl', controls: 'pill', font: { heading: 'plus-jakarta-sans', body: 'plus-jakarta-sans', mono: 'geist-mono' }, stroke: 'regular', depth: 'soft', density: 'spacious', border: 'hairline', size: '16', leading: 'relaxed', flow: 'loose', measure: '60', button: 'soft', field: 'filled' },
   },
   {
     id: 'playful',
     name: 'Playful',
-    description: 'Pink, chunky icons, round display type and lifted cards.',
-    recipe: { brand: '#db2777', neutral: 'neutral', radius: 'xl', controls: 'pill', font: { heading: 'bricolage-grotesque', body: 'nunito', mono: 'fira-code' }, stroke: 'bold', depth: 'raised', density: 'comfortable', border: 'regular', size: '16', leading: 'relaxed', flow: 'normal', measure: '60' },
+    description: 'Pink, chunky icons, round display type, lifted cards and raised buttons.',
+    recipe: { brand: '#db2777', neutral: 'neutral', radius: 'xl', controls: 'pill', font: { heading: 'bricolage-grotesque', body: 'nunito', mono: 'fira-code' }, stroke: 'bold', depth: 'raised', density: 'comfortable', border: 'regular', size: '16', leading: 'relaxed', flow: 'normal', measure: '60', button: 'raised', field: 'outline' },
   },
   {
     id: 'brutalist',
@@ -51,6 +51,18 @@ export const PRESETS = [
     description: 'Teal on warm greys, a book serif for headings, thin lines, no shadows.',
     recipe: { brand: '#0d9488', neutral: 'stone', radius: 'xl', controls: 'match', font: { heading: 'lora', body: 'manrope', mono: 'source-code-pro' }, stroke: 'thin', depth: 'flat', density: 'spacious', border: 'hairline', size: '16', leading: 'relaxed', flow: 'loose', measure: '70' },
   },
+  {
+    id: 'tactile',
+    name: 'Tactile',
+    description: 'Warm orange, raised buttons you want to press, filled fields, rounded and friendly.',
+    recipe: { brand: '#ea580c', neutral: 'stone', radius: 'xl', controls: 'match', font: { heading: 'nunito', body: 'nunito', mono: 'fira-code' }, stroke: 'bold', depth: 'raised', density: 'comfortable', border: 'regular', size: '16', leading: 'normal', flow: 'normal', measure: '70', button: 'raised', field: 'filled' },
+  },
+  {
+    id: 'studio',
+    name: 'Studio',
+    description: 'Indigo on slate, tinted buttons, underlined fields, hairlines: quiet and precise.',
+    recipe: { brand: '#4f46e5', neutral: 'slate', radius: 'md', controls: 'match', font: { heading: 'geist', body: 'geist', mono: 'geist-mono' }, stroke: 'regular', depth: 'flat', density: 'comfortable', border: 'hairline', size: '15', leading: 'normal', flow: 'normal', measure: '70', button: 'soft', field: 'underline' },
+  },
 ];
 
 export const presetById = (id) => PRESETS.find((p) => p.id === id);

package/lib/theme/recipe.mjs

@@ -6,6 +6,8 @@
  *
  * The typeset (font.mono, size, leading, flow, measure) came later. A recipe without it gets the defaults,
  * which are what the kits always had, and a theme with the default typeset still encodes as a ht1 code.
+ * So did the styles (button, field): their defaults are the kits' original look, and a theme that keeps them
+ * encodes as ht1 or ht2 as before.
  */
 import { FONTS } from './fonts.mjs';
 
@@ -34,16 +36,46 @@ export const OPTIONS = {
   flow: ['normal', 'tight', 'loose'],
   /** Typeset: the longest line of long-form text (Prose), in characters. */
   measure: ['70', '60', '80', '90'],
+  /** Style: the primary button. Solid fill, a brand tint, a brand outline, or solid with a darker bottom edge. */
+  button: ['solid', 'soft', 'outline', 'raised'],
+  /** Style: text fields (inputs, text areas, select triggers). A box, a tinted field with a line, or a line. */
+  field: ['outline', 'filled', 'underline'],
 };
 
 /** The recipe keys that make up the typeset, besides font.mono. */
 export const TYPESET_KEYS = ['size', 'leading', 'flow', 'measure'];
+/** The recipe keys that are component styles (ht3 codes). */
+export const STYLE_KEYS = ['button', 'field'];
 
 /** Base radius per option: a primitive radius step (a reference) or 0. */
 export const RADIUS = { none: 0, sm: 'sm', md: 'md', lg: 'lg', xl: 'xl', '2xl': '2xl' };
 export const STROKE = { thin: 1.5, regular: 2, bold: 2.5 };
 /** px; hairline renders as one device pixel on a 2x screen. */
 export const BORDER = { hairline: 0.5, regular: 1, heavy: 2 };
+/**
+ * Button styles as numbers (px), on top of the colours in semantic.mjs (styleColors). `alpha` is the fill's
+ * opacity: an outline button has no fill. `border` is every side, `edge` the bottom (raised: a thicker,
+ * darker bottom edge).
+ */
+export const BUTTON = {
+  solid: { alpha: 1, border: 0, edge: 0 },
+  soft: { alpha: 1, border: 0, edge: 0 },
+  outline: { alpha: 0, border: 2, edge: 2 },
+  raised: { alpha: 1, border: 0, edge: 3 },
+};
+/**
+ * Field styles. `alpha` per mode (outline: transparent, with a faint tint in dark, as the kits always had).
+ * `border` / `edge`: 'border' = the theme's border width, 'line' = at least 1px (it's the field's only edge).
+ * `round` / `roundBottom`: 1 = the md radius, 0 = square. `inset`: 1 = the usual inner padding, 0 = flush.
+ */
+export const FIELD = {
+  outline: { alpha: { light: 0, dark: 0.3 }, border: 'border', edge: 'border', round: 1, roundBottom: 1, inset: 1 },
+  filled: { alpha: { light: 1, dark: 1 }, border: 0, edge: 'line', round: 1, roundBottom: 0, inset: 1 },
+  underline: { alpha: { light: 0, dark: 0 }, border: 0, edge: 'line', round: 0, roundBottom: 0, inset: 0 },
+};
+/** A field width in px for a border width. */
+export const fieldWidth = (value, borderWidth) => (value === 'border' ? borderWidth : value === 'line' ? Math.max(1, borderWidth) : value);
+
 /** Line height of running text (× size). 1.75 = leading-7 at 16px, what the kits' paragraphs always had. */
 export const LEADING = { tight: 1.6, normal: 1.75, relaxed: 1.9 };
 /** Space between blocks of long-form text, in em. */
@@ -136,6 +168,8 @@ export const DEFAULT_RECIPE = Object.freeze({
   leading: 'normal',
   flow: 'normal',
   measure: '70',
+  button: 'solid',
+  field: 'outline',
 });
 
 const HEX = /^#[0-9a-f]{6}$/;
@@ -143,6 +177,9 @@ const HEX = /^#[0-9a-f]{6}$/;
 /** Does the recipe use the default typeset (what every ht1 code means)? */
 export const defaultTypeset = (r) => r.font.mono === DEFAULT_RECIPE.font.mono && TYPESET_KEYS.every((k) => r[k] === DEFAULT_RECIPE[k]);
 
+/** Does the recipe keep the default styles (solid buttons, outline fields: every ht1 and ht2 code)? */
+export const defaultStyles = (r) => STYLE_KEYS.every((k) => r[k] === DEFAULT_RECIPE[k]);
+
 /** Fill in defaults, normalise, and throw on anything invalid. Returns a new, plain recipe. */
 export function normalizeRecipe(input = {}) {
   const r = { ...DEFAULT_RECIPE, ...input, font: { ...DEFAULT_RECIPE.font, ...input.font } };
@@ -175,6 +212,8 @@ export function normalizeRecipe(input = {}) {
     leading: r.leading,
     flow: r.flow,
     measure: r.measure,
+    button: r.button,
+    field: r.field,
   };
   if (input.preset) out.preset = String(input.preset);
   return out;

package/lib/theme/semantic.mjs

@@ -3,6 +3,8 @@
  * references per mode. With a curated seed this is exactly the kit's original map; a generated seed
  * moves the brand steps to wherever the seed landed (its anchor).
  */
+import { STEPS } from './palettes.mjs';
+
 const n = (step) => `{primitive.color.neutral.${step}}`;
 const b = (step) => `{primitive.color.brand.${step}}`;
 const p = (ramp, step) => `{primitive.color.${ramp}.${step}}`;
@@ -57,6 +59,29 @@ export function semanticColors(anchor = '600') {
   };
 }
 
+const shift = (step, by) => STEPS[Math.min(STEPS.length - 1, Math.max(0, STEPS.indexOf(step) + by))];
+
+/**
+ * The colours a recipe's styles add (button, field), from the base colours after their contrast fix, so a moved
+ * primary moves the button with it. Field edges that are the field's only boundary (filled, underline) are a
+ * mid neutral, which the gate holds to 3:1 (contrast.mjs).
+ */
+export function styleColors({ button, field }, anchor, colors) {
+  const dark = darkStep(anchor);
+  const buttons = {
+    solid: { button: colors.primary, 'button-foreground': colors['primary-foreground'], 'button-edge': colors.primary },
+    soft: { button: { light: b(100), dark: b(900) }, 'button-foreground': { light: b(700), dark: b(200) }, 'button-edge': { light: b(100), dark: b(900) } },
+    outline: { button: colors.background, 'button-foreground': colors.primary, 'button-edge': colors.primary },
+    raised: { button: colors.primary, 'button-foreground': colors['primary-foreground'], 'button-edge': { light: b(shift(anchor, 2)), dark: b(shift(dark, 2)) } },
+  };
+  const fields = {
+    outline: { field: colors.input, 'field-edge': colors.input },
+    filled: { field: colors.muted, 'field-edge': { light: n(500), dark: n(400) } },
+    underline: { field: colors.background, 'field-edge': { light: n(500), dark: n(500) } },
+  };
+  return { ...buttons[button], ...fields[field] };
+}
+
 /** Tokens that share the brand step; when the fixer moves `primary`, these move with it. */
 export const BRAND_LINKED = ['ring', 'sidebar-primary', 'sidebar-ring'];