@ima-jin/tokens 1.0.0

package/README.md

@@ -0,0 +1,29 @@
+# @ima-jin/tokens
+
+Design tokens for the Imajin platform in DTCG format, built with Style Dictionary v4.
+
+## Install
+
+```bash
+npm install @ima-jin/tokens
+```
+
+## Usage
+
+### Tailwind
+
+```js
+// tailwind.config.js
+const tokens = require('@ima-jin/tokens');
+// Use tokens.colors, tokens.spacing, etc.
+```
+
+### CSS Variables
+
+```css
+@import '@ima-jin/tokens/css';
+```
+
+## Part of Imajin
+
+[Imajin](https://imajin.ai) — sovereign technology infrastructure. Open source.

package/build.mjs

@@ -0,0 +1,244 @@
+import StyleDictionary from 'style-dictionary';
+import { formats } from 'style-dictionary/enums';
+
+const { cssVariables } = formats;
+
+// Register a custom dimension transform that preserves original units (rem, em, px)
+StyleDictionary.registerTransform({
+  name: 'dimension/preserve-unit',
+  type: 'value',
+  filter: (token) => token.$type === 'dimension',
+  transform: (token) => {
+    const val = token.$value ?? token.value;
+    // If already a string with a unit suffix, keep it as-is
+    if (typeof val === 'string' && /(px|rem|em|%|vh|vw|ch)$/.test(val)) {
+      return val;
+    }
+    // Otherwise fallback to px
+    return `${val}px`;
+  },
+});
+
+const sd = new StyleDictionary({
+  source: ['tokens.json'],
+  platforms: {
+    css: {
+      // Use web transforms but override dimension to preserve rem/em
+      transforms: [
+        'attribute/cti',
+        'name/kebab',
+        'time/seconds',
+        'dimension/preserve-unit',
+        'color/css',
+        'fontFamily/css',
+      ],
+      buildPath: 'dist/',
+      files: [{
+        destination: 'variables.css',
+        format: cssVariables,
+        options: {
+          outputReferences: true,
+          selector: ':root',
+        },
+      }],
+    },
+    tailwind: {
+      buildPath: 'dist/',
+      transforms: ['attribute/cti', 'name/kebab', 'color/css'],
+      files: [{
+        destination: 'tailwind.js',
+        format: 'tailwind',
+      }],
+    },
+  },
+});
+
+// Register a custom format for Tailwind theme extension
+sd.registerFormat({
+  name: 'tailwind',
+  format: ({ dictionary }) => {
+    const tokens = dictionary.allTokens;
+
+    // Extract colors
+    const colors = {};
+    const sunset = {};
+    const surface = {};
+    const functional = {};
+    const interactive = {};
+
+    // Semantic tokens — role-based aliases (app code uses these, not raw)
+    const semSurface = {};
+    const semText = {};
+    const semCta = {};
+    const semBorder = {};
+    const semStatus = {};
+    let semAccent = null;
+    let semFocusRing = null;
+
+    // Extract spacing
+    const spacing = {};
+
+    // Extract border radius
+    const borderRadius = {};
+
+    // Extract shadows
+    const boxShadow = {};
+
+    // Extract font families
+    const fontFamily = {};
+
+    // Extract font weights
+    const fontWeight = {};
+
+    // Extract font sizes
+    const fontSize = {};
+
+    // Extract letter spacing
+    const letterSpacing = {};
+
+    for (const token of tokens) {
+      const path = token.path;
+      const value = token.$value ?? token.value;
+
+      // Colors
+      if (path[0] === 'color') {
+        if (path[1] === 'background') {
+          surface[path[2]] = value;
+        } else if (path[1] === 'sunset') {
+          sunset[path[2]] = value;
+        } else if (path[1] === 'functional') {
+          const key = path[2].replace('text-', '');
+          functional[key] = value;
+        } else if (path[1] === 'interactive') {
+          const key = path[2].replace('border-', '');
+          interactive[key] = value;
+        } else if (path[1] === 'gradient' && path[2] === 'sunset') {
+          colors['sunset-gradient'] = value;
+        }
+      }
+
+      // Semantic tokens — alias tier
+      if (path[0] === 'semantic') {
+        if (path[1] === 'surface') {
+          semSurface[path[2]] = value;
+        } else if (path[1] === 'text') {
+          semText[path[2]] = value;
+        } else if (path[1] === 'cta') {
+          semCta[path[2]] = value;
+        } else if (path[1] === 'border') {
+          semBorder[path[2]] = value;
+        } else if (path[1] === 'focus') {
+          if (path[2] === 'ring') semFocusRing = value;
+        } else if (path[1] === 'status') {
+          semStatus[path[2]] = value;
+        } else if (path[1] === 'accent' && path.length === 2) {
+          semAccent = value;
+        }
+      }
+
+      // Spacing
+      if (path[0] === 'space') {
+        spacing[path[1]] = value;
+      }
+
+      // Border radius
+      if (path[0] === 'radius') {
+        borderRadius[path[1]] = value;
+      }
+
+      // Shadows
+      if (path[0] === 'shadow') {
+        boxShadow[path[1]] = value;
+      }
+
+      // Font families
+      if (path[0] === 'font' && path[1] === 'family') {
+        fontFamily[path[2]] = value;
+      }
+
+      // Font weights
+      if (path[0] === 'font' && path[1] === 'weight') {
+        fontWeight[path[2]] = value;
+      }
+
+      // Font sizes
+      if (path[0] === 'font' && path[1] === 'size') {
+        fontSize[path[2]] = value;
+      }
+
+      // Letter spacing
+      if (path[0] === 'font' && path[1] === 'tracking') {
+        letterSpacing[path[2]] = value;
+      }
+    }
+
+    // Assemble the Tailwind theme extension
+    // Raw tokens stay available (imajin-*, surface-*, etc) for use INSIDE packages/ui only.
+    // Semantic tokens (accent, cta-*, surface-1/2/3, text-heading/body/quiet, border-*, focus-ring,
+    // status-*) are what app code and primitives should use.
+    const theme = {
+      colors: {
+        // --- Raw tokens (use only inside packages/ui primitives) ---
+        imajin: sunset,
+        surface,
+        ...functional,
+        interactive,
+        ...colors,
+        // --- Semantic tokens (use everywhere else) ---
+        ...(semAccent ? { accent: semAccent } : {}),
+        'cta-primary': semCta.primary,
+        'cta-secondary': semCta.secondary,
+        'surface-1': semSurface['1'],
+        'surface-2': semSurface['2'],
+        'surface-3': semSurface['3'],
+        'surface-input': semSurface.input,
+        'text-heading': semText.heading,
+        'text-body': semText.body,
+        'text-quiet': semText.quiet,
+        'text-on-accent': semText['on-accent'],
+        'border-subtle': semBorder.subtle,
+        'border-strong': semBorder.strong,
+        'border-input-field': semBorder.input,
+        'border-nav': semBorder.nav,
+        ...(semFocusRing ? { 'focus-ring': semFocusRing } : {}),
+        'status-success': semStatus.success,
+        'status-warning': semStatus.warning,
+        'status-error': semStatus.error,
+        'status-info': semStatus.info,
+      },
+      spacing,
+      borderRadius,
+      boxShadow,
+      fontFamily,
+      fontWeight,
+      fontSize,
+      letterSpacing,
+    };
+
+    // Serialize to JS — quote keys with special chars, keep clean identifiers unquoted
+    function serialize(value, indent = 2) {
+      const pad = ' '.repeat(indent);
+      if (Array.isArray(value)) {
+        const items = value.map((v) => serialize(v, indent + 2)).join(', ');
+        return `[${items}]`;
+      }
+      if (typeof value === 'object' && value !== null) {
+        const entries = Object.entries(value).map(([k, v]) => {
+          const key = /^[a-zA-Z_$][a-zA-Z0-9_$]*$/.test(k) ? k : `'${k}'`;
+          return `${pad}${key}: ${serialize(v, indent + 2)}`;
+        });
+        return `{\n${entries.join(',\n')}\n${' '.repeat(indent - 2)}}`;
+      }
+      if (typeof value === 'string') {
+        return `'${value.replace(/'/g, "\\'")}'`;
+      }
+      return String(value);
+    }
+
+    const jsString = serialize(theme, 2);
+    return `/** @type {import('tailwindcss').Config['theme']['extend']} */\nmodule.exports = ${jsString};\n`;
+  },
+});
+
+await sd.buildAllPlatforms();
+console.log('✓ Built tokens to dist/');

package/dist/tailwind.js

@@ -0,0 +1,96 @@
+/** @type {import('tailwindcss').Config['theme']['extend']} */
+module.exports = {
+  colors: {
+    imajin: {
+      purple: '#8b5cf6',
+      blue: '#6366f1',
+      red: '#ef4444',
+      orange: '#f97316'
+    },
+    surface: {
+      base: '#0a0a0f',
+      surface: '#12121a',
+      elevated: '#1a1a26',
+      input: '#15151f'
+    },
+    primary: '#f0f0f5',
+    secondary: '#9393a8',
+    muted: '#5a5a72',
+    success: '#22c55e',
+    warning: '#eab308',
+    error: '#ef4444',
+    info: '#6366f1',
+    interactive: {
+      light: 'rgba(255, 255, 255, 0.1)',
+      'light-hover': 'rgba(255, 255, 255, 0.2)',
+      input: 'rgba(255, 255, 255, 0.12)',
+      secondary: 'rgba(255, 255, 255, 0.15)',
+      nav: 'rgba(255, 255, 255, 0.08)',
+      'scrollbar-thumb': 'rgba(139, 92, 246, 0.3)'
+    },
+    'sunset-gradient': 'linear-gradient(135deg, #8b5cf6, #6366f1, #ef4444, #f97316)',
+    accent: '#f97316',
+    'cta-primary': 'linear-gradient(135deg, #8b5cf6, #6366f1, #ef4444, #f97316)',
+    'cta-secondary': '#1a1a26',
+    'surface-1': '#0a0a0f',
+    'surface-2': '#12121a',
+    'surface-3': '#1a1a26',
+    'surface-input': '#15151f',
+    'text-heading': '#f0f0f5',
+    'text-body': '#9393a8',
+    'text-quiet': '#5a5a72',
+    'text-on-accent': '#f0f0f5',
+    'border-subtle': 'rgba(255, 255, 255, 0.1)',
+    'border-strong': 'rgba(255, 255, 255, 0.2)',
+    'border-input-field': 'rgba(255, 255, 255, 0.12)',
+    'border-nav': 'rgba(255, 255, 255, 0.08)',
+    'focus-ring': '#8b5cf6',
+    'status-success': '#22c55e',
+    'status-warning': '#eab308',
+    'status-error': '#ef4444',
+    'status-info': '#6366f1'
+  },
+  spacing: {
+    '1': '4px',
+    '2': '8px',
+    '3': '12px',
+    '4': '16px',
+    '6': '24px',
+    '8': '32px',
+    '12': '48px',
+    '16': '64px'
+  },
+  borderRadius: {
+    none: '0'
+  },
+  boxShadow: {
+    glow: '0 0 20px rgba(139, 92, 246, 0.15)'
+  },
+  fontFamily: {
+    mono: ['\'JetBrains Mono\'', 'ui-monospace', 'SFMono-Regular', 'Menlo', 'Monaco', 'Consolas', 'Liberation Mono', 'Courier New', 'monospace'],
+    sans: ['\'Inter\'', 'ui-sans-serif', 'system-ui', '-apple-system', 'BlinkMacSystemFont', 'Segoe UI', 'Roboto', 'Helvetica Neue', 'Arial', 'sans-serif']
+  },
+  fontWeight: {
+    regular: 400,
+    medium: 500,
+    bold: 700
+  },
+  fontSize: {
+    label: '0.6875rem',
+    nav: '0.8125rem',
+    body: '0.875rem',
+    'heading-sm': '1.5rem',
+    'heading-md': '2rem',
+    'heading-lg': '2.5rem',
+    'hero-sm': '2.5rem',
+    'hero-md': '3rem',
+    'hero-lg': '4rem'
+  },
+  letterSpacing: {
+    tight: '-0.03em',
+    heading: '-0.02em',
+    normal: '0',
+    nav: '0.02em',
+    label: '0.05em'
+  }
+};

package/dist/variables.css

@@ -0,0 +1,78 @@
+/**
+ * Do not edit directly, this file was auto-generated.
+ */
+
+:root {
+  --color-background-base: #0a0a0f; /** Page background, app shell */
+  --color-background-surface: #12121a; /** Cards, panels, modals */
+  --color-background-elevated: #1a1a26; /** Hover states, raised elements */
+  --color-background-input: #15151f; /** Form fields, text inputs */
+  --color-sunset-purple: #8b5cf6; /** Gradient start — protocol, network, deep infrastructure */
+  --color-sunset-blue: #6366f1; /** Gradient mid-left — identity, trust, verification */
+  --color-sunset-red: #ef4444; /** Gradient mid-right — settlement, payments, action */
+  --color-sunset-orange: #f97316; /** Gradient end — community, presence, warmth */
+  --color-functional-text-primary: #f0f0f5; /** Primary text */
+  --color-functional-text-secondary: #9393a8; /** Secondary text, labels */
+  --color-functional-text-muted: #5a5a72; /** Placeholders, disabled */
+  --color-functional-success: #22c55e; /** Confirmations, positive states */
+  --color-functional-warning: #eab308; /** Warnings, caution */
+  --color-functional-error: #ef4444; /** Errors, destructive actions */
+  --color-functional-info: #6366f1; /** Informational */
+  --color-interactive-border-light: rgba(255, 255, 255, 0.1); /** Card borders */
+  --color-interactive-border-light-hover: rgba(255, 255, 255, 0.2); /** Card border hover */
+  --color-interactive-border-input: rgba(255, 255, 255, 0.12); /** Input borders */
+  --color-interactive-border-secondary: rgba(255, 255, 255, 0.15); /** Secondary button border */
+  --color-interactive-border-nav: rgba(255, 255, 255, 0.08); /** Navigation border */
+  --color-interactive-scrollbar-thumb: rgba(139, 92, 246, 0.3); /** Scrollbar thumb (purple) */
+  --color-gradient-sunset: linear-gradient(135deg, #8b5cf6, #6366f1, #ef4444, #f97316); /** The Imajin sunset gradient */
+  --space-1: 4px; /** Tight gaps (icon-to-text) */
+  --space-2: 8px; /** Inline spacing, small gaps */
+  --space-3: 12px; /** Input padding, list items */
+  --space-4: 16px; /** Card padding, section gaps */
+  --space-6: 24px; /** Between components */
+  --space-8: 32px; /** Section separators */
+  --space-12: 48px; /** Page sections */
+  --space-16: 64px; /** Hero spacing, major sections */
+  --radius-none: 0px; /** Everything */
+  --shadow-glow: 0 0 20px rgba(139, 92, 246, 0.15); /** Accent glow on focus/active (purple base) */
+  --font-family-mono: 'JetBrains Mono', ui-monospace, SFMono-Regular, Menlo, Monaco, Consolas, 'Liberation Mono', 'Courier New', monospace; /** Headings, labels, navigation, data, code */
+  --font-family-sans: 'Inter', ui-sans-serif, system-ui, -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, 'Helvetica Neue', Arial, sans-serif; /** Body text, long-form reading */
+  --font-weight-regular: 400; /** Body, data, code */
+  --font-weight-medium: 500; /** Labels, nav items */
+  --font-weight-bold: 700; /** Headings, hero/display */
+  --font-size-label: 0.6875rem; /** Labels (uppercase monospace) */
+  --font-size-nav: 0.8125rem; /** Nav items */
+  --font-size-body: 0.875rem; /** Body text */
+  --font-size-heading-sm: 1.5rem; /** Small headings */
+  --font-size-heading-md: 2rem; /** Medium headings */
+  --font-size-heading-lg: 2.5rem; /** Large headings */
+  --font-size-hero-sm: 2.5rem; /** Hero small */
+  --font-size-hero-md: 3rem; /** Hero medium */
+  --font-size-hero-lg: 4rem; /** Hero large */
+  --font-tracking-tight: -0.03em; /** Hero/display */
+  --font-tracking-heading: -0.02em; /** Headings */
+  --font-tracking-normal: 0px; /** Body, data, code */
+  --font-tracking-nav: 0.02em; /** Nav items */
+  --font-tracking-label: 0.05em; /** Labels (uppercase) */
+  --semantic-surface-1: var(--color-background-base); /** Page background, app shell */
+  --semantic-surface-2: var(--color-background-surface); /** Cards, panels, modals */
+  --semantic-surface-3: var(--color-background-elevated); /** Hover states, raised elements */
+  --semantic-surface-input: var(--color-background-input); /** Form fields */
+  --semantic-text-heading: var(--color-functional-text-primary); /** Headings, primary content */
+  --semantic-text-body: var(--color-functional-text-secondary); /** Body text, labels */
+  --semantic-text-quiet: var(--color-functional-text-muted); /** Placeholders, disabled, muted hints */
+  --semantic-text-on-accent: var(--color-functional-text-primary); /** Text on accent/CTA backgrounds */
+  --semantic-accent: var(--color-sunset-orange); /** The brand accent. Change this one token to rebrand. Currently warm/orange. */
+  --semantic-cta-primary: var(--color-gradient-sunset); /** Primary CTA — sunset gradient */
+  --semantic-cta-secondary: var(--color-background-elevated); /** Secondary CTA — quiet surface */
+  --semantic-border-subtle: var(--color-interactive-border-light); /** Card and panel borders */
+  --semantic-border-strong: var(--color-interactive-border-light-hover); /** Border on hover or emphasis */
+  --semantic-border-input: var(--color-interactive-border-input); /** Form field borders */
+  --semantic-border-nav: var(--color-interactive-border-nav); /** Navigation dividers */
+  --semantic-focus-ring: var(--color-sunset-purple); /** Focus ring color */
+  --semantic-focus-glow: var(--shadow-glow); /** Subtle purple glow on focus */
+  --semantic-status-success: var(--color-functional-success);
+  --semantic-status-warning: var(--color-functional-warning);
+  --semantic-status-error: var(--color-functional-error);
+  --semantic-status-info: var(--color-functional-info);
+}

package/package.json

@@ -0,0 +1,22 @@
+{
+  "name": "@ima-jin/tokens",
+  "version": "1.0.0",
+  "description": "Imajin design tokens — DTCG format, built with Style Dictionary v4",
+  "main": "./dist/tailwind.js",
+  "exports": {
+    ".": "./dist/tailwind.js",
+    "./tailwind": "./dist/tailwind.js",
+    "./dist/tailwind.js": "./dist/tailwind.js",
+    "./css": "./dist/variables.css",
+    "./variables.css": "./dist/variables.css",
+    "./dist/variables.css": "./dist/variables.css"
+  },
+  "files": [
+    "dist/",
+    "tokens.json",
+    "build.mjs"
+  ],
+  "publishConfig": {
+    "access": "public"
+  }
+}

package/tokens.json

@@ -0,0 +1,232 @@
+{
+  "color": {
+    "$description": "Imajin color tokens — sunset on black",
+    "background": {
+      "base": {
+        "$value": "#0a0a0f",
+        "$type": "color",
+        "$description": "Page background, app shell"
+      },
+      "surface": {
+        "$value": "#12121a",
+        "$type": "color",
+        "$description": "Cards, panels, modals"
+      },
+      "elevated": {
+        "$value": "#1a1a26",
+        "$type": "color",
+        "$description": "Hover states, raised elements"
+      },
+      "input": {
+        "$value": "#15151f",
+        "$type": "color",
+        "$description": "Form fields, text inputs"
+      }
+    },
+    "sunset": {
+      "purple": {
+        "$value": "#8b5cf6",
+        "$type": "color",
+        "$description": "Gradient start — protocol, network, deep infrastructure"
+      },
+      "blue": {
+        "$value": "#6366f1",
+        "$type": "color",
+        "$description": "Gradient mid-left — identity, trust, verification"
+      },
+      "red": {
+        "$value": "#ef4444",
+        "$type": "color",
+        "$description": "Gradient mid-right — settlement, payments, action"
+      },
+      "orange": {
+        "$value": "#f97316",
+        "$type": "color",
+        "$description": "Gradient end — community, presence, warmth"
+      }
+    },
+    "functional": {
+      "text-primary": {
+        "$value": "#f0f0f5",
+        "$type": "color",
+        "$description": "Primary text"
+      },
+      "text-secondary": {
+        "$value": "#9393a8",
+        "$type": "color",
+        "$description": "Secondary text, labels"
+      },
+      "text-muted": {
+        "$value": "#5a5a72",
+        "$type": "color",
+        "$description": "Placeholders, disabled"
+      },
+      "success": {
+        "$value": "#22c55e",
+        "$type": "color",
+        "$description": "Confirmations, positive states"
+      },
+      "warning": {
+        "$value": "#eab308",
+        "$type": "color",
+        "$description": "Warnings, caution"
+      },
+      "error": {
+        "$value": "#ef4444",
+        "$type": "color",
+        "$description": "Errors, destructive actions"
+      },
+      "info": {
+        "$value": "#6366f1",
+        "$type": "color",
+        "$description": "Informational"
+      }
+    },
+    "interactive": {
+      "border-light": {
+        "$value": "rgba(255, 255, 255, 0.1)",
+        "$type": "color",
+        "$description": "Card borders"
+      },
+      "border-light-hover": {
+        "$value": "rgba(255, 255, 255, 0.2)",
+        "$type": "color",
+        "$description": "Card border hover"
+      },
+      "border-input": {
+        "$value": "rgba(255, 255, 255, 0.12)",
+        "$type": "color",
+        "$description": "Input borders"
+      },
+      "border-secondary": {
+        "$value": "rgba(255, 255, 255, 0.15)",
+        "$type": "color",
+        "$description": "Secondary button border"
+      },
+      "border-nav": {
+        "$value": "rgba(255, 255, 255, 0.08)",
+        "$type": "color",
+        "$description": "Navigation border"
+      },
+      "scrollbar-thumb": {
+        "$value": "rgba(139, 92, 246, 0.3)",
+        "$type": "color",
+        "$description": "Scrollbar thumb (purple)"
+      }
+    },
+    "gradient": {
+      "sunset": {
+        "$value": "linear-gradient(135deg, #8b5cf6, #6366f1, #ef4444, #f97316)",
+        "$type": "other",
+        "$description": "The Imajin sunset gradient"
+      }
+    }
+  },
+  "space": {
+    "$description": "4px base unit spacing system",
+    "1": { "$value": "4px", "$type": "dimension", "$description": "Tight gaps (icon-to-text)" },
+    "2": { "$value": "8px", "$type": "dimension", "$description": "Inline spacing, small gaps" },
+    "3": { "$value": "12px", "$type": "dimension", "$description": "Input padding, list items" },
+    "4": { "$value": "16px", "$type": "dimension", "$description": "Card padding, section gaps" },
+    "6": { "$value": "24px", "$type": "dimension", "$description": "Between components" },
+    "8": { "$value": "32px", "$type": "dimension", "$description": "Section separators" },
+    "12": { "$value": "48px", "$type": "dimension", "$description": "Page sections" },
+    "16": { "$value": "64px", "$type": "dimension", "$description": "Hero spacing, major sections" }
+  },
+  "radius": {
+    "$description": "Border radius — zero everywhere",
+    "none": { "$value": "0", "$type": "dimension", "$description": "Everything" }
+  },
+  "shadow": {
+    "$description": "Shadows — almost none",
+    "glow": {
+      "$value": "0 0 20px rgba(139, 92, 246, 0.15)",
+      "$type": "other",
+      "$description": "Accent glow on focus/active (purple base)"
+    }
+  },
+  "font": {
+    "$description": "Typography tokens",
+    "family": {
+      "mono": {
+        "$value": ["'JetBrains Mono'", "ui-monospace", "SFMono-Regular", "Menlo", "Monaco", "Consolas", "Liberation Mono", "Courier New", "monospace"],
+        "$type": "fontFamily",
+        "$description": "Headings, labels, navigation, data, code"
+      },
+      "sans": {
+        "$value": ["'Inter'", "ui-sans-serif", "system-ui", "-apple-system", "BlinkMacSystemFont", "Segoe UI", "Roboto", "Helvetica Neue", "Arial", "sans-serif"],
+        "$type": "fontFamily",
+        "$description": "Body text, long-form reading"
+      }
+    },
+    "weight": {
+      "regular": { "$value": 400, "$type": "fontWeight", "$description": "Body, data, code" },
+      "medium": { "$value": 500, "$type": "fontWeight", "$description": "Labels, nav items" },
+      "bold": { "$value": 700, "$type": "fontWeight", "$description": "Headings, hero/display" }
+    },
+    "size": {
+      "label": { "$value": "0.6875rem", "$type": "dimension", "$description": "Labels (uppercase monospace)" },
+      "nav": { "$value": "0.8125rem", "$type": "dimension", "$description": "Nav items" },
+      "body": { "$value": "0.875rem", "$type": "dimension", "$description": "Body text" },
+      "heading-sm": { "$value": "1.5rem", "$type": "dimension", "$description": "Small headings" },
+      "heading-md": { "$value": "2rem", "$type": "dimension", "$description": "Medium headings" },
+      "heading-lg": { "$value": "2.5rem", "$type": "dimension", "$description": "Large headings" },
+      "hero-sm": { "$value": "2.5rem", "$type": "dimension", "$description": "Hero small" },
+      "hero-md": { "$value": "3rem", "$type": "dimension", "$description": "Hero medium" },
+      "hero-lg": { "$value": "4rem", "$type": "dimension", "$description": "Hero large" }
+    },
+    "tracking": {
+      "tight": { "$value": "-0.03em", "$type": "dimension", "$description": "Hero/display" },
+      "heading": { "$value": "-0.02em", "$type": "dimension", "$description": "Headings" },
+      "normal": { "$value": "0", "$type": "dimension", "$description": "Body, data, code" },
+      "nav": { "$value": "0.02em", "$type": "dimension", "$description": "Nav items" },
+      "label": { "$value": "0.05em", "$type": "dimension", "$description": "Labels (uppercase)" }
+    }
+  },
+  "semantic": {
+    "$description": "Semantic tokens — role-based aliases for raw colors. App code and UI primitives reference these, NOT the raw tokens. If you change the brand from orange to teal, you change semantic.accent here, not 200 components.",
+    "surface": {
+      "$description": "Layered backgrounds — 1 is page, 2 is cards/panels, 3 is hover/raised, input is form fields",
+      "1": { "$value": "{color.background.base}", "$type": "color", "$description": "Page background, app shell" },
+      "2": { "$value": "{color.background.surface}", "$type": "color", "$description": "Cards, panels, modals" },
+      "3": { "$value": "{color.background.elevated}", "$type": "color", "$description": "Hover states, raised elements" },
+      "input": { "$value": "{color.background.input}", "$type": "color", "$description": "Form fields" }
+    },
+    "text": {
+      "$description": "Text hierarchy — heading, body, quiet (descending prominence)",
+      "heading": { "$value": "{color.functional.text-primary}", "$type": "color", "$description": "Headings, primary content" },
+      "body": { "$value": "{color.functional.text-secondary}", "$type": "color", "$description": "Body text, labels" },
+      "quiet": { "$value": "{color.functional.text-muted}", "$type": "color", "$description": "Placeholders, disabled, muted hints" },
+      "on-accent": { "$value": "{color.functional.text-primary}", "$type": "color", "$description": "Text on accent/CTA backgrounds" }
+    },
+    "accent": {
+      "$description": "The brand accent. Change this one token to rebrand. Currently warm/orange.",
+      "$value": "{color.sunset.orange}",
+      "$type": "color"
+    },
+    "cta": {
+      "$description": "Call-to-action backgrounds — primary uses the brand gradient, secondary is a quiet button surface",
+      "primary": { "$value": "{color.gradient.sunset}", "$type": "other", "$description": "Primary CTA — sunset gradient" },
+      "secondary": { "$value": "{color.background.elevated}", "$type": "color", "$description": "Secondary CTA — quiet surface" }
+    },
+    "border": {
+      "$description": "Border tokens by purpose — subtle for cards, input for forms, focus for active state",
+      "subtle": { "$value": "{color.interactive.border-light}", "$type": "color", "$description": "Card and panel borders" },
+      "strong": { "$value": "{color.interactive.border-light-hover}", "$type": "color", "$description": "Border on hover or emphasis" },
+      "input": { "$value": "{color.interactive.border-input}", "$type": "color", "$description": "Form field borders" },
+      "nav": { "$value": "{color.interactive.border-nav}", "$type": "color", "$description": "Navigation dividers" }
+    },
+    "focus": {
+      "$description": "Focus ring — anchored on purple per DESIGN.md",
+      "ring": { "$value": "{color.sunset.purple}", "$type": "color", "$description": "Focus ring color" },
+      "glow": { "$value": "{shadow.glow}", "$type": "other", "$description": "Subtle purple glow on focus" }
+    },
+    "status": {
+      "$description": "Status colors — same values as functional but named by intent",
+      "success": { "$value": "{color.functional.success}", "$type": "color" },
+      "warning": { "$value": "{color.functional.warning}", "$type": "color" },
+      "error": { "$value": "{color.functional.error}", "$type": "color" },
+      "info": { "$value": "{color.functional.info}", "$type": "color" }
+    }
+  }
+}