figma-code-agent 1.0.0

package/skills/ref-react/SKILL.md

@@ -0,0 +1,222 @@
+---
+name: ref-react
+description: "Reference: Generate a production-grade React/TSX component from Figma node data. Use this skill when the user has Figma design data (JSON node tree, REST API response, or component description) and needs a typed React component with CSS Modules, proper semantics, and accessibility."
+---
+
+@knowledge/design-to-code-layout.md
+@knowledge/design-to-code-visual.md
+@knowledge/design-to-code-typography.md
+@knowledge/design-to-code-assets.md
+@knowledge/design-to-code-semantic.md
+@knowledge/css-strategy.md
+
+## Objective
+
+Generate a complete, production-grade React/TSX component from Figma node data. The output includes a typed function component (`.tsx`) and a companion CSS Modules file (`.module.css`) using the three-layer CSS architecture: Tailwind for layout bones, CSS Custom Properties for design tokens, and CSS Modules for visual skin.
+
+## Input
+
+The user provides Figma design data as `$ARGUMENTS`. This may be:
+
+- Raw Figma REST API JSON (node tree with children, fills, strokes, effects, text properties)
+- Extracted/summarized node properties
+- A description of the Figma component (layer names, layout, colors, typography)
+- A Figma file/node URL (use the REST API knowledge to fetch data if needed)
+
+If the input is insufficient for full generation, ask the user for what is missing. At minimum you need: component structure (parent/child hierarchy), layout mode, and visual properties for each node.
+
+## Process
+
+Follow these steps in order. Each step references the relevant knowledge module for detailed mapping rules.
+
+### Step 1: Analyze Node Tree Structure
+
+Identify the component boundary and internal hierarchy:
+
+- The root node is the component container.
+- Map each child node to its role: structural container, text element, image, icon/vector, interactive element.
+- Identify repeated patterns that suggest list/map rendering.
+- Note any component instances or variants that imply prop-driven rendering.
+
+### Step 2: Determine Semantic HTML Elements
+
+Consult `knowledge/design-to-code-semantic.md`:
+
+- Match layer names against semantic tag heuristics (header, nav, button, h1-h6, p, img, section, article, footer, etc.).
+- Enforce heading hierarchy: single `<h1>`, sequential levels, no headings inside interactive elements.
+- Detect interactive elements from names (button, link, input, form, checkbox, toggle, etc.).
+- Map structural landmarks (header, nav, footer, main, aside, section).
+- Default to `<div>` only when no semantic match is found.
+
+### Step 3: Extract Layout Properties
+
+Consult `knowledge/design-to-code-layout.md`:
+
+- For Auto Layout containers: map `layoutMode`, alignment, gap, padding, wrap, constraints.
+- For each child: determine sizing mode on primary and counter axes.
+- **CRITICAL**: FILL on primary axis requires BOTH `flex-grow: 1` AND `flex-basis: 0`.
+- FILL on counter axis with max constraint uses `width: 100%`/`height: 100%`, not `align-self: stretch`.
+- Handle absolute children with `position: relative` on parent and constraint-based offsets on child.
+- For GROUP/legacy frames: absolute positioning with coordinate adjustments.
+
+### Step 4: Extract Visual Properties
+
+Consult `knowledge/design-to-code-visual.md`:
+
+- **Fills**: solid colors -> `background-color`, gradients -> `background-image`, images -> handled in Step 6.
+- **Strokes**: INSIDE alignment -> `box-shadow: inset 0 0 0 {width}px {color}` (NOT `border`). CENTER/OUTSIDE -> standard `border` or `outline`.
+- **Effects**: drop shadows -> `box-shadow`, inner shadows -> `box-shadow: inset`, layer blur -> `filter: blur()`, background blur -> `backdrop-filter: blur()`.
+- **Corner radius**: uniform -> `border-radius`, per-corner -> `border-radius: TL TR BR BL` with shorthand optimization.
+- **Opacity**: node-level -> CSS `opacity`, fill-level -> embedded in color alpha. Never double-apply.
+- **Gradients**: convert angle with `90 - figmaAngle` for CSS. Map gradient stops with position percentages.
+- **Variable bindings**: resolve to `var(--token-name)` with pixel fallbacks for external library variables.
+
+### Step 5: Extract Typography
+
+Consult `knowledge/design-to-code-typography.md`:
+
+- Map font family, weight, size, and style.
+- **Line height**: ALWAYS use unitless ratio (`lineHeightPx / fontSize`). Never use px or % for line-height.
+- Letter spacing: convert from Figma percentage to CSS `em` value.
+- Text decoration, text transform, text alignment.
+- Handle styled segments (mixed fonts/weights/colors within one text node) as `<span>` elements.
+- Text auto-resize modes interact with layout sizing -- resolve the interaction.
+
+### Step 6: Handle Assets
+
+Consult `knowledge/design-to-code-assets.md`:
+
+- **Vector containers** (nodes with only vector/boolean children and no Auto Layout): export as inline SVG or `<img>` referencing an SVG file.
+- **Images**: use `<img>` with `alt` text derived from layer name. Export at **2x minimum** for retina displays.
+- **Decision tree**: If the vector is simple and needs color control -> inline SVG. If complex or decorative -> `<img src="asset.svg">`.
+- Deduplicate identical images (same `imageHash`).
+
+### Step 7: Generate CSS Using Three-Layer Architecture
+
+Consult `knowledge/css-strategy.md`:
+
+**Layer 1 -- Tailwind (layout bones):**
+Apply Tailwind utility classes directly in JSX for:
+- Flexbox: `flex`, `flex-row`, `flex-col`, `items-center`, `justify-between`
+- Spacing: `gap-4`, `p-6`, `px-4`, `py-2`
+- Sizing: `w-full`, `h-auto`, `max-w-lg`, `flex-1`
+- Positioning: `relative`, `absolute`, `top-0`, `right-0`
+- Responsive: `md:flex-row`, `lg:gap-8`
+
+**Layer 2 -- CSS Custom Properties (design tokens):**
+Define in the CSS Module file or a shared `tokens.css`:
+```css
+/* Token references consumed by Layer 3 */
+color: var(--color-primary);
+font-size: var(--font-size-lg);
+border-radius: var(--radius-md);
+```
+
+**Layer 3 -- CSS Modules (visual skin):**
+Component-specific visual styles in `.module.css`:
+```css
+.card {
+  background-color: var(--color-surface);
+  box-shadow: inset 0 0 0 1px var(--color-border);  /* INSIDE stroke */
+  border-radius: var(--radius-lg);
+}
+
+.card__title {
+  color: var(--color-text-primary);
+  font-family: var(--font-heading);
+  font-size: var(--font-size-xl);
+  line-height: 1.3;  /* unitless ratio */
+}
+```
+
+### Step 8: Generate BEM Class Names
+
+Consult `knowledge/design-to-code-semantic.md`:
+
+- Block name from the root component (kebab-case from layer name).
+- Element names with double underscore: `block__element`.
+- **NEVER nest deeper than one level**: `block__element` is valid, `block__element__sub` is NOT. Flatten to `block__sub` or use a modifier.
+- Modifier with double dash: `block__element--modifier`.
+- Deduplicate class names within the component tree.
+
+### Step 9: Generate TypeScript Interfaces
+
+Define prop interfaces for the component:
+
+- Extract variant-driven props from Figma component properties (boolean, text, instance swap).
+- Text content nodes become string props.
+- Image nodes become `src`/`alt` prop pairs.
+- Interactive elements get event handler props (`onClick`, `onSubmit`, etc.).
+- Use descriptive names, not Figma layer names directly.
+
+### Step 10: Assemble React Component
+
+Combine all outputs into a complete `.tsx` file:
+
+```tsx
+import React from 'react';
+import styles from './ComponentName.module.css';
+
+interface ComponentNameProps {
+  title: string;
+  description?: string;
+  onAction?: () => void;
+}
+
+export function ComponentName({ title, description, onAction }: ComponentNameProps) {
+  return (
+    <section className={`flex flex-col gap-4 p-6 ${styles.card}`}>
+      <h2 className={`${styles.card__title}`}>
+        {title}
+      </h2>
+      {description && (
+        <p className={`${styles.card__description}`}>
+          {description}
+        </p>
+      )}
+      <button
+        className={`flex items-center justify-center ${styles.card__action}`}
+        onClick={onAction}
+        type="button"
+      >
+        Get Started
+      </button>
+    </section>
+  );
+}
+```
+
+## Output
+
+Generate two files:
+
+### 1. `ComponentName.tsx`
+
+- Named export (not default export) with PascalCase component name.
+- TypeScript interface for props.
+- Semantic HTML elements with Tailwind layout classes + CSS Module visual classes.
+- Proper ARIA attributes where needed (`aria-label`, `role`, `alt`).
+- Inline SVGs for simple vectors, `<img>` for complex assets/images.
+
+### 2. `ComponentName.module.css`
+
+- BEM class names with flat hierarchy.
+- Visual properties only (colors, backgrounds, borders/shadows, effects, typography skin).
+- CSS Custom Property references for design tokens (`var(--token-name)`).
+- Responsive overrides via media queries if multi-frame breakpoints detected.
+- Comments showing Figma property origin for maintainability.
+
+### Critical Rules Checklist
+
+Before returning the component, verify:
+
+- [ ] INSIDE strokes use `box-shadow: inset`, not `border`
+- [ ] Gradient angles use `90 - figmaAngle` conversion
+- [ ] Line heights are unitless ratios (`lineHeightPx / fontSize`)
+- [ ] Images export at 2x minimum for retina
+- [ ] BEM nesting is flat: never `block__element__sub`
+- [ ] FILL on primary axis has BOTH `flex-grow: 1` AND `flex-basis: 0`
+- [ ] Layout is in Tailwind classes; visual skin is in CSS Modules
+- [ ] No hardcoded color values -- use CSS Custom Properties for anything that could be a token
+- [ ] Semantic HTML tags used where layer names match heuristics
+- [ ] ARIA attributes present on interactive and image elements

package/skills/ref-tokens/SKILL.md

@@ -0,0 +1,347 @@
+---
+name: ref-tokens
+description: "Reference: Extract design tokens from Figma Variables, styles, or node data and generate CSS Custom Properties + Tailwind config. Use this skill when the user has Figma file data (Variables API response, style definitions, or node tree) and needs a structured token output with semantic naming, mode-aware rendering, and CSS/Tailwind integration."
+---
+
+@knowledge/design-tokens.md
+@knowledge/design-tokens-variables.md
+@knowledge/figma-api-variables.md
+@knowledge/css-strategy.md
+
+## Objective
+
+Extract design tokens from Figma data and generate production-grade CSS Custom Properties (`:root` block with mode-aware overrides), optional SCSS variables, and a Tailwind `theme.extend` configuration snippet. The skill handles the full token pipeline: source identification, variable resolution, threshold-based promotion, semantic naming (HSL color classification, spacing scale detection), and multi-format rendering.
+
+## Input
+
+The user provides Figma token source data as `$ARGUMENTS`. This may be:
+
+- **Variables API response** -- JSON from `GET /v1/files/:key/variables/local` containing variables and collections with `valuesByMode`
+- **Plugin API variable data** -- Extracted variable collections from `figma.variables.getLocalVariableCollectionsAsync()`
+- **Node tree with bound variables** -- Figma REST API node data containing `boundVariables` on fills, strokes, layout properties, and text
+- **Style definitions** -- Published styles from the file (colors, text styles, effects)
+- **Raw node tree** -- Full node subtree for heuristic-based token extraction (file traversal fallback)
+- **Plain language description** -- Description of the design system's colors, spacing, typography, etc.
+
+If the input is insufficient, ask the user for clarification. At minimum you need either: (a) variable collections with values, or (b) a node tree with enough nodes to detect repeated values for promotion.
+
+## Process
+
+Follow these steps in order. Consult the referenced knowledge modules for all mapping rules, naming conventions, and edge cases.
+
+### Step 1: Identify Token Source and Access Path
+
+Determine which token extraction path to use based on the input data. Consult `knowledge/figma-api-variables.md` for access requirements and `knowledge/design-tokens-variables.md` for the source priority chain.
+
+**Priority order:**
+
+1. **Variables API** (best) -- Structured, multi-mode, scoped. Requires Enterprise org full member access with `file_variables:read` scope. If the user provides Variables API JSON, use this path.
+2. **Published styles** -- Good for non-Enterprise plans. Limited to published content.
+3. **File tree traversal** -- Fallback for any plan. Heuristic-based extraction from node properties. Uses threshold promotion.
+4. **Plugin API** -- When running inside a Figma plugin context. Access via `figma.variables.getLocalVariableCollectionsAsync()`.
+
+**If the user does not have Enterprise access**, inform them that the Variables API path is unavailable and proceed with file traversal + threshold promotion. Do NOT block on missing Variables access -- always provide a working fallback path.
+
+### Step 2: Extract Raw Token Values
+
+Based on the identified source path:
+
+**Variables API path:**
+- Parse variable collections and their modes
+- For each variable: read `resolvedType` (COLOR, FLOAT, STRING), `valuesByMode`, `scopes`
+- Classify each collection's modes using mode name detection (see Step 3)
+- Distinguish local vs remote variables using the `remote` boolean field
+- Follow alias chains: if a variable's value is a `VariableAlias`, resolve to the terminal value for each mode
+
+**File traversal path:**
+- Traverse the node tree recursively
+- Collect values from five domains, tracking usage count per unique value:
+  - **Colors**: solid fills (`fill.color`), strokes (`stroke.color`), shadow effect colors
+  - **Spacing**: `itemSpacing` (gap), `paddingTop/Right/Bottom/Left`, margins
+  - **Typography**: font families, font sizes, font weights, line heights
+  - **Effects**: box shadows (drop shadow, inner shadow), border radii
+  - **Breakpoints**: frame dimensions that suggest responsive breakpoints
+- Normalize values before comparison (lowercase hex, whitespace-normalize rgba)
+- Collect any `boundVariables` references found on nodes (these get priority in Step 6)
+
+### Step 3: Detect Modes (Variables Path Only)
+
+Consult `knowledge/design-tokens-variables.md` Section 4 for mode detection rules.
+
+Classify each collection's modes as one of:
+- **Theme modes** -- Mode names like "Light", "Dark", "Brand A", "Brand B"
+- **Breakpoint modes** -- Mode names like "Mobile", "Tablet", "Desktop", "sm", "md", "lg"
+- **Unknown** -- Cannot classify; treat as theme modes by default
+
+**Default mode selection:**
+- Theme modes: "Light" is default (base `:root`)
+- Breakpoint modes: smallest breakpoint (typically "Mobile") is default (mobile-first)
+- Unknown: first mode in the collection is default
+
+### Step 4: Promote Values to Tokens
+
+Consult `knowledge/design-tokens.md` Section 1 (Stage 2: PROMOTE).
+
+**Threshold-based promotion (file traversal path):**
+- Values used 2 or more times are promoted to CSS Custom Properties
+- Single-use values remain inline in component CSS (not tokenized)
+- The threshold of 2 is the default; adjust if the user specifies differently
+
+**Variables path:**
+- All Figma Variables are automatically promoted (they are explicit designer-curated tokens)
+- No threshold needed -- variables are tokens by definition
+
+**Priority when both exist:**
+- Bound variable references on a property always take priority
+- Auto-detected tokens fill gaps where no variable binding exists
+- If a variable and an auto-detected token produce the same CSS value, the variable wins
+
+### Step 5: Assign Semantic Names
+
+Consult `knowledge/design-tokens.md` Sections 3-6 for naming rules per category.
+
+**Token naming convention:** `--{category}-{name}-{variant}`
+
+**Colors (HSL-based classification):**
+1. Convert to HSL (Hue 0-360, Saturation 0-100, Lightness 0-100)
+2. Classify:
+   - Saturation < 10% --> `neutral` with lightness scale (100-900)
+   - Hue 0-20 or 340-360 --> `error`
+   - Hue 30-60 --> `warning`
+   - Hue 90-150 --> `success`
+   - Most-used saturated color --> `primary`
+   - Second most-used saturated --> `secondary`
+   - Remaining --> `accent`, `accent-2`, etc.
+3. Neutral lightness scale: `step = Math.round((1 - lightness / 100) * 8 + 1) * 100` clamped to [100, 900]
+4. Output format: HSL values for easy manipulation: `--color-primary: hsl(220, 90%, 56%)`
+
+**If Variables API is the source**, use the variable's own path as the name base (e.g., `color/primary/500` --> `--color-primary-500`). HSL classification is only needed for file traversal path where names must be inferred.
+
+**Spacing (4px base unit detection):**
+1. Detect the base unit from collected spacing values (typically 4px or 8px)
+2. Express each spacing value as a multiple of the base: `value / baseUnit`
+3. Name pattern: `--spacing-{multiplier}` (e.g., `--spacing-1` = 4px, `--spacing-4` = 16px)
+4. If a clear base unit cannot be detected, use pixel-based naming: `--spacing-4` = 4px, `--spacing-16` = 16px
+
+**Typography:**
+- Font families: `--font-primary`, `--font-secondary`, `--font-mono`
+- Font sizes: `--text-xs`, `--text-sm`, `--text-base`, `--text-lg`, `--text-xl`, `--text-2xl`, etc. (match to nearest standard scale)
+- Font weights: `--font-regular` (400), `--font-medium` (500), `--font-semibold` (600), `--font-bold` (700)
+
+**Effects:**
+- Shadows: `--shadow-sm`, `--shadow-md`, `--shadow-lg` (by blur radius / spread scale)
+- Border radii: `--radius-sm`, `--radius-md`, `--radius-lg`, `--radius-full`
+
+**Name deduplication:**
+- If two tokens would get the same name, append a numeric suffix: `--color-accent`, `--color-accent-2`
+- For Variables API tokens, the variable path provides unique names naturally
+
+### Step 6: Render CSS Custom Properties
+
+Consult `knowledge/design-tokens-variables.md` Sections 5-7 for mode-aware rendering and `knowledge/css-strategy.md` for where tokens fit in the three-layer architecture.
+
+**Base `:root` block (default mode values):**
+
+```css
+/* ========================================
+   Design Tokens (Layer 2)
+   ======================================== */
+
+:root {
+  /* Colors */
+  --color-primary: hsl(220, 90%, 56%);
+  --color-secondary: hsl(258, 88%, 66%);
+  --color-neutral-100: hsl(0, 0%, 96%);
+  --color-neutral-900: hsl(0, 0%, 9%);
+  --color-error: hsl(0, 84%, 60%);
+  --color-success: hsl(142, 71%, 45%);
+
+  /* Spacing (4px base) */
+  --spacing-1: 0.25rem;   /* 4px */
+  --spacing-2: 0.5rem;    /* 8px */
+  --spacing-4: 1rem;      /* 16px */
+  --spacing-6: 1.5rem;    /* 24px */
+  --spacing-8: 2rem;      /* 32px */
+
+  /* Typography */
+  --font-primary: 'Inter', sans-serif;
+  --font-heading: 'Instrument Sans', sans-serif;
+  --text-sm: 0.875rem;    /* 14px */
+  --text-base: 1rem;      /* 16px */
+  --text-lg: 1.125rem;    /* 18px */
+  --text-xl: 1.5rem;      /* 24px */
+
+  /* Effects */
+  --radius-sm: 0.25rem;   /* 4px */
+  --radius-md: 0.5rem;    /* 8px */
+  --radius-lg: 1rem;      /* 16px */
+  --shadow-sm: 0 1px 2px rgba(0, 0, 0, 0.05);
+  --shadow-md: 0 4px 6px rgba(0, 0, 0, 0.1);
+}
+```
+
+**Theme mode overrides:**
+
+```css
+/* Dark theme */
+@media (prefers-color-scheme: dark) {
+  :root {
+    --color-primary: hsl(220, 90%, 65%);
+    --color-neutral-100: hsl(0, 0%, 15%);
+    --color-neutral-900: hsl(0, 0%, 95%);
+    /* Only tokens that change in dark mode */
+  }
+}
+
+/* Class-based theme (alternative/additional) */
+[data-theme="dark"] {
+  --color-primary: hsl(220, 90%, 65%);
+  --color-neutral-100: hsl(0, 0%, 15%);
+  --color-neutral-900: hsl(0, 0%, 95%);
+}
+```
+
+**Breakpoint mode overrides (mobile-first):**
+
+```css
+@media (min-width: 768px) {
+  :root {
+    --spacing-4: 1.25rem;  /* 20px at tablet */
+    --text-xl: 1.75rem;    /* 28px at tablet */
+  }
+}
+
+@media (min-width: 1024px) {
+  :root {
+    --spacing-4: 1.5rem;   /* 24px at desktop */
+    --text-xl: 2rem;       /* 32px at desktop */
+  }
+}
+```
+
+**Rendering rules:**
+- Only emit overrides for tokens whose values differ from the base mode
+- Theme collections render as `@media (prefers-color-scheme)` AND `[data-theme]` selector (both, for progressive enhancement)
+- Breakpoint collections render as `@media (min-width)` with mobile-first ordering
+- Use rem units for spacing and font sizes (divide pixel value by 16)
+- Use HSL for colors (enables easy lightness/saturation manipulation)
+- Add comments showing the original pixel values for developer reference
+
+### Step 7: Render Tailwind Config Extension
+
+Generate a `tailwind.config.ts` extension snippet that maps tokens to Tailwind utilities:
+
+```typescript
+import type { Config } from 'tailwindcss'
+
+export default {
+  theme: {
+    extend: {
+      colors: {
+        primary: 'var(--color-primary)',
+        secondary: 'var(--color-secondary)',
+        neutral: {
+          100: 'var(--color-neutral-100)',
+          900: 'var(--color-neutral-900)',
+        },
+        error: 'var(--color-error)',
+        success: 'var(--color-success)',
+      },
+      fontFamily: {
+        primary: 'var(--font-primary)',
+        heading: 'var(--font-heading)',
+      },
+      fontSize: {
+        sm: 'var(--text-sm)',
+        base: 'var(--text-base)',
+        lg: 'var(--text-lg)',
+        xl: 'var(--text-xl)',
+      },
+      spacing: {
+        1: 'var(--spacing-1)',
+        2: 'var(--spacing-2)',
+        4: 'var(--spacing-4)',
+        6: 'var(--spacing-6)',
+        8: 'var(--spacing-8)',
+      },
+      borderRadius: {
+        sm: 'var(--radius-sm)',
+        md: 'var(--radius-md)',
+        lg: 'var(--radius-lg)',
+      },
+      boxShadow: {
+        sm: 'var(--shadow-sm)',
+        md: 'var(--shadow-md)',
+      },
+    },
+  },
+} satisfies Config
+```
+
+**Tailwind mapping rules:**
+- All Tailwind values reference CSS Custom Properties via `var()` -- never hardcode values
+- This ensures Tailwind utilities automatically adapt to theme/breakpoint mode changes
+- Color tokens map to `theme.extend.colors` (enables `bg-primary`, `text-secondary`, etc.)
+- Spacing tokens map to `theme.extend.spacing` (enables `gap-4`, `p-6`, etc.)
+- Typography tokens split across `fontFamily`, `fontSize`
+- Effect tokens map to `borderRadius`, `boxShadow`
+
+### Step 8: Render SCSS Variables (If Requested)
+
+Only generate SCSS output if the user explicitly requests it:
+
+```scss
+// _variables.scss — Generated from Figma design tokens
+
+// Colors
+$color-primary: var(--color-primary);
+$color-secondary: var(--color-secondary);
+
+// Spacing
+$spacing-1: var(--spacing-1);
+$spacing-4: var(--spacing-4);
+
+// Typography
+$font-primary: var(--font-primary);
+$text-base: var(--text-base);
+```
+
+SCSS variables reference CSS Custom Properties (not raw values) to maintain single source of truth.
+
+## Output
+
+Generate two files (three if SCSS requested):
+
+### 1. `tokens.css`
+
+- `:root` block with all promoted tokens organized by category (colors, spacing, typography, effects)
+- Mode-aware overrides via `@media (prefers-color-scheme)`, `[data-theme]` selectors, or `@media (min-width)` for breakpoints
+- Comments showing original Figma variable paths or pixel values
+- HSL format for colors, rem units for spacing/typography
+
+### 2. `tailwind.config.ts` (extension snippet)
+
+- `theme.extend` configuration referencing CSS Custom Properties
+- All values use `var()` references to tokens defined in `tokens.css`
+- Ready to merge into existing Tailwind configuration
+
+### 3. `_variables.scss` (only if requested)
+
+- SCSS variable declarations referencing CSS Custom Properties
+
+### Output Checklist
+
+Before returning token output, verify:
+
+- [ ] Colors use HSL format (`hsl(h, s%, l%)`)
+- [ ] Spacing values use rem units with pixel comments
+- [ ] Spacing is based on consistent base unit (default 4px)
+- [ ] Token names follow `--{category}-{name}-{variant}` convention
+- [ ] Variables API tokens preserve original variable path in names
+- [ ] File traversal tokens use HSL classification for color naming
+- [ ] Mode overrides only contain tokens that differ from the base
+- [ ] Theme modes render both `@media (prefers-color-scheme)` and `[data-theme]`
+- [ ] Breakpoint modes render mobile-first `@media (min-width)` in ascending order
+- [ ] Tailwind config references `var()` for all values (no hardcoded values)
+- [ ] Fallback path is documented when Variables API is not available
+- [ ] Single-use values (below threshold) are NOT promoted to tokens