figma-code-agent 1.0.0

package/knowledge/css-strategy.md

@@ -0,0 +1,973 @@
+# Layered CSS Architecture
+
+## Purpose
+
+Authoritative reference for the layered CSS strategy used in Figma design-to-code generation. Documents how generated CSS properties are distributed across three layers -- Tailwind CSS utilities for structural layout, CSS Custom Properties for design tokens, and CSS Modules for component-specific visual styling -- to produce maintainable, overridable, production-grade CSS output. Encodes production patterns for token extraction, CSS generation, token consumption, and CSS Modules isolation.
+
+## When to Use
+
+Reference this module when you need to:
+
+- Decide which CSS layer a generated property should belong to (Tailwind, Custom Property, or CSS Module)
+- Understand how the three CSS layers compose without specificity conflicts
+- Configure Tailwind to reference design tokens from CSS Custom Properties
+- Structure CSS Module files for component-scoped visual styles
+- Implement token consumption patterns with `var()` and fallback values
+- Handle responsive CSS using mobile-first media queries with Tailwind prefixes
+- Support light/dark themes through CSS Custom Properties and mode selectors
+- Choose between separate CSS files (reset.css, tokens.css, styles.css) or merged output
+- Understand how the five design-to-code modules feed into the CSS generation pipeline
+- Implement Visual Builder token aliasing for plugin isolation
+
+---
+
+## Content
+
+### 1. Three-Layer Architecture Overview
+
+Generated CSS is distributed across three layers, each with a distinct responsibility and specificity level. This separation ensures that layout structure, design tokens, and visual skin can be modified independently.
+
+#### Layer Summary
+
+| Layer | Technology | Responsibility | Specificity |
+|-------|-----------|----------------|-------------|
+| 1. Layout Bones | Tailwind CSS classes | Flexbox, gap, padding, margin, sizing, positioning, responsive breakpoints | Zero (utility classes at `@layer utilities`) |
+| 2. Design Tokens | CSS Custom Properties | Colors, font sizes, font families, spacing values, radii, shadows, transitions | Defined on `:root` (zero selector specificity for the variables themselves) |
+| 3. Visual Skin | CSS Modules | Component-specific backgrounds, borders, effects, color assignments, overrides | Scoped to component (hashed class names prevent leaking) |
+
+#### Why Three Layers
+
+The three-layer approach solves three problems that single-strategy CSS cannot:
+
+1. **Tailwind alone** cannot handle design-specific visual styles (exact color assignments, shadow compositions, gradient definitions) without excessive arbitrary values that defeat the utility-class purpose.
+
+2. **CSS Custom Properties alone** cannot provide structural layout utilities efficiently. Repeating `display: flex; flex-direction: column; gap: var(--spacing-md)` on every container is verbose when `flex flex-col gap-4` achieves the same result.
+
+3. **CSS Modules alone** cannot share design tokens across components without importing a shared file or duplicating values. Token changes would require editing every module file.
+
+The three layers compose naturally: Tailwind handles the predictable structural patterns, Custom Properties provide the shared design language, and CSS Modules apply the unique visual identity per component.
+
+#### How the Layers Compose
+
+```html
+<!-- Layer 1: Tailwind classes handle layout -->
+<div class="flex flex-col gap-4 p-6 w-full">
+  <!-- Layer 3: CSS Module class handles visual skin -->
+  <div class="card">
+    <h2 class="card__title">Welcome</h2>
+    <p class="card__body">Content here</p>
+  </div>
+</div>
+```
+
+```css
+/* Layer 2: tokens.css — design tokens at :root */
+:root {
+  --color-neutral-100: #f5f5f5;
+  --color-neutral-800: #333333;
+  --color-primary: #1a73e8;
+  --radius-lg: 12px;
+  --shadow-md: 0 4px 6px -1px rgba(0, 0, 0, 0.1);
+}
+
+/* Layer 3: Card.module.css — visual skin consuming tokens */
+.card {
+  background-color: var(--color-neutral-100);
+  border: 1px solid var(--color-neutral-300);
+  border-radius: var(--radius-lg);
+  box-shadow: var(--shadow-md);
+}
+
+.card__title {
+  color: var(--color-neutral-800);
+  font-size: var(--text-2xl);
+  font-weight: var(--font-bold);
+}
+```
+
+---
+
+### 2. Layer 1: Tailwind CSS (Layout Bones)
+
+Tailwind CSS handles all structural layout properties. These are the mechanical, pattern-based properties that determine how elements are arranged, sized, and spaced -- not how they look visually.
+
+#### Properties That Belong in Tailwind
+
+| CSS Property | Tailwind Class | Source in Figma |
+|-------------|---------------|-----------------|
+| `display: flex` | `flex` | Auto Layout container |
+| `flex-direction: column` | `flex-col` | `layoutMode: VERTICAL` |
+| `flex-direction: row` | `flex-row` | `layoutMode: HORIZONTAL` |
+| `justify-content: center` | `justify-center` | `primaryAxisAlignItems: CENTER` |
+| `justify-content: space-between` | `justify-between` | `primaryAxisAlignItems: SPACE_BETWEEN` |
+| `align-items: center` | `items-center` | `counterAxisAlignItems: CENTER` |
+| `align-items: flex-start` | `items-start` | `counterAxisAlignItems: MIN` |
+| `gap: 16px` | `gap-4` | `itemSpacing: 16` |
+| `padding: 24px` | `p-6` | `padding: { top: 24, right: 24, bottom: 24, left: 24 }` |
+| `padding: 16px 24px` | `py-4 px-6` | Mixed padding values |
+| `flex-grow: 1; flex-basis: 0` | `flex-1` | `layoutSizingHorizontal: FILL` (primary axis) |
+| `flex-shrink: 0` | `shrink-0` | `layoutSizingHorizontal: FIXED` (primary axis) |
+| `align-self: stretch` | `self-stretch` | `layoutSizingVertical: FILL` (counter axis) |
+| `width: 100%` | `w-full` | FILL on counter axis |
+| `flex-wrap: wrap` | `flex-wrap` | `layoutWrap: WRAP` |
+| `position: relative` | `relative` | Parent of absolute children |
+| `position: absolute` | `absolute` | `layoutPositioning: ABSOLUTE` |
+| `overflow: hidden` | `overflow-hidden` | Clip content |
+| `min-width: 200px` | `min-w-[200px]` | `minWidth: 200` |
+| `max-width: 800px` | `max-w-[800px]` | `maxWidth: 800` |
+
+#### When NOT to Use Tailwind
+
+Tailwind should NOT be used for visual design properties:
+
+- **Colors** -- `bg-blue-500` creates a tight coupling to Tailwind's color palette. Use CSS Custom Properties so colors can be changed via tokens without touching HTML.
+- **Shadows** -- `shadow-lg` uses Tailwind's built-in shadow, not the design's specific shadow. Use token-referenced `box-shadow` in CSS Modules.
+- **Border radius** -- Design-specific radii should reference tokens (`var(--radius-lg)`), not Tailwind's radius scale.
+- **Font sizes** -- Use token-referenced `font-size` (`var(--text-lg)`) to maintain consistency with the design's type scale.
+- **Specific spacing values** -- When a spacing value maps to a design token (from Figma Variables or threshold-promoted), use `var(--spacing-md)` instead of `gap-4`.
+
+**Exception:** When Tailwind is configured to reference CSS Custom Properties in its theme (see Section 2.1), Tailwind classes like `gap-md` or `text-lg` can safely reference tokens.
+
+#### 2.1 Tailwind Theme Integration with Design Tokens
+
+Tailwind's theme can be configured to reference CSS Custom Properties, bridging Layer 1 and Layer 2:
+
+```js
+// tailwind.config.js
+export default {
+  theme: {
+    extend: {
+      colors: {
+        primary: 'var(--color-primary)',
+        secondary: 'var(--color-secondary)',
+        neutral: {
+          100: 'var(--color-neutral-100)',
+          300: 'var(--color-neutral-300)',
+          800: 'var(--color-neutral-800)',
+        },
+      },
+      spacing: {
+        xs: 'var(--spacing-xs)',
+        sm: 'var(--spacing-sm)',
+        md: 'var(--spacing-md)',
+        lg: 'var(--spacing-lg)',
+        xl: 'var(--spacing-xl)',
+      },
+      borderRadius: {
+        sm: 'var(--radius-sm)',
+        md: 'var(--radius-md)',
+        lg: 'var(--radius-lg)',
+        full: 'var(--radius-full)',
+      },
+      fontSize: {
+        xs: 'var(--text-xs)',
+        sm: 'var(--text-sm)',
+        base: 'var(--text-base)',
+        lg: 'var(--text-lg)',
+        xl: 'var(--text-xl)',
+        '2xl': 'var(--text-2xl)',
+      },
+      boxShadow: {
+        sm: 'var(--shadow-sm)',
+        md: 'var(--shadow-md)',
+        lg: 'var(--shadow-lg)',
+      },
+    },
+  },
+}
+```
+
+With this configuration, `gap-md` resolves to `gap: var(--spacing-md)`, which in turn resolves to the actual pixel value defined in the `:root` tokens. This allows Tailwind classes to be token-aware without hardcoding values.
+
+#### Tailwind v4 Configuration
+
+The reference project uses Tailwind v4 via `@tailwindcss/postcss`:
+
+```js
+// postcss.config.mjs
+const config = {
+  plugins: {
+    '@tailwindcss/postcss': {},
+  },
+}
+export default config
+```
+
+Tailwind v4 automatically detects CSS custom properties and can use them as utility values without explicit theme configuration, reducing the need for manual theme extension.
+
+---
+
+### 3. Layer 2: CSS Custom Properties (Design Tokens)
+
+CSS Custom Properties serve as the design tokens bridge -- the shared vocabulary of colors, spacing, typography, radii, shadows, and transitions that all components reference. Tokens are defined once in `:root` and consumed everywhere via `var()`.
+
+#### Token Placement at `:root`
+
+All design tokens are defined on the `:root` selector, making them globally available:
+
+```css
+:root {
+  /* Colors */
+  --color-primary: #1a73e8;
+  --color-secondary: #5f6368;
+  --color-neutral-100: #f5f5f5;
+  --color-neutral-800: #333333;
+  --color-success: #34a853;
+  --color-warning: #fbbc04;
+  --color-error: #ea4335;
+
+  /* Spacing */
+  --spacing-1: 4px;
+  --spacing-2: 8px;
+  --spacing-3: 12px;
+  --spacing-4: 16px;
+  --spacing-6: 24px;
+  --spacing-8: 32px;
+
+  /* Typography */
+  --font-primary: 'Inter', sans-serif;
+  --font-mono: 'Roboto Mono', monospace;
+  --text-sm: 14px;
+  --text-base: 16px;
+  --text-lg: 18px;
+  --text-xl: 24px;
+  --text-2xl: 32px;
+  --font-regular: 400;
+  --font-medium: 500;
+  --font-bold: 700;
+
+  /* Border Radii */
+  --radius-sm: 4px;
+  --radius-md: 8px;
+  --radius-lg: 12px;
+  --radius-full: 9999px;
+
+  /* Shadows */
+  --shadow-sm: 0 1px 2px rgba(0, 0, 0, 0.05);
+  --shadow-md: 0 4px 6px -1px rgba(0, 0, 0, 0.1);
+  --shadow-lg: 0 10px 15px -3px rgba(0, 0, 0, 0.1);
+
+  /* Transitions */
+  --transition-fast: 150ms ease;
+  --transition-normal: 200ms ease;
+  --transition-slow: 300ms ease;
+}
+```
+
+#### Category Naming Conventions
+
+The recommended category prefixes for auto-detected tokens:
+
+| Category | Prefix | Examples |
+|----------|--------|---------|
+| Colors | `--color-*` | `--color-primary`, `--color-neutral-800`, `--color-error` |
+| Spacing | `--spacing-*` | `--spacing-1`, `--spacing-4`, `--spacing-8` |
+| Font sizes | `--text-*` | `--text-sm`, `--text-base`, `--text-2xl` |
+| Font families | `--font-*` | `--font-primary`, `--font-mono` |
+| Font weights | `--font-*` | `--font-bold`, `--font-medium`, `--font-regular` |
+| Border radii | `--radius-*` | `--radius-sm`, `--radius-md`, `--radius-full` |
+| Shadows | `--shadow-*` | `--shadow-sm`, `--shadow-md`, `--shadow-lg` |
+| Transitions | `--transition-*` | `--transition-fast`, `--transition-normal` |
+
+#### The `--token-*` Double-Prefix Pattern
+
+Some projects add a `--token-` prefix to all design tokens. This serves two purposes: (1) clearly distinguishes design tokens from other CSS custom properties, and (2) enables the Visual Builder's token aliasing pattern.
+
+```css
+/* tokens.css */
+:root {
+  --token-color-primary: #3b82f6;
+  --token-spacing-md: 16px;
+  --token-radius-lg: 12px;
+  --token-font-size-base: 18px;
+  --token-shadow-md: 0 4px 6px -1px rgba(0, 0, 0, 0.1);
+}
+```
+
+The `--token-` prefix is a project convention, not a requirement. Some projects use bare category prefixes (`--color-*`), others use `--token-color-*`. Both are valid approaches.
+
+#### Token Fallback Pattern
+
+When consuming tokens in CSS Module rules, always include a raw fallback value. This ensures the styles work even if the token definition is missing (e.g., during development, or when tokens are loaded asynchronously):
+
+```css
+/* With fallback — safe for all environments */
+background-color: var(--token-color-primary, #3b82f6);
+border-radius: var(--token-radius-lg, 12px);
+padding: var(--token-spacing-lg, 24px);
+
+/* Without fallback — only safe when token is guaranteed to be defined */
+background-color: var(--color-primary);
+```
+
+**When to omit fallbacks:** For tokens defined in the same project's `tokens.css` that is guaranteed to be loaded before component styles. Fallbacks can be omitted for local Figma Variables (tokens defined in the same file). External library variables always include fallbacks.
+
+> For details on token extraction, naming algorithms, and promotion thresholds, see `design-tokens.md`.
+
+---
+
+### 4. Layer 3: CSS Modules (Visual Skin)
+
+CSS Modules provide component-scoped visual styles. These are the Figma-specific visual properties that give each component its unique appearance -- backgrounds, borders, shadows, color assignments, typography styling.
+
+#### Component-Scoped Styles
+
+Each component gets its own CSS Module file. Class names are locally scoped (hashed at build time), preventing style leaking between components:
+
+```css
+/* Card.module.css */
+.card {
+  background-color: var(--color-neutral-100);
+  border: 1px solid var(--color-neutral-300);
+  border-radius: var(--radius-lg);
+  box-shadow: var(--shadow-md);
+}
+
+.card__title {
+  color: var(--color-neutral-800);
+  font-size: var(--text-2xl);
+  font-weight: var(--font-bold);
+}
+
+.card__body {
+  color: var(--color-neutral-800);
+  font-size: var(--text-base);
+  line-height: 1.6;
+}
+
+.card__cta {
+  background-color: var(--color-primary);
+  color: var(--color-neutral-100);
+  border-radius: var(--radius-sm);
+  font-weight: var(--font-medium);
+}
+```
+
+#### BEM Naming Within Modules
+
+CSS Module class names follow BEM conventions with flat hierarchy (no deeper than `block__element`):
+
+```css
+/* Block */
+.hero { }
+
+/* Elements */
+.hero__inner { }
+.hero__content { }
+.hero__title { }
+.hero__buttons { }
+.hero__button { }
+
+/* Modifiers (via composes or separate classes) */
+.heroContainerHigh { min-height: 400px; }
+.heroContainerMedium { min-height: 300px; }
+```
+
+> For BEM naming conventions and flat hierarchy rules, see `design-to-code-semantic.md`.
+
+#### Token Consumption Pattern
+
+CSS Module rules consume tokens via `var()` references. The module never defines its own token values -- it only references tokens from Layer 2:
+
+```css
+/* CORRECT: Module consumes tokens */
+.card {
+  background-color: var(--token-color-bg, #ffffff);
+  border-radius: var(--token-radius-lg, 12px);
+  box-shadow: var(--token-shadow-sm, 0 1px 3px rgba(0, 0, 0, 0.1));
+}
+
+/* WRONG: Module defines its own values (bypasses token system) */
+.card {
+  background-color: #ffffff;
+  border-radius: 12px;
+  box-shadow: 0 1px 3px rgba(0, 0, 0, 0.1);
+}
+```
+
+#### File Organization (Per-Block Modules)
+
+The recommended approach organizes CSS Modules by block type, with each block in its own file under `src/styles/blocks/`:
+
+```
+src/styles/
+  tokens.css              # Layer 2: shared design tokens
+  blocks/
+    accordion.module.css  # Layer 3: per-block visual skin
+    button.module.css
+    callToAction.module.css
+    card.module.css
+    container.module.css
+    hero.module.css
+    media.module.css
+    richText.module.css
+    stats.module.css
+    testimonial.module.css
+    video.module.css
+```
+
+Each module imports `tokens.css` to ensure token definitions are available:
+
+```css
+@import '../tokens.css';
+
+.card {
+  background-color: var(--token-color-bg, #ffffff);
+  /* ... */
+}
+```
+
+#### Visual Builder Token Aliasing
+
+The Visual Builder plugin creates a CSS isolation boundary using `contain: content` and `isolation: isolate`. Within this boundary, tokens are aliased from `--token-*` to `--vb-*` to prevent interference with the Payload CMS admin panel's styles:
+
+```css
+/* visualCanvas.module.css */
+.visualCanvas {
+  all: revert;
+  contain: content;
+  isolation: isolate;
+
+  /* Token aliasing: VB tokens reference project tokens with fallbacks */
+  --vb-color-primary: var(--token-color-primary, #3b82f6);
+  --vb-spacing-md: var(--token-spacing-md, 16px);
+  --vb-radius-md: var(--token-radius-md, 8px);
+  /* ... full aliasing for all token categories */
+}
+```
+
+This pattern enables:
+
+1. **Plugin portability** -- The Visual Builder works in any project regardless of whether `--token-*` variables are defined (fallbacks kick in)
+2. **Admin isolation** -- `contain: content` prevents Payload admin styles from bleeding into the visual canvas
+3. **Single source of truth** -- Projects define tokens once in `tokens.css`; the Visual Builder automatically picks them up via the alias chain
+
+---
+
+### 5. Property Placement Decision Tree
+
+For any CSS property generated from a Figma node, this decision tree determines which layer it belongs to. This is the core routing logic for the CSS generation pipeline.
+
+```
+For each CSS property on a GeneratedElement:
+
+  1. IS IT A STRUCTURAL LAYOUT PROPERTY?
+     (display, flex-direction, justify-content, align-items, gap,
+      flex-grow, flex-basis, flex-shrink, flex-wrap, align-self,
+      align-content, position, width/height from sizing modes,
+      min-width, max-width, min-height, max-height, overflow)
+
+       YES → Layer 1: Tailwind utility class
+       Rationale: Layout is mechanical and pattern-based.
+       Tailwind's utility classes express these concisely.
+
+  2. IS THE RAW VALUE A PROMOTED DESIGN TOKEN?
+     (color resolves to var(--color-*),
+      spacing resolves to var(--spacing-*),
+      font-size resolves to var(--text-*),
+      font-family resolves to var(--font-*),
+      font-weight resolves to var(--font-*),
+      border-radius resolves to var(--radius-*),
+      box-shadow resolves to var(--shadow-*))
+
+       YES → Layer 2: CSS Custom Property reference in the value
+       The token is DEFINED in :root, CONSUMED in the CSS Module rule.
+       Rationale: Tokens are the shared design language. Centralizing
+       them enables theme changes without touching component styles.
+
+  3. IS IT A COMPONENT-SPECIFIC VISUAL STYLE?
+     (background-color, background-image, border, border-color,
+      border-radius, box-shadow, color, opacity, filter,
+      backdrop-filter, mix-blend-mode, text-decoration,
+      transition, transform)
+
+       YES → Layer 3: CSS Module rule
+       The property is placed in the component's .module.css file.
+       If the value is a token, the rule uses var(--token-*).
+       If the value is not a token, the raw value is used inline.
+
+  4. IS IT PADDING OR GAP WITH A TOKEN VALUE?
+
+       YES → Layer 1 if using Tailwind theme integration:
+         class="gap-md p-lg" (where md/lg map to token vars)
+       YES → Layer 3 if not using Tailwind theme integration:
+         gap: var(--spacing-md); padding: var(--spacing-lg);
+       Rationale: Padding and gap are layout properties but can also
+       carry token values. The choice depends on Tailwind configuration.
+```
+
+#### Property-to-Layer Reference Table
+
+| Property Category | Example Properties | Layer | Method |
+|------------------|--------------------|-------|--------|
+| Flex container | `display`, `flex-direction`, `justify-content`, `align-items`, `flex-wrap`, `align-content` | 1 (Tailwind) | Utility classes |
+| Flex child | `flex-grow`, `flex-basis`, `flex-shrink`, `align-self` | 1 (Tailwind) | Utility classes |
+| Spacing | `gap`, `padding`, `margin` | 1 or 3 | Tailwind if standard; Module if token-bound |
+| Sizing | `width`, `height`, `min-width`, `max-width` | 1 (Tailwind) | Utility classes |
+| Positioning | `position`, `top`, `right`, `bottom`, `left`, `z-index` | 1 (Tailwind) | Utility classes |
+| Overflow | `overflow`, `text-overflow` | 1 (Tailwind) | Utility classes |
+| Background | `background-color`, `background-image`, `background-size` | 3 (Module) | CSS rule with `var()` |
+| Border | `border`, `border-color`, `border-width` | 3 (Module) | CSS rule with `var()` |
+| Border radius | `border-radius` | 3 (Module) | CSS rule with `var()` |
+| Shadow | `box-shadow` | 3 (Module) | CSS rule with `var()` |
+| Color | `color` | 3 (Module) | CSS rule with `var()` |
+| Typography | `font-family`, `font-size`, `font-weight`, `line-height` | 3 (Module) | CSS rule with `var()` |
+| Text | `text-align`, `text-transform`, `white-space`, `letter-spacing` | 3 (Module) | CSS rule |
+| Opacity | `opacity` | 3 (Module) | CSS rule |
+| Blend modes | `mix-blend-mode`, `background-blend-mode` | 3 (Module) | CSS rule |
+| Filters | `filter`, `backdrop-filter` | 3 (Module) | CSS rule |
+| Transitions | `transition` | 3 (Module) | CSS rule with `var()` |
+
+---
+
+### 6. Specificity Management
+
+The three layers compose without specificity conflicts because each layer operates at a different specificity level.
+
+#### Specificity by Layer
+
+| Layer | Selector Type | Specificity | Example |
+|-------|-------------|-------------|---------|
+| 1. Tailwind | Utility class | `0-1-0` (single class) | `.flex` |
+| 2. Tokens | `:root` pseudo-class | `0-1-0` (for definition) | `:root { --color-primary: #1a73e8 }` |
+| 3. CSS Module | Hashed class | `0-1-0` (single class) | `.card_abc123` |
+
+#### Why Conflicts Do Not Occur
+
+1. **Tailwind vs Modules** -- Tailwind handles layout properties. Modules handle visual properties. They target different CSS properties on the same element, so they do not compete.
+
+2. **Tokens vs Modules** -- Tokens define variables on `:root`. Modules consume those variables via `var()`. They do not target the same selectors or properties.
+
+3. **Tailwind vs Tokens** -- When Tailwind is configured with token references in its theme, Tailwind utilities resolve to `var()` values. This is composition, not conflict.
+
+#### Potential Conflict: Padding and Gap
+
+The one area where Layers 1 and 3 could conflict is spacing properties (padding, gap). If a Tailwind class sets `gap: 16px` and a CSS Module rule also sets `gap: var(--spacing-md)`, the Module rule wins due to source order (Modules are loaded after Tailwind utilities).
+
+**Resolution:** Choose one layer for spacing. Either:
+- Use Tailwind for all spacing (with token-aware theme configuration)
+- Use CSS Module rules for all spacing (when token substitution is needed)
+
+Do not mix both layers for the same spacing property on the same element.
+
+#### Tailwind `@layer` Ordering
+
+Tailwind v4 uses CSS `@layer` to establish baseline ordering:
+
+```
+@layer base;       /* Resets, element defaults */
+@layer components; /* Component styles (CSS Modules go here) */
+@layer utilities;  /* Tailwind utilities (highest CSS layer priority) */
+```
+
+By default, Tailwind utilities override component styles. This means a Tailwind class on an element will override the same property set by a CSS Module. This is generally desirable for layout overrides but requires awareness when both layers target the same property.
+
+---
+
+### 7. Responsive Strategy
+
+#### Mobile-First Breakpoint Ordering
+
+All responsive CSS uses a mobile-first approach: base styles target the smallest viewport, and larger viewports are handled through `min-width` media queries.
+
+| Breakpoint | min-width | CSS |
+|------------|-----------|-----|
+| `mobile` | _(base)_ | No media query (base styles) |
+| `tablet` | 768px | `@media (min-width: 768px)` |
+| `desktop` | 1024px | `@media (min-width: 1024px)` |
+
+This matches both responsive frame merging (see `design-to-code-layout.md` Section 8) and Figma Variables breakpoint mode detection.
+
+#### Figma Variables Mode to Media Query Mapping
+
+When Figma variable collections use breakpoint modes (detected by mode names like "mobile", "tablet", "desktop"), the pipeline renders mode-aware `:root` overrides inside media queries:
+
+```css
+/* Base: mobile values (default mode) */
+:root {
+  --spacing-lg: 16px;
+  --text-xl: 20px;
+}
+
+/* Tablet overrides */
+@media (min-width: 768px) {
+  :root {
+    --spacing-lg: 24px;
+    --text-xl: 24px;
+  }
+}
+
+/* Desktop overrides */
+@media (min-width: 1024px) {
+  :root {
+    --spacing-lg: 32px;
+    --text-xl: 28px;
+  }
+}
+```
+
+This approach means component styles automatically respond to viewport changes without any media queries of their own -- the token values change, and all `var()` references resolve to the new values.
+
+#### Tailwind Responsive Prefixes
+
+For layout properties in Layer 1, use Tailwind's responsive prefixes:
+
+```html
+<div class="flex flex-col md:flex-row gap-3 md:gap-6 lg:gap-8 p-4 md:p-6 lg:p-8">
+```
+
+| Prefix | Breakpoint | CSS |
+|--------|-----------|-----|
+| _(none)_ | All | Base styles |
+| `sm:` | 640px | `@media (min-width: 640px)` |
+| `md:` | 768px | `@media (min-width: 768px)` |
+| `lg:` | 1024px | `@media (min-width: 1024px)` |
+| `xl:` | 1280px | `@media (min-width: 1280px)` |
+
+#### CSS Module Responsive Patterns
+
+For visual properties in Layer 3 that need responsive behavior beyond what token media queries provide:
+
+```css
+/* Card.module.css */
+.card {
+  border-radius: var(--radius-md);
+}
+
+@media (min-width: 768px) {
+  .card {
+    border-radius: var(--radius-lg);
+  }
+}
+```
+
+This is less common because most responsive visual changes are handled through token mode overrides at the `:root` level. Module-level media queries are only needed for structural visual changes (e.g., adding/removing a border on desktop, changing an element's background pattern).
+
+> For responsive frame matching and style diffing algorithms, see `design-to-code-layout.md` Section 8.
+
+---
+
+### 8. Theme Support
+
+#### Light/Dark Theme via CSS Custom Properties
+
+Themes are implemented by redefining token values under different selectors. The component styles remain unchanged -- they reference tokens via `var()`, and the resolved values change based on the active theme.
+
+**Media query approach (automatic, based on OS preference):**
+
+```css
+:root {
+  --color-bg: #ffffff;
+  --color-text: #1a1a1a;
+  --color-border: #e0e0e0;
+}
+
+@media (prefers-color-scheme: dark) {
+  :root {
+    --color-bg: #1a1a1a;
+    --color-text: #ffffff;
+    --color-border: #404040;
+  }
+}
+```
+
+**Data attribute approach (manual toggle, JavaScript-controlled):**
+
+```css
+:root,
+[data-theme="light"] {
+  --color-bg: #ffffff;
+  --color-text: #1a1a1a;
+}
+
+[data-theme="dark"] {
+  --color-bg: #1a1a1a;
+  --color-text: #ffffff;
+}
+```
+
+The pipeline generates both approaches when theme mode collections are detected: the `prefers-color-scheme` media query for automatic theme detection, and the `[data-theme]` selector for manual control.
+
+#### Figma Variables Theme Mode Mapping
+
+When a Figma variable collection has a "theme" mode type (detected by mode names containing "light" or "dark"), the pipeline maps the default mode (light) to `:root` and non-default modes to both `prefers-color-scheme` and `[data-theme]` selectors:
+
+```
+Collection: "Theme"
+  Mode "Light" (default) → :root { }
+  Mode "Dark"            → @media (prefers-color-scheme: dark) { :root { } }
+                           [data-theme="dark"] { }
+```
+
+> For the full Figma Variables multi-mode theming patterns, see `figma-api-variables.md`.
+
+#### Brand Theming
+
+For multi-brand themes, use class-based selectors:
+
+```css
+.brand-a {
+  --color-primary: #0066ff;
+  --font-primary: 'Inter', sans-serif;
+}
+
+.brand-b {
+  --color-primary: #ff3366;
+  --font-primary: 'Poppins', sans-serif;
+}
+```
+
+Components reference `var(--color-primary)` and automatically adopt the active brand's values.
+
+---
+
+### 9. Export Formats
+
+The generation pipeline supports multiple CSS export structures depending on the project's needs.
+
+#### Separate Files (Recommended for Projects)
+
+When `separateTokens: true`, the export produces three independent CSS files:
+
+| File | Content | Layer |
+|------|---------|-------|
+| `reset.css` | Universal CSS reset (box-sizing, margin, padding, image defaults) | Pre-layer |
+| `tokens.css` | `:root` block with CSS Custom Properties, media queries for modes | Layer 2 |
+| `styles.css` | Component class rules (BEM-named) | Layer 3 |
+
+Import order matters:
+
+```html
+<link rel="stylesheet" href="reset.css">
+<link rel="stylesheet" href="tokens.css">
+<link rel="stylesheet" href="styles.css">
+```
+
+#### Merged Output (Default for Preview)
+
+When `separateTokens: false`, tokens are merged into `styles.css`:
+
+| File | Content |
+|------|---------|
+| `reset.css` | Universal CSS reset |
+| `styles.css` | Tokens (`:root` block) + component class rules |
+
+#### SCSS Export
+
+For SCSS consumers, the pipeline generates a parallel file structure using SCSS conventions:
+
+| File | Content | Notes |
+|------|---------|-------|
+| `_reset.scss` | Reset rules | Underscore prefix = SCSS partial |
+| `_variables.scss` | `$variable` declarations | `--color-primary` becomes `$color-primary` |
+| `_mixins.scss` | Empty placeholder | For project-specific mixins |
+| `styles.scss` | `@import` statements + component rules | Entry point with var() converted to $variable |
+
+**SCSS variable conversion:**
+
+```scss
+// _variables.scss (generated from tokens)
+$color-primary: #1a73e8;
+$spacing-4: 16px;
+$text-lg: 18px;
+$font-bold: 700;
+$shadow-md: 0 4px 6px -1px rgba(0, 0, 0, 0.1);
+
+// styles.scss (generated from component styles)
+@import 'variables';
+@import 'reset';
+@import 'mixins';
+
+.card {
+  background-color: $color-neutral-100;
+  border-radius: $radius-lg;
+  box-shadow: $shadow-md;
+}
+```
+
+The conversion replaces `var(--name)` with `$name` and `--name: value` with `$name: value`.
+
+#### HTML Document Export
+
+For standalone preview, the pipeline generates a complete HTML document with embedded CSS:
+
+```html
+<!DOCTYPE html>
+<html lang="en">
+<head>
+  <style>
+    @import url('https://fonts.googleapis.com/css2?family=...');
+    /* CSS reset */
+    /* tokens :root block */
+    /* component styles */
+  </style>
+</head>
+<body>
+  <!-- generated HTML -->
+</body>
+</html>
+```
+
+The ordering within the `<style>` block is: font imports, reset, tokens, component styles.
+
+> For details on the SCSS rendering pipeline, see `design-tokens.md`.
+
+---
+
+### 10. Integration with Design-to-Code Pipeline
+
+The five design-to-code modules feed into the CSS strategy at specific integration points.
+
+#### Pipeline Flow
+
+```
+Figma Node Tree
+    ↓
+[Extraction Phase]
+    ↓
+ExtractedNode tree
+    ↓
+┌─────────────────────────────┐
+│ Token Collection & Promotion │  ← design-tokens.md
+│ (colors, spacing, typography,│
+│  effects, Figma Variables)   │
+└──────────────┬──────────────┘
+               ↓
+         TokenLookup map
+               ↓
+┌─────────────────────────────┐
+│ Generation Phase             │
+│  ├─ layout.md    → Layer 1  │  Flex container/child → Tailwind classes
+│  ├─ visual.md    → Layer 3  │  Fills, strokes, effects → CSS Module rules
+│  ├─ typography.md → Layer 3 │  Font props → CSS Module rules with var()
+│  ├─ assets.md    → HTML     │  Vector/image → <img> tags
+│  └─ semantic.md  → HTML     │  Tags, BEM classes, ARIA attributes
+└──────────────┬──────────────┘
+               ↓
+         GeneratedOutput
+    ┌──────┼──────┐
+    ↓      ↓      ↓
+  HTML   CSS    Tokens
+               ↓      ↓
+         Layer 3   Layer 2
+       (styles.css) (tokens.css)
+```
+
+#### How Each Module Contributes
+
+**`design-to-code-layout.md`** produces layout CSS that maps to Layer 1 (Tailwind classes):
+- `display: flex` → `flex`
+- `flex-direction: column` → `flex-col`
+- `gap: 16px` → `gap-4` (or `gap: var(--spacing-4)` if token-bound)
+- Responsive frame merging → `md:flex-row lg:gap-8`
+
+**`design-to-code-visual.md`** produces visual CSS that maps to Layer 3 (CSS Module rules):
+- `background-color: var(--color-primary)` (via token lookup)
+- `box-shadow: var(--shadow-md)` (via token lookup)
+- `border-radius: var(--radius-lg)` (via token lookup)
+- Raw values when no token match: `border: 1px solid #e0e0e0`
+
+**`design-to-code-typography.md`** produces typography CSS that maps to Layer 3:
+- `font-family: var(--font-primary)` (via token lookup)
+- `font-size: var(--text-lg)` (via token lookup)
+- `font-weight: var(--font-bold)` (via token lookup)
+- `line-height: 1.50` (always raw, not tokenized)
+
+**`design-to-code-assets.md`** produces HTML elements (not CSS):
+- Vector containers → `<img src="icon.svg">`
+- Image fills → `<img>` or `background-image` CSS in Module
+
+**`design-to-code-semantic.md`** produces HTML structure:
+- Semantic tags → `<section>`, `<nav>`, `<h2>`, `<button>`
+- BEM class names → `.card`, `.card__title`, `.card__body`
+- ARIA attributes → `aria-label`, `role`
+
+#### Token Lookup During Generation
+
+The `TokenLookup` is built from promoted tokens before generation begins. During CSS generation, each raw value is checked against the lookup map. If a match is found, the `var()` reference is used instead of the raw value:
+
+```
+Raw value: #1a73e8
+  → lookupColor(lookup, "#1a73e8")
+  → Returns: "var(--color-primary)" (if token exists)
+  → Returns: "#1a73e8" (if no token match)
+```
+
+This substitution happens transparently during the generation of visual and typography styles. Layout properties are not token-substituted (they go to Tailwind).
+
+> For the complete token lookup system, including Figma Variable priority over auto-detected tokens, see `design-tokens.md`.
+
+#### Complete Example: All Three Layers
+
+A card component with all three layers working together:
+
+```html
+<!-- Layer 1: Tailwind for layout -->
+<section class="flex flex-col gap-6 p-6 max-w-md">
+  <!-- Layer 3: CSS Module for visual skin -->
+  <div class="card">
+    <img class="card__image" src="./assets/photo.png" alt="Team photo">
+    <div class="flex flex-col gap-3 p-4">
+      <h3 class="card__title">Meet the Team</h3>
+      <p class="card__body">Our talented people make the difference.</p>
+      <a class="card__cta" href="#">Learn More</a>
+    </div>
+  </div>
+</section>
+```
+
+```css
+/* Layer 2: tokens.css */
+:root {
+  --color-primary: #1a73e8;
+  --color-neutral-100: #f5f5f5;
+  --color-neutral-800: #333333;
+  --text-lg: 18px;
+  --text-2xl: 32px;
+  --font-bold: 700;
+  --radius-lg: 12px;
+  --shadow-md: 0 4px 6px -1px rgba(0, 0, 0, 0.1);
+}
+
+/* Layer 3: Card.module.css */
+.card {
+  background-color: var(--color-neutral-100);
+  border-radius: var(--radius-lg);
+  box-shadow: var(--shadow-md);
+  overflow: hidden;
+}
+
+.card__title {
+  font-size: var(--text-2xl);
+  font-weight: var(--font-bold);
+  color: var(--color-neutral-800);
+}
+
+.card__body {
+  font-size: var(--text-lg);
+  color: var(--color-neutral-800);
+  line-height: 1.60;
+}
+
+.card__cta {
+  background-color: var(--color-primary);
+  color: var(--color-neutral-100);
+  border-radius: var(--radius-sm);
+  padding: 8px 16px;
+  font-weight: var(--font-bold);
+}
+```
+
+---
+
+## Cross-References
+
+- **`design-tokens.md`** -- Token extraction pipeline, threshold-based promotion, naming conventions, CSS/SCSS/Tailwind rendering. Defines the tokens consumed by Layer 2.
+- **`design-tokens-variables.md`** -- Figma Variables deep dive: mode detection and classification, variable resolution chains, mode-aware CSS rendering, fallback strategies, scope-to-CSS-property mapping. The Variables-to-Token-to-CSS bridge.
+- **`figma-api-variables.md`** -- Variables API endpoints, variable data model, multi-mode theming patterns. The source data for Figma Variable tokens.
+- **`design-to-code-layout.md`** -- Auto Layout to Flexbox mapping that produces Layer 1 (Tailwind) output. Responsive multi-frame pattern with mobile-first media queries.
+- **`design-to-code-visual.md`** -- Visual property extraction that produces Layer 3 (CSS Module) output. Color token integration with HSL naming, variable binding resolution.
+- **`design-to-code-typography.md`** -- Typography extraction that produces Layer 3 output. Font family/size/weight token lookup during generation.
+- **`design-to-code-assets.md`** -- Asset management for image and vector export. Asset references appear in HTML (`<img src>`) and CSS Module rules (`background-image`).
+- **`design-to-code-semantic.md`** -- Semantic HTML generation that provides the element structure. BEM class naming used by Layer 3 CSS Modules. Three-layer architecture overview (Section 9).
+- **`payload-blocks.md`** -- PayloadCMS block system that consumes all three CSS layers. Container blocks store Tailwind utility classes (Layer 1), block CSS Modules reference `--token-*` custom properties (Layer 2), and each block has a dedicated CSS Module for scoped visual styles (Layer 3). The three-layer architecture serves this block system directly.