@halftone-ds/tokens 1.0.0 → 1.2.0

package/lib/theme/shadcn.mjs

@@ -0,0 +1,265 @@
+/**
+ * Halftone ⇄ shadcn. Pure ESM, no Node APIs: the docs site's studio runs it in the browser.
+ *
+ *   isShadcnPresetCode(s)        a shadcn/ui preset code (ui.shadcn.com/create): "b5owWMfJ8l"
+ *   decodeShadcnPreset(code)     → { version, style, baseColor, theme, chartColor, iconLibrary, font,
+ *                                    fontHeading, radius, menuAccent, menuColor } | null
+ *   encodeShadcnPreset(preset)   the reverse (tests, round trips)
+ *   recipeFromShadcn(preset)     → { recipe, notes }: the nearest Halftone recipe, and one plain line per
+ *                                  value it approximated or dropped (Halftone has no match for it)
+ *   shadcnTheme(theme, options)  a shadcn `registry:theme` item for a generated theme: colours (oklch, light
+ *                                  and dark), radius, shadows, and its fonts as registryDependencies
+ *   shadcnFont(id, role)         the `registry:font` item those dependencies point at
+ *
+ * A Halftone theme carries more than a shadcn preset (density, depth, border, icon stroke, typeset, both kits),
+ * so codes go one way: a shadcn code becomes a Halftone recipe, never the reverse. The other way is the
+ * registry item, which any shadcn project installs with `npx shadcn add`.
+ *
+ * The preset codec below is ported from shadcn/ui, packages/registry/src/preset/preset.ts (@shadcn/registry
+ * 0.2.0, shadcn 4.22). Its value lists are append-only there; keep them in step.
+ *
+ *   MIT License
+ *
+ *   Copyright (c) 2023 shadcn
+ *
+ *   Permission is hereby granted, free of charge, to any person obtaining a copy of this software and
+ *   associated documentation files (the "Software"), to deal in the Software without restriction, including
+ *   without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+ *   copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the
+ *   following conditions:
+ *
+ *   The above copyright notice and this permission notice shall be included in all copies or substantial
+ *   portions of the Software.
+ *
+ *   THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT
+ *   LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO
+ *   EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER
+ *   IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE
+ *   USE OR OTHER DEALINGS IN THE SOFTWARE.
+ */
+import { fontById } from './fonts.mjs';
+import { BRAND_RAMPS, NEUTRAL_RAMPS } from './palettes.mjs';
+import { normalizeRecipe } from './recipe.mjs';
+import { themeVars } from './vars.mjs';
+
+// ---- the preset codec (ported) --------------------------------------------------------------------------
+
+const MENU_COLORS = ['default', 'inverted', 'default-translucent', 'inverted-translucent'];
+const MENU_ACCENTS = ['subtle', 'bold'];
+const RADII = ['default', 'none', 'small', 'medium', 'large'];
+const FONTS = [
+  'inter', 'noto-sans', 'nunito-sans', 'figtree', 'roboto', 'raleway', 'dm-sans', 'public-sans', 'outfit', 'jetbrains-mono',
+  'geist', 'geist-mono', 'lora', 'merriweather', 'playfair-display', 'noto-serif', 'roboto-slab', 'oxanium', 'manrope',
+  'space-grotesk', 'montserrat', 'ibm-plex-sans', 'source-sans-3', 'instrument-sans', 'eb-garamond', 'instrument-serif',
+];
+const ICON_LIBRARIES = ['lucide', 'hugeicons', 'tabler', 'phosphor', 'remixicon'];
+const THEMES = [
+  'neutral', 'stone', 'zinc', 'gray', 'amber', 'blue', 'cyan', 'emerald', 'fuchsia', 'green', 'indigo', 'lime', 'orange',
+  'pink', 'purple', 'red', 'rose', 'sky', 'teal', 'violet', 'yellow', 'mauve', 'olive', 'mist', 'taupe',
+];
+const BASE_COLORS = ['neutral', 'stone', 'zinc', 'gray', 'mauve', 'olive', 'mist', 'taupe'];
+const STYLES = ['nova', 'vega', 'maia', 'lyra', 'mira', 'luma', 'sera', 'rhea'];
+const FONT_HEADINGS = ['inherit', ...FONTS];
+
+const FIELDS_V1 = [
+  { key: 'menuColor', values: MENU_COLORS, bits: 3 },
+  { key: 'menuAccent', values: MENU_ACCENTS, bits: 3 },
+  { key: 'radius', values: RADII, bits: 4 },
+  { key: 'font', values: FONTS, bits: 6 },
+  { key: 'iconLibrary', values: ICON_LIBRARIES, bits: 6 },
+  { key: 'theme', values: THEMES, bits: 6 },
+  { key: 'baseColor', values: BASE_COLORS, bits: 6 },
+  { key: 'style', values: STYLES, bits: 6 },
+];
+const FIELDS_V2 = [...FIELDS_V1, { key: 'chartColor', values: THEMES, bits: 6 }, { key: 'fontHeading', values: FONT_HEADINGS, bits: 5 }];
+/** v1 codes carry no chart colour; ui.shadcn.com picks one per theme (apps/v4 preset-query.ts). */
+const V1_CHART_COLOR = { neutral: 'blue', stone: 'lime', zinc: 'amber', mauve: 'emerald', olive: 'violet', mist: 'rose', taupe: 'cyan' };
+
+const BASE62 = '0123456789ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz';
+const fromBase62 = (text) => {
+  let n = 0;
+  for (const ch of text) {
+    const i = BASE62.indexOf(ch);
+    if (i === -1) return -1;
+    n = n * 62 + i;
+  }
+  return n;
+};
+const toBase62 = (n) => {
+  if (n === 0) return '0';
+  let s = '';
+  while (n > 0) {
+    s = BASE62[n % 62] + s;
+    n = Math.floor(n / 62);
+  }
+  return s;
+};
+
+export const isShadcnPresetCode = (s) => typeof s === 'string' && /^[ab][0-9A-Za-z]{1,9}$/.test(s);
+
+export function decodeShadcnPreset(code) {
+  if (!isShadcnPresetCode(code)) return null;
+  const version = code[0];
+  const fields = version === 'a' ? FIELDS_V1 : FIELDS_V2;
+  const bits = fromBase62(code.slice(1));
+  if (bits < 0) return null;
+  const preset = { version };
+  let offset = 0;
+  for (const field of fields) {
+    const i = Math.floor(bits / 2 ** offset) % 2 ** field.bits;
+    preset[field.key] = i < field.values.length ? field.values[i] : field.values[0];
+    offset += field.bits;
+  }
+  if (version === 'a') {
+    preset.fontHeading = 'inherit';
+    preset.chartColor = V1_CHART_COLOR[preset.theme] ?? preset.theme;
+  }
+  return preset;
+}
+
+export function encodeShadcnPreset(preset) {
+  let bits = 0;
+  let offset = 0;
+  for (const field of FIELDS_V2) {
+    const i = field.values.indexOf(preset[field.key] ?? field.values[0]);
+    bits += (i === -1 ? 0 : i) * 2 ** offset;
+    offset += field.bits;
+  }
+  return `b${toBase62(bits)}`;
+}
+
+// ---- shadcn → Halftone ----------------------------------------------------------------------------------
+
+/** shadcn's extra greys → the nearest Halftone neutral. */
+const NEAREST_NEUTRAL = { mauve: 'zinc', olive: 'stone', mist: 'slate', taupe: 'stone' };
+const RADIUS = { default: 'lg', medium: 'lg', none: 'none', small: 'sm', large: 'xl' };
+const RADIUS_REM = { small: '0.45rem', large: '0.875rem' };
+/** shadcn's fonts → Halftone's (the same family, or the nearest of the same kind). */
+const FONT = {
+  inter: 'inter', 'dm-sans': 'dm-sans', outfit: 'outfit', 'jetbrains-mono': 'jetbrains-mono', geist: 'geist', 'geist-mono': 'geist-mono',
+  lora: 'lora', 'playfair-display': 'playfair-display', manrope: 'manrope', 'space-grotesk': 'space-grotesk', 'ibm-plex-sans': 'ibm-plex-sans',
+  'noto-sans': 'inter', 'nunito-sans': 'nunito', figtree: 'plus-jakarta-sans', roboto: 'inter', raleway: 'outfit', 'public-sans': 'inter',
+  montserrat: 'outfit', 'source-sans-3': 'inter', 'instrument-sans': 'inter', oxanium: 'space-grotesk',
+  merriweather: 'source-serif-4', 'noto-serif': 'source-serif-4', 'roboto-slab': 'source-serif-4', 'eb-garamond': 'fraunces',
+  'instrument-serif': 'playfair-display',
+};
+const title = (id) => id.split('-').map((w) => (/^(dm|ibm|eb)$/.test(w) ? w.toUpperCase() : w[0].toUpperCase() + w.slice(1))).join(' ');
+
+/** The nearest Halftone recipe for a decoded shadcn preset, with a note for everything it couldn't carry. */
+export function recipeFromShadcn(preset) {
+  const notes = [];
+  const base = preset.baseColor;
+  const neutral = NEAREST_NEUTRAL[base] ?? base;
+  if (NEAREST_NEUTRAL[base]) notes.push(`Base colour ${base}: Halftone has no ${base} grey, so it uses ${neutral}, the nearest.`);
+
+  let brand;
+  if (BRAND_RAMPS[preset.theme]) brand = BRAND_RAMPS[preset.theme]['600'];
+  else {
+    // A monochrome theme (the theme is a grey): the brand is that grey's 900, as in Halftone's Mono preset.
+    const grey = NEAREST_NEUTRAL[preset.theme] ?? preset.theme;
+    brand = NEUTRAL_RAMPS[grey]['900'];
+    if (NEAREST_NEUTRAL[preset.theme] && preset.theme !== base) notes.push(`Theme ${preset.theme}: a monochrome brand in ${grey}, the nearest grey.`);
+  }
+
+  const radius = RADIUS[preset.radius] ?? 'lg';
+  if (RADIUS_REM[preset.radius]) notes.push(`Radius ${preset.radius} (${RADIUS_REM[preset.radius]}): Halftone's nearest step is ${radius}.`);
+
+  const font = (id, role) => {
+    const mapped = FONT[id] ?? 'inter';
+    if (mapped !== id) notes.push(`${role} font ${title(id)}: not in Halftone's list, so it uses ${fontById(mapped).family}.`);
+    return mapped;
+  };
+  const body = font(preset.font, 'Body');
+  const heading = preset.fontHeading && preset.fontHeading !== 'inherit' ? font(preset.fontHeading, 'Heading') : body;
+  // shadcn has no separate mono role; a mono body or heading font takes it too.
+  const mono = [body, heading].find((id) => fontById(id).category === 'mono') ?? 'system-mono';
+
+  if (preset.iconLibrary && preset.iconLibrary !== 'lucide') notes.push(`Icons ${title(preset.iconLibrary)}: Halftone's kits use Lucide.`);
+  if (preset.chartColor && preset.chartColor !== preset.theme) notes.push(`Chart colour ${preset.chartColor}: Halftone's charts follow the brand.`);
+  if (preset.menuAccent === 'bold') notes.push("Bold menu accents aren't a Halftone option: accents stay neutral.");
+  if (preset.menuColor && preset.menuColor !== 'default') notes.push(`Menu colour ${preset.menuColor} isn't a Halftone option.`);
+  if (preset.style && preset.style !== 'nova') {
+    notes.push(`Style ${title(preset.style)}: Halftone's own density, depth and border apply. Start from a Halftone preset to change them.`);
+  }
+
+  const recipe = normalizeRecipe({ brand, neutral, radius, font: { heading, body, mono } });
+  return { recipe, notes };
+}
+
+// ---- Halftone → shadcn ----------------------------------------------------------------------------------
+
+export const SHADCN_FONTS_URL = 'https://halftonedesignsystem.com/r';
+
+/** Tailwind's rounded-* steps as multiples of --radius (the kits' primitive radius steps over lg). */
+const RADIUS_STEPS = { sm: 0.6, md: 0.8, lg: 1, xl: 1.6, '2xl': 2 };
+const SHADOW_STEPS = { '2xs': 1, xs: 1, sm: 1, md: 2, lg: 3, xl: 3, '2xl': 3 };
+const FONT_VARIABLE = { body: '--font-sans', heading: '--font-heading', mono: '--font-mono' };
+const FALLBACK = { sans: 'sans-serif', display: 'sans-serif', serif: 'serif', mono: 'monospace' };
+const SELECTOR = { heading: 'h1, h2, h3, h4, h5, h6', mono: 'code, kbd, pre, samp' };
+
+/** The registry item path (under the fonts URL) for a font in a role. */
+const fontPath = (id, role) => `font/${role === 'body' ? '' : `${role}-`}${id}.json`;
+
+/** A shadcn `registry:font` item for one of Halftone's Google fonts, in a role (body, heading or mono). */
+export function shadcnFont(id, role = 'body') {
+  const f = fontById(id);
+  if (!f || f.system) return null;
+  const variable = f.fontsource !== 'static';
+  return {
+    $schema: 'https://ui.shadcn.com/schema/registry-item.json',
+    name: role === 'body' ? `font-${id}` : `font-${role}-${id}`,
+    title: f.family,
+    type: 'registry:font',
+    font: {
+      family: `'${f.family}${variable ? ' Variable' : ''}', ${FALLBACK[f.category] ?? 'sans-serif'}`,
+      provider: 'google',
+      import: f.family.replace(/ /g, '_'),
+      variable: FONT_VARIABLE[role],
+      subsets: ['latin'],
+      ...(variable ? {} : { weight: f.weights.map(String) }),
+      // shadcn applies a font's utility to `html` by default: the body font does go there, but the heading font
+      // belongs on headings (as in Halftone's kits) and the mono font on code.
+      ...(role === 'body' ? {} : { selector: SELECTOR[role] }),
+      dependency: `@fontsource${variable ? '-variable' : ''}/${id}`,
+    },
+  };
+}
+
+/**
+ * A shadcn `registry:theme` item for a generated theme. `npx shadcn add` writes the colours into :root and
+ * .dark, the radius and shadow steps into @theme, and installs the fonts it depends on (fontsUrl/font/*.json,
+ * hosted by the docs site). Web only: phone apps take the theme code.
+ */
+export function shadcnTheme(theme, { name, title: label, description, fontsUrl = SHADCN_FONTS_URL } = {}) {
+  const vars = themeVars(theme, 'oklch');
+  // The button and field styles are Halftone's own (shadcn's components don't read them): they stay behind.
+  const colours = Object.keys(theme.resolved.light).filter((c) => !/^(button|field)(-|$)/.test(c));
+  const mode = (m) => ({
+    ...(m === 'light' ? { radius: vars.light['--radius'] } : {}),
+    ...Object.fromEntries(colours.map((c) => [c, vars[m][`--${c}`]])),
+    ...Object.fromEntries(['1', '2', '3'].map((level) => [`shadow-${level}`, vars[m][`--shadow-${level}`]])),
+  });
+  const roles = { body: theme.recipe.font.body, heading: theme.recipe.font.heading, mono: theme.recipe.font.mono };
+  const dependencies = Object.entries(roles)
+    .filter(([, id]) => !fontById(id)?.system)
+    .map(([role, id]) => `${fontsUrl.replace(/\/$/, '')}/${fontPath(id, role)}`);
+  return {
+    $schema: 'https://ui.shadcn.com/schema/registry-item.json',
+    name: name ?? `halftone-${theme.code}`,
+    title: label ?? `Halftone theme ${theme.code}`,
+    description: description ?? `A Halftone theme (${theme.code}): colours for light and dark, radius, shadows and fonts. halftonedesignsystem.com/themes/?t=${theme.code}`,
+    type: 'registry:theme',
+    ...(dependencies.length ? { registryDependencies: dependencies } : {}),
+    cssVars: {
+      theme: {
+        ...Object.fromEntries(Object.entries(RADIUS_STEPS).map(([step, k]) => [`radius-${step}`, k === 1 ? 'var(--radius)' : `calc(var(--radius) * ${k})`])),
+        ...Object.fromEntries(Object.entries(SHADOW_STEPS).map(([step, level]) => [`shadow-${step}`, `var(--shadow-${level})`])),
+      },
+      light: mode('light'),
+      dark: mode('dark'),
+    },
+  };
+}
+
+/** Where the docs site hosts a font item, for build scripts: `font/<id>.json`, `font/heading-<id>.json`, … */
+export const shadcnFontPath = fontPath;

package/lib/theme/vars.mjs

@@ -20,6 +20,30 @@ export const typeVars = (type) => ({
   '--typeset-measure': `${type.measure}ch`,
 });
 
+/**
+ * The button and field styles' variables (both formats), from a theme's or a token file's { button, field }
+ * (generate.mjs, resolve.mjs). Widths and radii are numbers on the light block; the field's fill opacity is
+ * per mode. A field's inner padding is the kit's own: 1rem on mobile (hsl), px-3 on the web (oklch).
+ */
+export function styleVars({ button, field }, format) {
+  return {
+    light: {
+      '--button-alpha': String(button.alpha),
+      '--button-border-w': `${button.border}px`,
+      '--button-edge-w': `${button.edge}px`,
+      '--field-alpha': String(field.alpha.light),
+      '--field-border-w': `${field.border}px`,
+      '--field-edge-w': `${field.edge}px`,
+      '--field-radius': rem(field.radius),
+      '--field-radius-b': rem(field.radiusBottom),
+      '--field-x': field.inset ? (format === 'hsl' ? '1rem' : 'calc(var(--spacing) * 3)') : '0px',
+      // Web: a boxed field keeps shadcn's shadow-xs; a filled or underline field has none.
+      ...(format === 'hsl' ? {} : { '--field-shadow': field.border ? 'var(--shadow-1)' : '0 0 #0000' }),
+    },
+    dark: { '--field-alpha': String(field.alpha.dark) },
+  };
+}
+
 /** { light: { '--primary': '…', '--radius': '0.625rem' }, dark: { … } } */
 export function themeVars(theme, format) {
   const convert = format === 'hsl' ? hexToHslTriplet : hexToOklch;
@@ -34,6 +58,7 @@ export function themeVars(theme, format) {
       for (const size of ['sm', 'md', 'lg', 'x']) vars[`--control-${size}`] = `${theme.density[size]}px`;
       Object.assign(vars, typeVars(theme.type));
     }
+    Object.assign(vars, styleVars(theme, format)[m]);
     for (const [level, value] of Object.entries(theme.semantic.shadow)) vars[`--shadow-${level}`] = shadowCss(value[m]);
     return vars;
   };

package/lib/theme-cli.mjs

@@ -1,17 +1,26 @@
 /**
  * `halftone-tokens theme …` — commit a theme from the docs picker into tokens.json.
  *
- *   theme apply <code|preset|recipe.json> [--dry-run] [--force]
+ *   theme apply <theme> [--dry-run] [--force]
  *        write the theme into tokens.json (only the paths a theme owns) and rebuild
  *   theme show [--check]   the applied theme, its code and any hand edits since (drift)
  *                          --check: exit 1 if the recorded theme no longer reproduces (CI)
  *   theme presets          list the presets and their codes
- *   theme encode <recipe.json>   print the code for a recipe file
+ *   theme encode <theme>   print the Halftone code for a theme
+ *   theme decode <code> [--json]   what a code holds (a Halftone code, or a shadcn preset and what it maps to)
+ *   theme resolve [--json] the code for tokens.json as it is; exit 1 if none is recorded or it was edited
+ *   theme shadcn <theme> [--out file] [--fonts-url url]
+ *                          the theme as a shadcn registry:theme item (stdout, or a file), for `npx shadcn add`
+ *
+ * <theme> is a Halftone code (ht1-…, ht2-…, ht3-…), a preset name, a recipe .json, or a shadcn/ui preset code
+ * (ui.shadcn.com/create, e.g. b5owWMfJ8l), which becomes the nearest Halftone recipe: what it approximates
+ * or drops is listed on stderr.
  */
 import { spawnSync } from 'node:child_process';
 import { existsSync, readFileSync, writeFileSync } from 'node:fs';
 import { join } from 'node:path';
 
+import { cvdWarnings, describeCvdWarnings, MIN_DELTA_E } from './cvd.mjs';
 import { FONTS } from './theme/fonts.mjs';
 
 import {
@@ -23,6 +32,11 @@ import {
   normalizeRecipe,
   presetById,
   PRESETS,
+  decodeShadcnPreset,
+  isShadcnPresetCode,
+  recipeFromShadcn,
+  SHADCN_FONTS_URL,
+  shadcnTheme,
   themeStatus,
 } from './theme/index.mjs';
 
@@ -31,8 +45,14 @@ const fail = (message, code = 1) => {
   process.exit(code);
 };
 
+/** A shadcn code's mapping notes, on stderr so stdout stays a code or JSON. */
+function printNotes(code, notes) {
+  if (!notes.length) return;
+  console.error(`From shadcn preset ${code}, approximated or not carried:\n${notes.map((n) => `  - ${n}`).join('\n')}`);
+}
+
 function readRecipe(arg, root) {
-  if (!arg) fail('say which theme: a code (ht1-… or ht2-…), a preset name or a recipe .json', 2);
+  if (!arg) fail('say which theme: a code (ht1-…, ht2-… or ht3-…), a preset name, a recipe .json or a shadcn preset code', 2);
   if (isThemeCode(arg)) {
     try {
       return decodeRecipe(arg);
@@ -44,11 +64,18 @@ function readRecipe(arg, root) {
   if (preset) return normalizeRecipe({ ...preset.recipe, preset: preset.id });
   const file = join(root, arg);
   if (arg.endsWith('.json') && existsSync(file)) return normalizeRecipe(JSON.parse(readFileSync(file, 'utf8')));
-  fail(`"${arg}" is not a theme code, a preset (${PRESETS.map((p) => p.id).join(', ')}) or a recipe file`, 2);
+  // Last, so a preset name that happens to look like one (bold, brutalist) stays Halftone's preset.
+  const shadcn = isShadcnPresetCode(arg) ? decodeShadcnPreset(arg) : null;
+  if (shadcn) {
+    const { recipe, notes } = recipeFromShadcn(shadcn);
+    printNotes(arg, notes);
+    return recipe;
+  }
+  fail(`"${arg}" is not a theme code, a preset (${PRESETS.map((p) => p.id).join(', ')}), a recipe file or a shadcn preset code`, 2);
 }
 
 const describe = (input) => {
-  // A recipe recorded by an older halftone-tokens has no typeset: it gets the defaults.
+  // A recipe recorded by an older halftone-tokens has no typeset or styles: it gets the defaults.
   const recipe = normalizeRecipe(input);
   const font = (id) => {
     const f = fontById(id);
@@ -58,6 +85,7 @@ const describe = (input) => {
     `brand ${recipe.brand} · neutral ${recipe.neutral} · radius ${recipe.radius} · controls ${recipe.controls}`,
     `type ${font(recipe.font.heading)} / ${font(recipe.font.body)} · stroke ${recipe.stroke} · depth ${recipe.depth} · density ${recipe.density} · border ${recipe.border}`,
     `typeset ${recipe.size}px · leading ${recipe.leading} · flow ${recipe.flow} · measure ${recipe.measure}ch · mono ${font(recipe.font.mono)}`,
+    `styles: ${recipe.button} buttons · ${recipe.field} fields`,
   ].join('\n  ');
 };
 
@@ -100,6 +128,65 @@ export async function themeCommand({ positional, flags, root, sourcePath, config
     return;
   }
 
+  if (sub === 'decode') {
+    if (!arg) fail('say which code to decode: ht1-…, ht2-…, ht3-… or a shadcn preset code', 2);
+    // A preset name first, as for apply: `bold` is Halftone's preset, not a shadcn code.
+    const preset = presetById(arg.toLowerCase());
+    if (preset) {
+      const recipe = normalizeRecipe({ ...preset.recipe, preset: preset.id });
+      if (flags.json) console.log(JSON.stringify({ kind: 'halftone', preset: preset.id, code: encodeRecipe(recipe), recipe }, null, 2));
+      else console.log(`Halftone preset ${preset.name}: ${encodeRecipe(recipe)}\n  ${describe(recipe)}`);
+      return;
+    }
+    if (isThemeCode(arg)) {
+      let recipe;
+      try {
+        recipe = decodeRecipe(arg);
+      } catch (error) {
+        fail(error.message);
+      }
+      if (flags.json) console.log(JSON.stringify({ kind: 'halftone', code: encodeRecipe(recipe), recipe }, null, 2));
+      else console.log(`Halftone theme ${encodeRecipe(recipe)}\n  ${describe(recipe)}`);
+      return;
+    }
+    const shadcn = isShadcnPresetCode(arg) ? decodeShadcnPreset(arg) : null;
+    if (!shadcn) fail(`"${arg}" is not a Halftone theme code or a shadcn preset code`, 2);
+    const { recipe, notes } = recipeFromShadcn(shadcn);
+    const code = encodeRecipe(recipe);
+    if (flags.json) {
+      console.log(JSON.stringify({ kind: 'shadcn', shadcn, code, recipe, notes }, null, 2));
+      return;
+    }
+    const fields = Object.entries(shadcn).map(([k, v]) => `${k} ${v}`).join(' · ');
+    console.log(`shadcn preset ${arg}\n  ${fields}\n\nAs a Halftone theme: ${code}\n  ${describe(recipe)}`);
+    if (notes.length) console.log(`\nApproximated or not carried:\n${notes.map((n) => `  - ${n}`).join('\n')}`);
+    return;
+  }
+
+  if (sub === 'resolve') {
+    const status = themeStatus(tokens());
+    if (!status.applied) fail('no theme recorded in tokens.json, so there is no code for it. Apply one with `halftone-tokens theme apply <theme>`.');
+    if (status.drift.length) fail(`tokens.json was edited by hand since ${status.code} was applied (${status.drift.length} token(s)); no code reproduces it. \`theme show\` lists them.`);
+    if (flags.json) console.log(JSON.stringify({ code: status.code, recipe: status.recipe }, null, 2));
+    else console.log(status.code);
+    return;
+  }
+
+  if (sub === 'shadcn') {
+    const recipe = readRecipe(arg, root);
+    const { theme } = applyRecipe(tokens(), recipe);
+    const item = shadcnTheme(theme, {
+      ...(recipe.preset ? { name: `halftone-${recipe.preset}`, title: `Halftone ${presetById(recipe.preset)?.name} theme` } : {}),
+      fontsUrl: typeof flags['fonts-url'] === 'string' ? flags['fonts-url'] : SHADCN_FONTS_URL,
+    });
+    const json = JSON.stringify(item, null, 2) + '\n';
+    if (typeof flags.out === 'string') {
+      writeFileSync(join(root, flags.out), json);
+      console.error(`Wrote ${flags.out}: install it in a shadcn project with \`npx shadcn@latest add ./${flags.out.split('/').pop()}\`.`);
+    } else process.stdout.write(json);
+    return;
+  }
+
   if (sub === 'show') {
     const status = themeStatus(tokens());
     if (!status.applied) {
@@ -133,6 +220,11 @@ export async function themeCommand({ positional, flags, root, sourcePath, config
       console.log(`\nAdjusted for contrast (WCAG AA), hue kept:`);
       for (const a of theme.adjustments) console.log(`  ${a.mode.padEnd(5)} ${a.token.padEnd(28)} ${a.from} → ${a.to}`);
     }
+    const cvd = cvdWarnings(theme.resolved);
+    if (cvd.length) {
+      console.log(`\nColour vision: ${cvd.length} pair(s) of tones closer than ΔE ${MIN_DELTA_E} (a warning; give them an icon or a label as well):`);
+      console.log(describeCvdWarnings(cvd).join('\n'));
+    }
     if (flags['dry-run']) {
       console.log(`\n--dry-run: nothing written.${blocked && !flags.force ? `\nNote: ${blocked}` : ''}`);
       return;
@@ -144,5 +236,5 @@ export async function themeCommand({ positional, flags, root, sourcePath, config
     return;
   }
 
-  fail(`unknown command "theme ${sub}". Use apply, show, presets or encode.`, 2);
+  fail(`unknown command "theme ${sub}". Use apply, show, presets, encode, decode, resolve or shadcn.`, 2);
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@halftone-ds/tokens",
-  "version": "1.0.0",
+  "version": "1.2.0",
   "description": "Design tokens (W3C DTCG) to NativeWind, Tailwind 4 / shadcn, TypeScript, DESIGN.md and Figma, with a WCAG AA contrast gate. The token build behind Halftone.",
   "license": "MIT",
   "type": "module",

package/targets/design-md.mjs

@@ -46,6 +46,37 @@ function typography(prim, type) {
     .join('\n');
 }
 
+/**
+ * The contrast sentence. A passing palette says the build names any pairing that falls short (and --strict
+ * fails on it); a failing one, which only builds without --strict, names its pairings.
+ */
+function contrastLine(ctx) {
+  const failures = ctx.contrastFailures ?? [];
+  if (!failures.length) {
+    return `Every \`X\` / \`X-foreground\` pairing, muted text on every surface, and every status tone used as text
+clears WCAG AA (4.5:1) in both themes; the build names any pairing that falls short, and \`--strict\` fails on it.`;
+  }
+  return `${failures.length} pairing(s) in this palette fall below WCAG AA (4.5:1). Fix them before handing a prototype
+over (\`npm run tokens:build -- --strict\` fails on them):
+
+${failures.map((f) => `- ${f.trim()}`).join('\n')}`;
+}
+
+/** How the theme's styles read in DESIGN.md. */
+const STYLE_TEXT = {
+  button: {
+    solid: 'The primary button is a solid brand fill.',
+    soft: 'The primary button is a soft brand tint with brand text.',
+    outline: 'The primary button is a brand outline with brand text, no fill.',
+    raised: 'The primary button is a solid brand fill with a darker bottom edge.',
+  },
+  field: {
+    outline: 'Text fields are outlined boxes.',
+    filled: 'Text fields are tinted, with a line along the bottom.',
+    underline: 'Text fields are a single line, no box.',
+  },
+};
+
 export default function designMd(ctx, options) {
   const name = options.name ?? 'Halftone';
   // Which radius buttons use: 'control' (the theme's pill setting, the mobile kit) or a scale step (web: 'md').
@@ -131,8 +162,7 @@ hex literal or a Tailwind palette colour in UI code. Keys ending in \`-dark\` ar
 - **Destructive, Success, Warning, Info:** status only, each with its own \`-foreground\`.
 - **Chart 1–5:** data series.
 
-Every \`X\` / \`X-foreground\` pairing, muted text on every surface, and every status tone used as text
-clears WCAG AA (4.5:1) in both themes; the build refuses a palette that does not.
+${contrastLine(ctx)}
 
 A tone's text on that tone's own tint (\`text-success\` on \`bg-success/15\`) is a weaker pairing. With
 this palette it clears AA only for:
@@ -171,7 +201,7 @@ ${radius['2xl']}px; chips, avatars and dots are fully round.
 ## Components
 
 Only components listed in the registry in \`DESIGN_SYSTEM.md\` exist. Controls are 48px tall (small
-40, large 56). Selected chips and segments are neutral (inverted foreground), never the brand colour.
+40, large 56). ${STYLE_TEXT.button[ctx.styles.button]} ${STYLE_TEXT.field[ctx.styles.field]} Selected chips and segments are neutral (inverted foreground), never the brand colour.
 Motion: ${duration.fast}ms for micro-feedback, ${duration.base}ms for most transitions, ${duration.slow}ms for sheets, and
 nothing moves when the OS asks for reduced motion.
 

package/targets/llms.mjs

@@ -21,7 +21,7 @@ export default function llms(ctx, options) {
 
 Colours are semantic names only, used as Tailwind classes (\`bg-primary\`, \`text-muted-foreground\`,
 \`border-border\`, \`bg-success/15\`). Never hex, never Tailwind palette colours. Both themes are
-required; every fill/foreground pairing clears WCAG AA (${AA}:1), enforced by \`npm run tokens:build\`.
+required; ${ctx.contrastFailures?.length ? `${ctx.contrastFailures.length} pairing(s) in this palette fall below WCAG AA (${AA}:1): fix them (\`npm run tokens:build\` names them).` : `every fill/foreground pairing clears WCAG AA (${AA}:1); \`npm run tokens:build\` names any that falls short (\`--strict\` fails on it).`}
 A tone's own text on its own tint (\`text-success\` on \`bg-success/15\`) clears AA only for these
 tints; on a stronger one, put \`text-foreground\` on the tint:
 ${describeTintLimits(textOnTintLimits(ctx.colors))}.
@@ -34,6 +34,7 @@ ${rows}
 - Radius (\`rounded-*\`): ${ctx.radius.steps.map((s) => `${s.name} ${Math.round(ctx.radius.base * s.scale * 10) / 10}px`).join(' · ')} (multiples of \`--radius\` = ${ctx.radius.base}px)${options.controlRadius === false ? '; buttons use \`rounded-md\`' : `; \`rounded-control\` (buttons, chips) ${ctx.shape.control >= 9999 ? 'pill' : `${ctx.shape.control}px`}`}
 - Depth: \`shadow-sm\` (controls, cards), \`shadow-md\` (raised, popovers), \`shadow-lg\` (menus, dialogs) are the theme's three elevation levels; no shadow colour modifiers on surfaces (thumbs and floating elements may add \`shadow-black/20\`)
 - Border \`border\` ${ctx.shape.borderWidth}px · icon stroke ${ctx.shape.stroke} (an Icon's \`strokeWidth\` is relative to 2)
+- Styles: ${ctx.styles.button} buttons, ${ctx.styles.field} fields. Button and the text fields already draw them (\`bg-button\`, \`bg-field\`); never restyle a primary button or a field by hand
 - Fonts: headings ${fonts.heading?.family ?? 'system'}, body ${fonts.body?.family ?? 'system'}, mono ${fonts.mono?.family ?? 'system'} (applied by Text; \`font-heading\` makes any Text a heading, \`font-mono\` code and figures)
 - Typeset: body ${ctx.type.size}px, leading ${ctx.type.leading}; every \`text-*\` size below scales by ${ctx.type.scale}${theme.applied ? `\n- Theme: \`${theme.code}\` (\`npx halftone-tokens theme show\`)` : ''}
 - Font sizes (\`text-*\`): ${steps(['font', 'size'])}

package/targets/nativewind3.mjs

@@ -6,26 +6,33 @@
 import { hexToHslTriplet } from '../lib/color.mjs';
 import { cssName, group, isColor, radiusCalc } from '../lib/resolve.mjs';
 import { TEXT_LINE_HEIGHT } from '../lib/theme/recipe.mjs';
+import { styleVars } from '../lib/theme/vars.mjs';
 
 const rem = (px) => (px >= 9999 ? '9999px' : `${Number((px / 16).toFixed(4))}rem`);
 
 /** Shape variables come from ctx.shape, which has defaults for a token file from before themes. */
 const SHAPE = new Set(['radius-control', 'border-width', 'icon-stroke']);
 
-function cssBlock(selector, tokens, shape) {
+function cssBlock(selector, tokens, shape, mode, colors) {
   const lines = tokens
-    // Shadows are literal in tailwind.theme.js: a var() box-shadow drops the view on native.
+    // Shadows are literal in tailwind.theme.js: a var() box-shadow drops the view on native. The styles'
+    // numbers come from shape (with their units), below.
     .filter((t) => t.$type !== 'shadow' && !SHAPE.has(cssName(t)) && !/^(density|type)-/.test(cssName(t)))
+    .filter((t) => isColor(t) || !/^(button|field)-/.test(cssName(t)))
     .map((t) => {
       const name = cssName(t);
       if (isColor(t)) return `    --${name}: ${hexToHslTriplet(t.$value)};`;
       if (name === 'radius') return `    --${name}: ${rem(t.$value)};`;
       return `    --${name}: ${t.$value};`;
     });
-  if (shape) {
+  if (shape.control !== undefined) {
     lines.push(`    --radius-control: ${rem(shape.control)};`, `    --border-width: ${shape.borderWidth}px;`, `    --icon-stroke: ${shape.stroke};`);
     for (const size of ['sm', 'md', 'lg', 'x']) lines.push(`    --control-${size}: ${shape.density[size]}px;`);
   }
+  // Style colours a token file from before the styles doesn't have (resolve.mjs adds them), then the styles' numbers.
+  const present = new Set(tokens.filter(isColor).map(cssName));
+  for (const c of colors) if (!present.has(c.name)) lines.push(`    --${c.name}: ${hexToHslTriplet(c[mode])};`);
+  for (const [name, value] of Object.entries(styleVars(shape.styleShape, 'hsl')[mode])) lines.push(`    ${name}: ${value};`);
   return `  ${selector} {\n${lines.join('\n')}\n  }`;
 }
 
@@ -36,15 +43,23 @@ export default function nativewind3(ctx, options) {
 @tailwind utilities;
 
 @layer base {
-${cssBlock(':root', ctx.semLight, ctx.shape)}
+${cssBlock(':root', ctx.semLight, { ...ctx.shape, styleShape: ctx.shape }, 'light', ctx.colors)}
 
-${cssBlock('.dark:root', ctx.semDark)}
+${cssBlock('.dark:root', ctx.semDark, { styleShape: ctx.shape }, 'dark', ctx.colors)}
 }
 `;
   const colors = Object.fromEntries(ctx.colors.map((c) => [c.name, `hsl(var(--${c.name}))`]));
+  // The styles' fills carry their own opacity (an outline button, a transparent field). No /90 modifiers on these.
+  colors.button = 'hsl(var(--button) / var(--button-alpha))';
+  colors.field = 'hsl(var(--field) / var(--field-alpha))';
   const borderRadius = Object.fromEntries(ctx.radius.steps.map((s) => [s.name, radiusCalc(s.scale)]));
   borderRadius.control = 'var(--radius-control)';
-  const borderWidth = { DEFAULT: 'var(--border-width)' };
+  // Field style: rounded-field (top) and rounded-b-field-b (bottom).
+  borderRadius.field = 'var(--field-radius)';
+  borderRadius['field-b'] = 'var(--field-radius-b)';
+  // The styles' widths: border-button-w / border-b-button-edge-w, border-field-w / border-b-field-edge-w (named
+  // apart from the colours, or border-button would set both).
+  const borderWidth = { DEFAULT: 'var(--border-width)', 'button-w': 'var(--button-border-w)', 'button-edge-w': 'var(--button-edge-w)', 'field-w': 'var(--field-border-w)', 'field-edge-w': 'var(--field-edge-w)' };
   // The theme's depth takes over Tailwind's shadow scale: 1 = xs/sm/shadow, 2 = md, 3 = lg/xl/2xl. Light
   // values: native can't switch a box-shadow per scheme.
   const s = ctx.shape.shadows.light;
@@ -60,7 +75,7 @@ ${cssBlock('.dark:root', ctx.semDark)}
       .map(({ key, value }) => [key, [rem(value * scale), { lineHeight: rem(TEXT_LINE_HEIGHT[key] * scale * leadingFactor) }]])
   );
   const lineHeight = { prose: rem(size * leading) };
-  const spacing = { 'control-x': 'var(--control-x)', flow: rem(size * flow) };
+  const spacing = { 'control-x': 'var(--control-x)', 'field-x': 'var(--field-x)', flow: rem(size * flow) };
   const maxWidth = { measure: rem(measure * size * 0.5) };
   const tailwind = `// ${ctx.header}\nmodule.exports = ${JSON.stringify({ colors, borderRadius, borderWidth, boxShadow, height, minHeight: height, width: height, spacing, fontSize, lineHeight, maxWidth }, null, 2)};\n`;
   return [