@halftone-ds/tokens 1.1.0 → 1.3.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/studio/?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

@@ -5,7 +5,9 @@
  *   'oklch'  Tailwind 4 / shadcn web (`oklch(0.546 0.2152 262.88)`) — the web kit and the docs site
  */
 import { hexToHslTriplet, hexToOklch } from '../color.mjs';
-import { shadowCss } from './recipe.mjs';
+import { componentVars } from './components.mjs';
+import { extraList, extraTextStyles } from './extras.mjs';
+import { resolveTextStyles, shadowCss, textEdits } from './recipe.mjs';
 
 export const rem = (px) => (px >= 9999 ? '9999px' : `${px / 16}rem`);
 
@@ -20,7 +22,80 @@ export const typeVars = (type) => ({
   '--typeset-measure': `${type.measure}ch`,
 });
 
-/** { light: { '--primary': '…', '--radius': '0.625rem' }, dark: { … } } */
+const fixed = (n, places = 4) => Number(n.toFixed(places));
+
+/** A theme's text styles as drawn (recipe.mjs resolveTextStyles): its typeset, its edited styles on top. */
+export const themeTextStyles = (theme) => resolveTextStyles(theme.type, textEdits(theme.semantic?.type));
+
+/**
+ * The text styles' variables, --type-<style>-{size,leading,weight,tracking,font}, from resolveTextStyles. Literal
+ * values at the theme's typeset, in each kit's units:
+ *   'hsl'    mobile (NativeWind): size and line height in rem (native line heights are lengths); the font is
+ *            the role, which components/ui/text.tsx picks in JS, so no variable. Tracking is em on native too:
+ *            NativeWind resolves it against the style's own size (its preset's tracking-* are fixed px instead)
+ *   'oklch'  web: rem and a unitless line height; the font is the role's family variable. `font(role)` writes
+ *            it (the build adds fallbacks; a live theme always sets --kit-font-*)
+ */
+export function textStyleVars(styles, format, font = (role) => `var(--kit-font-${role})`) {
+  const vars = {};
+  // Mobile rounds rem to 4 places, as nativewind3's text-* sizes always were.
+  const length = (px) => (format === 'hsl' ? `${fixed(px / 16)}rem` : rem(fixed(px)));
+  for (const [name, s] of Object.entries(styles)) {
+    const v = `--type-${name}`;
+    vars[`${v}-size`] = length(s.size);
+    vars[`${v}-leading`] = format === 'hsl' ? length(s.lineHeight ?? s.size * s.leading) : String(fixed(s.leading, 6));
+    vars[`${v}-weight`] = String(s.weight);
+    vars[`${v}-tracking`] = `${s.tracking}em`;
+    if (format !== 'hsl') vars[`${v}-font`] = font(s.font);
+  }
+  return vars;
+}
+
+/**
+ * The button and field styles' variables (both formats), from a theme's or a token file's { button, field }
+ * (generate.mjs, resolve.mjs). Widths are numbers on the light block; the field's fill opacity is per mode. A
+ * field's corners and padding are the component layer's (componentVars: --field-radius, --field-radius-b,
+ * --field-x).
+ */
+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`,
+      // 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) },
+  };
+}
+
+/**
+ * A system's extras as variables (lib/theme/extras.mjs): --<colour> (a ramp's --<name>-<step>), --radius-<name>,
+ * --shadow-<name> per mode, --border-<name>-width and --type-<name>-*. `font` as textStyleVars takes it.
+ */
+export function extraVars(list, format, font) {
+  const convert = format === 'hsl' ? hexToHslTriplet : hexToOklch;
+  const light = {};
+  const dark = {};
+  for (const c of list.color) {
+    light[`--${c.name}`] = convert(c.light);
+    dark[`--${c.name}`] = convert(c.dark);
+  }
+  for (const r of list.radius) light[`--radius-${r.name}`] = rem(r.px);
+  for (const s of list.shadow) {
+    light[`--shadow-${s.name}`] = shadowCss(s.light);
+    dark[`--shadow-${s.name}`] = shadowCss(s.dark);
+  }
+  for (const b of list.border) light[`--border-${b.name}-width`] = `${b.width}px`;
+  Object.assign(light, textStyleVars(extraTextStyles(list), format, font));
+  return { light, dark };
+}
+
+/** { light: { '--primary': '…', '--radius': '0.625rem' }, dark: { … } } (a system's extras too) */
 export function themeVars(theme, format) {
   const convert = format === 'hsl' ? hexToHslTriplet : hexToOklch;
   const mode = (m) => {
@@ -32,9 +107,12 @@ export function themeVars(theme, format) {
       vars['--icon-stroke'] = String(theme.stroke);
       vars['--density'] = String(theme.density.scale);
       for (const size of ['sm', 'md', 'lg', 'x']) vars[`--control-${size}`] = `${theme.density[size]}px`;
-      Object.assign(vars, typeVars(theme.type));
+      Object.assign(vars, typeVars(theme.type), textStyleVars(themeTextStyles(theme), format));
     }
+    Object.assign(vars, styleVars(theme, format)[m]);
+    if (theme.components) Object.assign(vars, componentVars(theme.components, format, convert)[m]);
     for (const [level, value] of Object.entries(theme.semantic.shadow)) vars[`--shadow-${level}`] = shadowCss(value[m]);
+    if (theme.extra) Object.assign(vars, extraVars(extraList(theme.extra), format)[m]);
     return vars;
   };
   return { light: mode('light'), dark: mode('dark') };

package/lib/theme-cli.mjs

@@ -1,21 +1,34 @@
 /**
  * `halftone-tokens theme …` — commit a theme from the docs picker into tokens.json.
  *
- *   theme apply <code|preset|recipe.json> [--dry-run] [--force]
- *        write the theme into tokens.json (only the paths a theme owns) and rebuild
+ *   theme apply <theme> [--dry-run] [--force]
+ *        write the theme into tokens.json (only the paths a theme owns) and rebuild; a system document is
+ *        recorded in tokens.json's $extensions (without its brand images)
  *   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, a system document
+ * (name.halftone.json, from the Studio), 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 { join, resolve } from 'node:path';
 
-import { FONTS } from './theme/fonts.mjs';
+import { cvdWarnings, describeCvdWarnings, MIN_DELTA_E } from './cvd.mjs';
+import { FONTS, fontByFamily } from './theme/fonts.mjs';
+import { isSystem, normalizeSystem, SystemError, systemOverrides } from './system/schema.mjs';
+import { systemCode } from './system/generate.mjs';
 
 import {
   applyRecipe,
+  applySystem,
   decodeRecipe,
   encodeRecipe,
   fontById,
@@ -23,6 +36,12 @@ import {
   normalizeRecipe,
   presetById,
   PRESETS,
+  decodeShadcnPreset,
+  isShadcnPresetCode,
+  recipeFromShadcn,
+  SHADCN_FONTS_URL,
+  shadcnTheme,
+  THEME_EXTENSION,
   themeStatus,
 } from './theme/index.mjs';
 
@@ -31,8 +50,61 @@ 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')}`);
+}
+
+/** { recipe, system? }: a system document when <theme> is one (name.halftone.json), else a recipe. */
+function readTheme(arg, root) {
+  // resolve: an absolute path stays itself (join would put it under root).
+  const file = arg ? resolve(root, arg) : '';
+  if (arg?.endsWith('.json') && existsSync(file)) {
+    let json;
+    try {
+      json = JSON.parse(readFileSync(file, 'utf8'));
+    } catch (error) {
+      fail(`${arg} is not valid JSON: ${error.message}`);
+    }
+    if (isSystem(json)) {
+      try {
+        const system = normalizeSystem(json);
+        return { recipe: system.recipe, system };
+      } catch (error) {
+        if (error instanceof SystemError) fail(`${arg}: ${error.message}`);
+        throw error;
+      }
+    }
+  }
+  return { recipe: readRecipe(arg, root) };
+}
+
+/** Why a system has no code: its overrides, briefly. */
+function noCode(system) {
+  const overrides = systemOverrides(system);
+  const shown = overrides.slice(0, 6).join(', ') + (overrides.length > 6 ? `, and ${overrides.length - 6} more` : '');
+  return `"${system.name}" has ${overrides.length} override(s) a theme code can't carry (${shown}). Share its .halftone.json instead.`;
+}
+
+/** A system's overrides, grouped by section, for `show` and `apply`. */
+function describeOverrides(system) {
+  const bySection = {};
+  for (const path of systemOverrides(system)) {
+    const [section, ...rest] = path.split('.');
+    (bySection[section] ??= []).push(rest.join('.'));
+  }
+  return Object.entries(bySection).map(([section, list]) => `${section}: ${list.join(', ')}`);
+}
+
+function printWarnings(warnings) {
+  if (!warnings?.length) return;
+  console.log(`\nBelow WCAG AA because of colours chosen by hand (warnings; the fixer leaves hand-picked colours alone):`);
+  for (const w of warnings) console.log(`  ${w.mode.padEnd(5)} ${w.label.padEnd(40)} ${w.ratio}:1 (needs ${w.threshold})${w.locked.length ? `  · chosen: ${w.locked.join(', ')}` : ''}`);
+}
+
 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, a system .halftone.json or a shadcn preset code', 2);
   if (isThemeCode(arg)) {
     try {
       return decodeRecipe(arg);
@@ -42,13 +114,20 @@ function readRecipe(arg, root) {
   }
   const preset = presetById(arg.toLowerCase());
   if (preset) return normalizeRecipe({ ...preset.recipe, preset: preset.id });
-  const file = join(root, arg);
+  const file = resolve(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 +137,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  ');
 };
 
@@ -70,7 +150,8 @@ function installFonts(root, config, theme, flags) {
   if (config.targets?.fonts?.platform !== 'expo') return;
   const pkg = JSON.parse(readFileSync(join(root, 'package.json'), 'utf8'));
   const have = new Set(Object.keys({ ...pkg.dependencies, ...pkg.devDependencies }).filter((d) => d.startsWith('@expo-google-fonts/')));
-  const ids = Object.values(theme.recipe.font).filter((id) => !fontById(id)?.system);
+  // The theme's families: curated ones, or any Google Fonts family a system names.
+  const ids = Object.values(theme.fonts).filter(Boolean).map(fontByFamily).filter((f) => !f.system).map((f) => f.id);
   const need = [...new Set(ids)].map((id) => `@expo-google-fonts/${id}`);
   const missing = need.filter((p) => !have.has(p));
   const unused = [...have].filter((p) => !need.includes(p) && FONTS.some((f) => `@expo-google-fonts/${f.id}` === p));
@@ -96,7 +177,69 @@ export async function themeCommand({ positional, flags, root, sourcePath, config
   }
 
   if (sub === 'encode') {
-    console.log(encodeRecipe(readRecipe(arg, root)));
+    const { recipe, system } = readTheme(arg, root);
+    if (system && !systemCode(system)) fail(noCode(system));
+    console.log(encodeRecipe(recipe));
+    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.code) fail(`the applied system ${noCode(status.system)} Its document is recorded in tokens.json ($extensions).`);
+    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, system } = readTheme(arg, root);
+    const { theme } = system ? applySystem(tokens(), system) : 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;
   }
 
@@ -107,8 +250,16 @@ export async function themeCommand({ positional, flags, root, sourcePath, config
       if (flags.check) process.exit(0);
       return;
     }
-    const name = status.recipe.preset ? ` (${presetById(status.recipe.preset)?.name ?? status.recipe.preset})` : '';
-    console.log(`Theme ${status.code}${name}\n  ${describe(status.recipe)}`);
+    if (status.system) {
+      const { system } = status;
+      const overrides = describeOverrides(system);
+      console.log(`System "${system.name}"${status.code ? ` ${status.code}` : ' (no theme code: it has overrides)'}\n  ${describe(status.recipe)}`);
+      if (overrides.length) console.log(`\nOverrides:\n${overrides.map((o) => `  ${o}`).join('\n')}`);
+      printWarnings(tokens().$extensions?.[THEME_EXTENSION]?.warnings);
+    } else {
+      const name = status.recipe.preset ? ` (${presetById(status.recipe.preset)?.name ?? status.recipe.preset})` : '';
+      console.log(`Theme ${status.code}${name}\n  ${describe(status.recipe)}`);
+    }
     if (status.drift.length) {
       console.log(`\nEdited by hand since it was applied (${status.drift.length}):\n${status.drift.map((p) => `  ${p}`).join('\n')}`);
       if (flags.check) fail('tokens.json no longer matches its recorded theme. Re-apply it, or apply with --force to record the edits away.');
@@ -117,7 +268,7 @@ export async function themeCommand({ positional, flags, root, sourcePath, config
   }
 
   if (sub === 'apply') {
-    const recipe = readRecipe(arg, root);
+    const { recipe, system } = readTheme(arg, root);
     const current = tokens();
     const status = themeStatus(current);
     const blocked = !status.applied
@@ -127,12 +278,23 @@ export async function themeCommand({ positional, flags, root, sourcePath, config
         ? `these theme tokens were edited by hand since ${status.code} was applied:\n${status.drift.map((p) => `  ${p}`).join('\n')}\nRe-run with --force to overwrite them.`
         : null;
     if (blocked && !flags.force && !flags['dry-run']) fail(blocked);
-    const { tokens: next, theme } = applyRecipe(current, recipe);
-    console.log(`Theme ${theme.code}${recipe.preset ? ` (${presetById(recipe.preset)?.name})` : ''}\n  ${describe(theme.recipe)}`);
+    const { tokens: next, theme } = system ? applySystem(current, system) : applyRecipe(current, recipe);
+    if (system) {
+      const code = systemCode(system);
+      const overrides = describeOverrides(system);
+      console.log(`System "${system.name}"${code ? ` ${code}` : ''}\n  ${describe(theme.recipe)}`);
+      if (overrides.length) console.log(`\nOverrides (no theme code carries these; tokens.json records the document):\n${overrides.map((o) => `  ${o}`).join('\n')}`);
+    } else console.log(`Theme ${theme.code}${recipe.preset ? ` (${presetById(recipe.preset)?.name})` : ''}\n  ${describe(theme.recipe)}`);
     if (theme.adjustments.length) {
       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}`);
     }
+    printWarnings(theme.warnings);
+    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 +306,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);
 }