@hotelfriendag/design-tokens 0.3.0

package/generate-tokens.cjs

@@ -0,0 +1,665 @@
+#!/usr/bin/env node
+/*
+ * generate-tokens.cjs
+ *
+ * Reads `tokens.figma.json` (Tokens Studio format, sibling file) and emits
+ * a framework-specific token file you can drop into a project.
+ *
+ * Targets:
+ *   --target=css                  → :root { --token: value; ... }                 (vanilla CSS)
+ *   --target=tailwind             → module.exports = { theme: { extend: {...} } } (Tailwind v3 preset, legacy)
+ *   --target=tailwind-v4          → @theme { --color-hf-*: ...; --text-hf-*: ... }(Tailwind v4 CSS theme, collision-safe by prefix)
+ *   --target=tailwind-v4-additive → alias of `tailwind-v4` (kept for API discoverability — see Dispatch comment)
+ *   --target=scss                 → $token: value;                                (SCSS variables)
+ *   --target=ts                   → export const tokens = {...}                   (TypeScript source)
+ *   --target=js                   → module.exports = { tokens: {...} }            (CommonJS module — Node consumers)
+ *   --target=dts                  → export declare const tokens: {...}            (TypeScript declarations)
+ *   --target=shadcn               → :root { --primary: ...; --background: ... }   (shadcn/ui CSS contract — unprefixed by contract)
+ *
+ * Usage (from this folder, or anywhere — paths are relative to the script):
+ *   node generate-tokens.cjs --target=css                  > pre-built/tokens.css
+ *   node generate-tokens.cjs --target=tailwind             > pre-built/tailwind.preset.js
+ *   node generate-tokens.cjs --target=tailwind-v4          > pre-built/tailwind.css
+ *   node generate-tokens.cjs --target=tailwind-v4-additive > pre-built/tailwind.additive.css   (= same content)
+ *   node generate-tokens.cjs --target=scss                 > pre-built/_tokens.scss
+ *   node generate-tokens.cjs --target=ts                   > pre-built/tokens.ts
+ *   node generate-tokens.cjs --target=js                   > pre-built/tokens.js
+ *   node generate-tokens.cjs --target=dts                  > pre-built/tokens.d.ts
+ *   node generate-tokens.cjs --target=shadcn               > pre-built/shadcn-tokens.css
+ *
+ * Pass --in=path/to/tokens.figma.json to override the input file.
+ *
+ * ESM compatibility: the `.cjs` extension guarantees this script runs under Node even when
+ * the host project has `"type": "module"` in package.json (Vite / Vue 3 / most modern repos).
+ * Do not rename to `.js` without rewriting to ESM `import`/`export`.
+ */
+const fs = require('fs');
+const path = require('path');
+
+const arg = (name) => {
+  const a = process.argv.find(s => s.startsWith('--' + name + '='));
+  return a ? a.slice(name.length + 3) : null;
+};
+const target = arg('target') || 'css';
+const inputPath = arg('in') || path.resolve(__dirname, 'tokens.figma.json');
+const raw = JSON.parse(fs.readFileSync(inputPath, 'utf8'));
+const G = raw.global || raw;
+
+// ── RFC-0001 §4.2: collision-safe `hf-` prefix ──
+// All emitted CSS variable names insert `hf-` AFTER the category segment so they
+// 1) cannot shadow Tailwind v4 defaults (--text-*, --spacing-*, --radius-*, --font-*)
+// 2) still match Tailwind v4's utility derivation (--color-* → bg-*, etc.)
+//
+// Example: tokens.figma.json `color.primary` → CSS `--color-hf-primary` → Tailwind utility `bg-hf-primary`.
+// (Not `--hf-color-primary` because that wouldn't generate any utility — Tailwind v4 only
+//  scans tokens that start with its known utility prefixes: --color-, --text-, --spacing-, etc.)
+//
+// Exception: --target=shadcn emits unprefixed names (shadcn's contract requires fixed names).
+//
+// Override via --prefix=foo- (e.g. --prefix=  for unprefixed legacy output).
+const PREFIX = arg('prefix') ?? 'hf-';
+
+// ── Helpers ──────────────────────────────────────────────────────────────────
+const isToken = (v) => v && typeof v === 'object' && 'value' in v && 'type' in v;
+function flatten(obj, prefix = []) {
+  // Walk Tokens Studio tree → flat list of { path: ['color','primary','default'], token }
+  const out = [];
+  for (const [k, v] of Object.entries(obj)) {
+    if (k.startsWith('$')) continue; // skip $themes / $metadata
+    const next = [...prefix, k];
+    if (isToken(v)) out.push({ path: next, token: v });
+    else if (v && typeof v === 'object') out.push(...flatten(v, next));
+  }
+  return out;
+}
+
+// ── RFC-0002: Tier normalisation + alias resolution ──
+// Tokens Studio supports two notations we need to resolve:
+//   1. Tier prefixes  — `primitive.color.blue.500` and `semantic.color.accent.default`
+//                       both emit as if their path started with `color` (the actual category).
+//                       We STRIP the leading `primitive`/`semantic` segment so kebab() works.
+//   2. Reference values — a token's `value` can be a string like `"{primitive.color.blue.500}"`
+//                         which means "use the resolved value of that token". For CSS targets we
+//                         emit `var(--color-hf-blue-500)` (preserving the alias chain at runtime).
+//                         For non-CSS targets (TS/SCSS/shadcn/v3-preset) we inline the resolved value.
+const TIER_NAMESPACES = new Set(['primitive', 'semantic']);
+
+// Strip leading tier namespace so downstream emitters see a clean category-first path.
+const normalisePath = (parts) => {
+  if (parts.length > 1 && TIER_NAMESPACES.has(parts[0])) return parts.slice(1);
+  return parts;
+};
+
+// Resolve a token-studio-style reference (e.g. "{primitive.color.blue.500}") to its raw value.
+// `aliasMode='css'`: returns var(--color-hf-blue-500) so the chain stays runtime-resolvable.
+// `aliasMode='inline'`: returns the resolved raw value, walking the chain if needed.
+// `tokens`: lookup index { 'primitive.color.blue.500': token, ... }
+const isRef = (v) => typeof v === 'string' && /^\{[\w.-]+\}$/.test(v);
+const refTarget = (v) => v.slice(1, -1); // strip braces
+
+function resolveRef(ref, tokenIndex, mode = 'inline', seen = new Set()) {
+  if (seen.has(ref)) throw new Error(`Token alias cycle detected: ${[...seen, ref].join(' → ')}`);
+  seen.add(ref);
+  const target = tokenIndex[ref];
+  if (!target) {
+    // Reference not found — return the raw ref so the consumer can spot it.
+    console.error(`Warning: unresolved token reference {${ref}}`);
+    return `{${ref}}`;
+  }
+  if (mode === 'css') {
+    // Emit var() pointing to the target CSS variable. Path → kebab name.
+    const targetPath = normalisePath(ref.split('.'));
+    return `var(--${kebab(targetPath)})`;
+  }
+  // mode === 'inline' — walk the chain
+  const tv = target.value;
+  if (isRef(tv)) return resolveRef(refTarget(tv), tokenIndex, mode, seen);
+  return tv;
+}
+
+// Resolve a token's value for emission. Handles refs + composite (typography/boxShadow) values.
+function resolveValue(token, tokenIndex, aliasMode = 'inline') {
+  const v = token.value;
+  if (isRef(v)) return resolveRef(refTarget(v), tokenIndex, aliasMode);
+  return v;
+}
+// Drop trailing 'default' / 'DEFAULT' so a `.default` sub-key becomes the base token name.
+// Example: color.primary.default → color-primary (not color-primary-default).
+// This matches Tokens Studio + Tailwind v3 `DEFAULT` convention.
+const stripDefault = (parts) => {
+  const last = parts[parts.length - 1];
+  return (last === 'default' || last === 'DEFAULT') ? parts.slice(0, -1) : parts;
+};
+const kebabSeg = (s) => s.replace(/[A-Z]/g, m => '-' + m.toLowerCase()).replace(/-+/g, '-');
+const prefixNoDash = () => PREFIX.replace(/-$/, '');
+
+// kebab(parts) — for CSS target (full path INCLUDING leading category segment).
+// PREFIX is inserted AFTER the first (category) segment.
+// Examples (PREFIX='hf-'):
+//   ['color', 'primary']    → 'color-hf-primary'   → CSS: --color-hf-primary
+//   ['shadow', 'modal']     → 'shadow-hf-modal'    → CSS: --shadow-hf-modal
+//   ['spacing', '5']        → 'spacing-hf-5'       → CSS: --spacing-hf-5
+//   ['shadow']  (from .default collapse) → 'shadow-hf' → CSS: --shadow-hf
+const kebab = (parts) => {
+  const clean = stripDefault(parts);
+  if (PREFIX === '') return clean.map(kebabSeg).join('-');
+  if (clean.length === 0) return prefixNoDash();
+  if (clean.length === 1) return kebabSeg(clean[0]) + '-' + prefixNoDash();
+  const first = kebabSeg(clean[0]);
+  const rest  = clean.slice(1).map(kebabSeg).join('-');
+  return first + '-' + PREFIX + rest;
+};
+
+// suffix(parts) — for Tailwind v4 / shadcn emitters that already prepend a category
+// (e.g. `--color-`, `--shadow-`, `--text-`). The caller has sliced off the category
+// segment and passes the remainder; suffix() returns "{PREFIX}{remainder}" or just
+// PREFIX (no dash) when the remainder is empty.
+// Examples (PREFIX='hf-'):
+//   suffix(['primary'])      → 'hf-primary'         → used with --color-: `--color-hf-primary`
+//   suffix(['text','primary'])→ 'hf-text-primary'   → `--color-hf-text-primary`
+//   suffix([])               → 'hf'                 → used with --shadow-: `--shadow-hf`
+const suffix = (parts) => {
+  const clean = stripDefault(parts);
+  if (PREFIX === '') return clean.map(kebabSeg).join('-');
+  if (clean.length === 0) return prefixNoDash();
+  return PREFIX + clean.map(kebabSeg).join('-');
+};
+
+const camelRaw = (parts) => {
+  const clean = stripDefault(parts);
+  return clean.map((p, i) => (i === 0 ? p : p[0].toUpperCase() + p.slice(1))).join('');
+};
+const camel = (parts) => camelRaw(parts);
+
+const allRaw = flatten(G);
+// Build token lookup index by FULL path (including tier prefix) so refs like
+// "{primitive.color.blue.500}" can be resolved.
+const tokenIndex = Object.fromEntries(allRaw.map(({ path, token }) => [path.join('.'), token]));
+// `all` is the flattened list with TIER-NORMALISED paths (primitive/semantic stripped).
+// All emitters use this so the path passed to kebab()/suffix() starts with the actual category.
+const all = allRaw.map(({ path, token }) => ({ path: normalisePath(path), token }));
+
+// ── CSS target ───────────────────────────────────────────────────────────────
+function emitCss() {
+  const lines = [];
+  lines.push('/*');
+  lines.push(' * HotelFriend design tokens — CSS custom properties');
+  lines.push(' * Generated from docs/tokens.figma.json — do NOT edit by hand.');
+  lines.push(' *');
+  lines.push(' * Three-tier model per RFC-0002:');
+  lines.push(' *   primitive.* → raw palette values (--color-hf-blue-500, --color-hf-gray-300, …)');
+  lines.push(' *   semantic.*  → role tokens via var() chain (--color-hf-accent → var(--color-hf-blue-500))');
+  lines.push(' *');
+  lines.push(' * App code should reference SEMANTIC tokens. Primitives are theming-layer detail.');
+  lines.push(' */');
+  lines.push(':root {');
+  for (const { path: p, token } of all) {
+    if (token.type === 'typography' || token.type === 'boxShadow') continue;
+    const v = resolveValue(token, tokenIndex, 'css'); // string OR `var(--…)` for refs
+    if (typeof v === 'object') continue;
+    lines.push(`  --${kebab(p)}: ${v};` + (token.description ? ` /* ${token.description} */` : ''));
+  }
+  // Box shadow composites → flat string
+  for (const { path: p, token } of all) {
+    if (token.type !== 'boxShadow') continue;
+    const v = token.value;
+    if (Array.isArray(v)) continue;
+    const str = `${v.x}px ${v.y}px ${v.blur}px ${v.spread}px ${v.color}`;
+    lines.push(`  --${kebab(p)}: ${str};` + (token.description ? ` /* ${token.description} */` : ''));
+  }
+  lines.push('}');
+  lines.push('');
+  lines.push('/* Composite typography tokens (use as utility classes) */');
+  for (const { path: p, token } of all) {
+    if (token.type !== 'typography') continue;
+    const v = token.value;
+    const cls = '.' + kebab(p);
+    lines.push(`${cls} {`);
+    if (v.fontFamily)  lines.push(`  font-family: ${v.fontFamily.replace(/[{}]/g, '')};`);
+    if (v.fontWeight)  lines.push(`  font-weight: var(--font-weight-${PREFIX}${v.fontWeight.replace(/[{}]/g, '').replace(/^fontWeight\./, '')});`);
+    if (v.fontSize)    lines.push(`  font-size: var(--font-size-${PREFIX}${v.fontSize.replace(/[{}]/g, '').replace(/^fontSize\./, '')});`);
+    if (v.lineHeight)  lines.push(`  line-height: var(--line-height-${PREFIX}${v.lineHeight.replace(/[{}]/g, '').replace(/^lineHeight\./, '')});`);
+    lines.push('}');
+  }
+  return lines.join('\n');
+}
+
+// ── SCSS target ──────────────────────────────────────────────────────────────
+function emitScss() {
+  const lines = [];
+  lines.push('// HotelFriend design tokens — SCSS variables');
+  lines.push('// Generated from docs/tokens.figma.json — do NOT edit by hand.');
+  lines.push('');
+  for (const { path: p, token } of all) {
+    if (typeof token.value !== 'string') continue;
+    lines.push(`$${camel(p)}: ${token.value};${token.description ? ' // ' + token.description : ''}`);
+  }
+  for (const { path: p, token } of all) {
+    if (token.type !== 'boxShadow') continue;
+    const v = token.value;
+    if (Array.isArray(v)) continue;
+    const str = `${v.x}px ${v.y}px ${v.blur}px ${v.spread}px ${v.color}`;
+    lines.push(`$${camel(p)}: ${str};`);
+  }
+  return lines.join('\n');
+}
+
+// ── TypeScript / JS / DTS targets ────────────────────────────────────────────
+// All three share the same nested-object shape (path → leaf string value).
+// `nestTokens()` builds it once; emit functions wrap it in language-specific syntax.
+function nestTokens() {
+  const root = {};
+  for (const { path: p, token } of all) {
+    let cur = root;
+    for (let i = 0; i < p.length - 1; i++) {
+      cur[p[i]] = cur[p[i]] || {};
+      cur = cur[p[i]];
+    }
+    let v = token.value;
+    if (token.type === 'boxShadow' && typeof v === 'object' && !Array.isArray(v)) {
+      v = `${v.x}px ${v.y}px ${v.blur}px ${v.spread}px ${v.color}`;
+    }
+    cur[p[p.length - 1]] = v;
+  }
+  return root;
+}
+
+function emitTs() {
+  const obj = nestTokens();
+  const banner = [
+    '// HotelFriend design tokens — TypeScript const',
+    '// Generated from docs/tokens.figma.json — do NOT edit by hand.',
+    '',
+    'export const tokens = ' + JSON.stringify(obj, null, 2) + ' as const;',
+    '',
+    'export type Tokens = typeof tokens;',
+  ];
+  return banner.join('\n');
+}
+
+function emitJs() {
+  const obj = nestTokens();
+  const banner = [
+    '// HotelFriend design tokens — CommonJS module',
+    '// Generated from docs/tokens.figma.json — do NOT edit by hand.',
+    '//',
+    '// Works with both `require("@hotelfriendag/design-tokens").tokens` and',
+    '// ESM `import { tokens } from "@hotelfriendag/design-tokens"` via Node CJS-ESM interop.',
+    '',
+    'const tokens = ' + JSON.stringify(obj, null, 2) + ';',
+    '',
+    'module.exports = { tokens };',
+  ];
+  return banner.join('\n');
+}
+
+// Emit a `.d.ts` declaration matching the same tree shape, with `string` at the leaves.
+// Choice: concrete key paths (so `tokens.color.blue["500"]` autocompletes) but `string`
+// leaf type (avoids 6KB of literal types and lets values mutate without breaking dts).
+function emitDts() {
+  const obj = nestTokens();
+  const isSafeIdent = (k) => /^[A-Za-z_$][\w$]*$/.test(k);
+  function typeOf(node, indent) {
+    if (typeof node === 'string') return 'string';
+    const pad = '  '.repeat(indent);
+    const padInner = '  '.repeat(indent + 1);
+    const entries = Object.entries(node).map(([k, v]) => {
+      const key = isSafeIdent(k) ? k : JSON.stringify(k);
+      return `${padInner}readonly ${key}: ${typeOf(v, indent + 1)};`;
+    });
+    return '{\n' + entries.join('\n') + '\n' + pad + '}';
+  }
+  const banner = [
+    '// HotelFriend design tokens — TypeScript declarations',
+    '// Generated from docs/tokens.figma.json — do NOT edit by hand.',
+    '',
+    'export declare const tokens: ' + typeOf(obj, 0) + ';',
+    '',
+    'export type Tokens = typeof tokens;',
+  ];
+  return banner.join('\n');
+}
+
+// ── Tailwind preset ──────────────────────────────────────────────────────────
+function emitTailwind() {
+  // Reshape colors: { primary: { default, hover, ... }, neutral: {...}, status: {...}, badge: {...} }
+  const colors = {};
+  const fontSize = {};
+  const fontWeight = {};
+  const lineHeight = {};
+  const fontFamily = {};
+  const borderRadius = {};
+  const spacing = {};
+  const boxShadow = {};
+  const zIndex = {};
+  const transitionTimingFunction = {};
+
+  for (const { path: p, token } of all) {
+    const value = token.value;
+    if (token.type === 'color') {
+      // Build nested color object: color.primary.default → colors.primary.DEFAULT
+      // Path starts with 'color', skip first segment
+      const cp = p.slice(1);
+      let cur = colors;
+      for (let i = 0; i < cp.length - 1; i++) {
+        cur[cp[i]] = cur[cp[i]] || {};
+        cur = cur[cp[i]];
+      }
+      const last = cp[cp.length - 1];
+      cur[last === 'default' ? 'DEFAULT' : last] = value;
+    } else if (token.type === 'fontSizes') {
+      fontSize[p[1]] = value;
+    } else if (token.type === 'fontWeights') {
+      fontWeight[p[1]] = value;
+    } else if (token.type === 'lineHeights') {
+      lineHeight[p[1]] = value;
+    } else if (token.type === 'fontFamilies') {
+      fontFamily[p[1]] = value.split(',').map(s => s.trim());
+    } else if (token.type === 'borderRadius') {
+      borderRadius[p[1]] = value;
+    } else if (token.type === 'spacing') {
+      spacing[p[1]] = value;
+    } else if (token.type === 'sizing') {
+      spacing[p[1]] = value;
+    } else if (token.type === 'boxShadow') {
+      const v = value;
+      if (typeof v === 'object' && !Array.isArray(v)) {
+        boxShadow[p[1]] = `${v.x}px ${v.y}px ${v.blur}px ${v.spread}px ${v.color}`;
+      } else {
+        boxShadow[p[1]] = String(v);
+      }
+    } else if (token.type === 'other') {
+      if (p[0] === 'zIndex') zIndex[p[1]] = String(value);
+      else if (p[0] === 'motion') transitionTimingFunction[p[1]] = String(value);
+    }
+  }
+
+  const lines = [];
+  lines.push('/**');
+  lines.push(' * HotelFriend design tokens — Tailwind v3 preset (legacy)');
+  lines.push(' * Generated from docs/tokens.figma.json — do NOT edit by hand.');
+  lines.push(' *');
+  lines.push(' * For new projects use --target=tailwind-v4 (pre-built/tailwind.css).');
+  lines.push(' *');
+  lines.push(' * Usage in tailwind.config.js:');
+  lines.push(' *   const hfPreset = require("./tailwind.preset.js");');
+  lines.push(' *   module.exports = { presets: [hfPreset], content: [...] };');
+  lines.push(' */');
+  lines.push('module.exports = {');
+  lines.push('  theme: {');
+  lines.push('    extend: {');
+  lines.push('      colors: ' + JSON.stringify(colors, null, 6).split('\n').join('\n      ') + ',');
+  lines.push('      fontFamily: ' + JSON.stringify(fontFamily, null, 6).split('\n').join('\n      ') + ',');
+  lines.push('      fontSize: ' + JSON.stringify(fontSize, null, 6).split('\n').join('\n      ') + ',');
+  lines.push('      fontWeight: ' + JSON.stringify(fontWeight, null, 6).split('\n').join('\n      ') + ',');
+  lines.push('      lineHeight: ' + JSON.stringify(lineHeight, null, 6).split('\n').join('\n      ') + ',');
+  lines.push('      borderRadius: ' + JSON.stringify(borderRadius, null, 6).split('\n').join('\n      ') + ',');
+  lines.push('      spacing: ' + JSON.stringify(spacing, null, 6).split('\n').join('\n      ') + ',');
+  lines.push('      boxShadow: ' + JSON.stringify(boxShadow, null, 6).split('\n').join('\n      ') + ',');
+  lines.push('      zIndex: ' + JSON.stringify(zIndex, null, 6).split('\n').join('\n      ') + ',');
+  lines.push('      transitionTimingFunction: ' + JSON.stringify(transitionTimingFunction, null, 6).split('\n').join('\n      ') + ',');
+  lines.push('    },');
+  lines.push('  },');
+  lines.push('};');
+  return lines.join('\n');
+}
+
+// ── Tailwind v4 CSS theme ────────────────────────────────────────────────────
+function emitTailwind4() {
+  const lines = [];
+  lines.push('/*');
+  lines.push(' * HotelFriend design tokens — Tailwind v4 CSS theme');
+  lines.push(' * Generated from docs/tokens.figma.json — do NOT edit by hand.');
+  lines.push(' *');
+  lines.push(' * Usage in your main CSS entry file:');
+  lines.push(' *   @import "tailwindcss";');
+  lines.push(' *   @import "./pre-built/tailwind.css";');
+  lines.push(' *');
+  lines.push(' * Tailwind v4 auto-generates utilities from @theme variables:');
+  lines.push(' *   --color-*      → bg-*, text-*, border-*, ring-*, …');
+  lines.push(' *   --text-*       → text-*');
+  lines.push(' *   --font-*       → font-* (family)');
+  lines.push(' *   --font-weight-*→ font-* (weight)');
+  lines.push(' *   --leading-*    → leading-*');
+  lines.push(' *   --radius-*     → rounded-*');
+  lines.push(' *   --shadow-*     → shadow-*');
+  lines.push(' *   --z-*          → z-*');
+  lines.push(' */');
+  lines.push('@theme {');
+
+  // Colors — --color-{path} (drop leading "color" segment; collapse "default" leaf)
+  // Refs (e.g. semantic.color.accent → "{primitive.color.blue.500}") emit as var() chain.
+  lines.push('  /* Colors */');
+  for (const { path: p, token } of all) {
+    if (token.type !== 'color') continue;
+    lines.push(`  --color-${suffix(p.slice(1))}: ${resolveValue(token, tokenIndex, 'css')};`);
+  }
+
+  // Font families — map primary→sans per Tailwind v4 convention
+  lines.push('  /* Typography — font families */');
+  for (const { path: p, token } of all) {
+    if (token.type !== 'fontFamilies') continue;
+    // Special case: tokens.figma.json `fontFamily.primary` → Tailwind v4 `--font-sans` (default family)
+    // PREFIX still applied: `--font-hf-sans`
+    const isSansAlias = p[p.length - 1] === 'primary';
+    const name = isSansAlias ? prefixNoDash() + '-sans' : suffix(p.slice(1));
+    lines.push(`  --font-${name}: ${token.value};`);
+  }
+
+  // Font weights — --font-weight-{name}
+  lines.push('  /* Typography — font weights */');
+  for (const { path: p, token } of all) {
+    if (token.type !== 'fontWeights') continue;
+    lines.push(`  --font-weight-${suffix(p.slice(1))}: ${token.value};`);
+  }
+
+  // Font sizes — --text-{name}
+  lines.push('  /* Typography — font sizes */');
+  for (const { path: p, token } of all) {
+    if (token.type !== 'fontSizes') continue;
+    lines.push(`  --text-${suffix(p.slice(1))}: ${token.value};`);
+  }
+
+  // Line heights — --leading-{name}
+  lines.push('  /* Typography — line heights */');
+  for (const { path: p, token } of all) {
+    if (token.type !== 'lineHeights') continue;
+    lines.push(`  --leading-${suffix(p.slice(1))}: ${token.value};`);
+  }
+
+  // Border radius — --radius-{name}
+  lines.push('  /* Border radius */');
+  for (const { path: p, token } of all) {
+    if (token.type !== 'borderRadius') continue;
+    lines.push(`  --radius-${suffix(p.slice(1))}: ${token.value};`);
+  }
+
+  // Spacing / sizing — --spacing-{name}
+  lines.push('  /* Spacing */');
+  for (const { path: p, token } of all) {
+    if (token.type !== 'spacing' && token.type !== 'sizing') continue;
+    lines.push(`  --spacing-${suffix(p.slice(1))}: ${token.value};`);
+  }
+
+  // Box shadows — --shadow-{name}
+  lines.push('  /* Shadows */');
+  for (const { path: p, token } of all) {
+    if (token.type !== 'boxShadow') continue;
+    const v = token.value;
+    if (typeof v === 'object' && !Array.isArray(v)) {
+      lines.push(`  --shadow-${suffix(p.slice(1))}: ${v.x}px ${v.y}px ${v.blur}px ${v.spread}px ${v.color};`);
+    }
+  }
+
+  // Z-index — --z-{name}
+  lines.push('  /* Z-index */');
+  for (const { path: p, token } of all) {
+    if (token.type === 'other' && p[0] === 'zIndex') {
+      lines.push(`  --z-${suffix(p.slice(1))}: ${token.value};`);
+    }
+  }
+
+  lines.push('}');
+  return lines.join('\n');
+}
+
+// ── shadcn/ui target ─────────────────────────────────────────────────────────
+function emitShadcn() {
+  // shadcn v4 uses @theme inline with --color-* prefixed variables.
+  // Full contract: ~25 semantic slots + sidebar tokens + font + radius.
+  const lines = [];
+  lines.push('/* HotelFriend design tokens — shadcn/ui v4 contract');
+  lines.push(' * Generated from docs/tokens.figma.json — do NOT edit by hand.');
+  lines.push(' *');
+  lines.push(' * Usage: append to app/globals.css (after @import "tailwindcss")');
+  lines.push(' *   @import "./pre-built/shadcn-tokens.css";');
+  lines.push(' */');
+  lines.push('@theme inline {');
+  lines.push('  /* ── Base ── */');
+  lines.push('  --color-background:              #FFFFFF;');
+  lines.push('  --color-foreground:              #2B2B2B;   /* text-primary */');
+  lines.push('');
+  lines.push('  /* ── Card ── */');
+  lines.push('  --color-card:                    #FFFFFF;');
+  lines.push('  --color-card-foreground:         #2B2B2B;');
+  lines.push('');
+  lines.push('  /* ── Popover ── */');
+  lines.push('  --color-popover:                 #FFFFFF;');
+  lines.push('  --color-popover-foreground:      #2B2B2B;');
+  lines.push('');
+  lines.push('  /* ── Primary ── */');
+  lines.push('  --color-primary:                 #24AFE8;   /* canonical brand */');
+  lines.push('  --color-primary-foreground:      #FFFFFF;');
+  lines.push('');
+  lines.push('  /* ── Secondary ── */');
+  lines.push('  --color-secondary:               #E4E8EF;   /* neutral border */');
+  lines.push('  --color-secondary-foreground:    #4B5675;   /* text-secondary */');
+  lines.push('');
+  lines.push('  /* ── Muted ── */');
+  lines.push('  --color-muted:                   #F1F3F6;   /* very-light bg */');
+  lines.push('  --color-muted-foreground:        #99A1B7;   /* placeholder */');
+  lines.push('');
+  lines.push('  /* ── Accent ── */');
+  lines.push('  --color-accent:                  #E9F6FC;   /* primary light tint */');
+  lines.push('  --color-accent-foreground:       #149AD1;   /* primary-hover */');
+  lines.push('');
+  lines.push('  /* ── Destructive ── */');
+  lines.push('  --color-destructive:             #EA6565;   /* status error */');
+  lines.push('  --color-destructive-foreground:  #FFFFFF;');
+  lines.push('');
+  lines.push('  /* ── Border / Input / Ring ── */');
+  lines.push('  --color-border:                  #D1D6DD;');
+  lines.push('  --color-input:                   #D1D6DD;');
+  lines.push('  --color-ring:                    #24AFE8;   /* focus ring = primary */');
+  lines.push('');
+  lines.push('  /* ── Chart palette (maps to HF status colors) ── */');
+  lines.push('  --color-chart-1:                 #59B59D;   /* success */');
+  lines.push('  --color-chart-2:                 #FFBD5A;   /* warning */');
+  lines.push('  --color-chart-3:                 #24AFE8;   /* primary */');
+  lines.push('  --color-chart-4:                 #F87921;   /* coral */');
+  lines.push('  --color-chart-5:                 #EA6565;   /* error */');
+  lines.push('');
+  lines.push('  /* ── Sidebar ── */');
+  lines.push('  --color-sidebar:                 #F6F7FB;   /* bg-accent */');
+  lines.push('  --color-sidebar-foreground:      #4B5675;');
+  lines.push('  --color-sidebar-primary:         #24AFE8;');
+  lines.push('  --color-sidebar-primary-foreground: #FFFFFF;');
+  lines.push('  --color-sidebar-accent:          #E9F6FC;');
+  lines.push('  --color-sidebar-accent-foreground: #2B2B2B;');
+  lines.push('  --color-sidebar-border:          #E4E8EF;');
+  lines.push('  --color-sidebar-ring:            #24AFE8;');
+  lines.push('');
+  lines.push('  /* ── Radius ── */');
+  lines.push('  --radius:                        6px;       /* $br-sm */');
+  lines.push('');
+  lines.push('  /* ── Font ── */');
+  lines.push('  --font-sans:                     Roboto, sans-serif;');
+  lines.push('}');
+  return lines.join('\n');
+}
+
+// ── status-css target ─────────────────────────────────────────────────────────
+// Reads `status-map.json` and emits CSS rules:
+//   .status-{domain}-{state} { color: var(--color-hf-status-{role}); background: var(...-bg); }
+// One canonical source for the domain→semantic-role mapping, replacing the
+// hand-maintained block previously in `pre-built/components.css` (RFC-0002 §Q7 refinement).
+function emitStatusCss() {
+  const mapPath = path.resolve(__dirname, 'status-map.json');
+  if (!fs.existsSync(mapPath)) {
+    throw new Error(`status-map.json not found at ${mapPath}. Required for --target=status-css.`);
+  }
+  const map = JSON.parse(fs.readFileSync(mapPath, 'utf8'));
+
+  const lines = [];
+  lines.push('/*');
+  lines.push(' * HotelFriend status pills — domain → semantic mapping');
+  lines.push(' * Generated from docs/status-map.json — do NOT edit by hand.');
+  lines.push(' *');
+  lines.push(' * Each .status-{domain}-{state} class binds to a semantic status slot');
+  lines.push(' * (--color-hf-status-{role}) so adding a new domain status is JSON-only —');
+  lines.push(' * no CSS edit needed.');
+  lines.push(' *');
+  lines.push(' * Pair with .hf-pill from components.css for the visual chrome.');
+  lines.push(' */');
+  lines.push('');
+
+  // Collect domain entries (everything except keys starting with $ or _)
+  for (const [domain, states] of Object.entries(map)) {
+    if (domain.startsWith('$')) continue;
+    if (domain === '_orphan') {
+      // Standalone classes (.status-{key} — no domain prefix)
+      lines.push('/* Standalone (no domain prefix) */');
+      for (const [state, role] of Object.entries(states)) {
+        if (state.startsWith('$')) continue;
+        const colorVar = `--color-${PREFIX}status-${role}`;
+        const bgVar    = `--color-${PREFIX}status-${role}-bg`;
+        lines.push(`.status-${state} { color: var(${colorVar}); background: var(${bgVar}); }`);
+      }
+      lines.push('');
+      continue;
+    }
+    // Per-domain block
+    const domainTitle = domain.replace(/-/g, ' ').replace(/\b\w/g, c => c.toUpperCase());
+    lines.push(`/* ${domainTitle} */`);
+    // Group by role so identical mappings (all cancellations → cancel) collapse to one selector list
+    const byRole = {};
+    for (const [state, role] of Object.entries(states)) {
+      if (state.startsWith('$')) continue;
+      (byRole[role] = byRole[role] || []).push(state);
+    }
+    for (const [role, statesArr] of Object.entries(byRole)) {
+      const selectors = statesArr.map(s => `.status-${domain}-${s}`).join(',\n');
+      const colorVar = `--color-${PREFIX}status-${role}`;
+      const bgVar    = `--color-${PREFIX}status-${role}-bg`;
+      lines.push(`${selectors} { color: var(${colorVar}); background: var(${bgVar}); }`);
+    }
+    lines.push('');
+  }
+  return lines.join('\n');
+}
+
+// ── Dispatch ─────────────────────────────────────────────────────────────────
+//
+// `tailwind-v4-additive` is an explicit alias for `tailwind-v4`:
+//   - After Phase 1A's `hf-` prefix, every emitted token is namespace-isolated:
+//     --color-hf-*, --text-hf-*, --radius-hf-*, --spacing-hf-*, --font-hf-* etc.
+//     none of these can collide with Tailwind v4 defaults (--color-*, --text-*, --radius-*, etc.).
+//   - So "additive" is a property of the prefix model, not a separate filter.
+//   - The alias exists for API discoverability (RFC-0001 §4.2) and for projects whose
+//     integration scripts explicitly request it. Identical bytes-output.
+//   - For TRULY additive-only emit (skip any non-prefixed default-overrides), no current
+//     output emits unprefixed keys — so this alias is a 1:1.
+const out =
+  target === 'css'                  ? emitCss() :
+  target === 'scss'                 ? emitScss() :
+  target === 'ts'                   ? emitTs() :
+  target === 'js'                   ? emitJs() :
+  target === 'dts'                  ? emitDts() :
+  target === 'tailwind'             ? emitTailwind() :
+  target === 'tailwind-v4'          ? emitTailwind4() :
+  target === 'tailwind-v4-additive' ? emitTailwind4() : // alias — see comment above
+  target === 'shadcn'               ? emitShadcn() :
+  target === 'status-css'           ? emitStatusCss() :
+  (() => { throw new Error(`Unknown target: ${target}. Use css | scss | ts | js | dts | tailwind | tailwind-v4 | tailwind-v4-additive | status-css | shadcn`); })();
+
+process.stdout.write(out + '\n');