figma-code-agent 1.0.0

package/knowledge/design-to-code-layout.md

@@ -0,0 +1,929 @@
+# Auto Layout → CSS Flexbox Mapping
+
+## Purpose
+
+Authoritative reference for converting Figma Auto Layout properties to CSS Flexbox. Encodes production-proven mapping rules covering the complete pipeline: extracting Auto Layout data from Figma nodes, transforming it into intermediate types, and generating pixel-accurate CSS. This is the foundational design-to-code module that all component generation depends on.
+
+## When to Use
+
+Reference this module when you need to:
+
+- Convert a Figma Auto Layout frame into CSS Flexbox (`display: flex`)
+- Determine the correct CSS for Figma sizing modes (FIXED, HUG, FILL)
+- Map Figma alignment properties to `justify-content` and `align-items`
+- Generate gap, padding, and spacing CSS from Figma properties
+- Handle flex-wrap and `align-content` for wrapped layouts
+- Apply min/max constraints to flex containers and children
+- Position absolute children within Auto Layout parents
+- Convert non-Auto-Layout frames (GROUP, legacy FRAME) to CSS
+- Build responsive CSS from multiple Figma frames representing breakpoints
+- Avoid common design-to-code pitfalls (flex-basis, STRETCH, sizing interactions)
+
+---
+
+## Content
+
+### 1. Auto Layout → Flexbox Core Mapping
+
+Figma's Auto Layout maps directly to CSS Flexbox. Any FRAME, COMPONENT, or INSTANCE node with `layoutMode` set to `HORIZONTAL` or `VERTICAL` is an Auto Layout container.
+
+#### Container Detection
+
+Only these node types can have Auto Layout:
+- `FRAME`
+- `COMPONENT`
+- `INSTANCE`
+
+When `layoutMode` is `NONE`, the frame has no Auto Layout — children use absolute or constraint-based positioning (see Section 7).
+
+#### Flex Direction
+
+| Figma `layoutMode` | CSS `flex-direction` | Intermediate Mode |
+|---------------------|----------------------|-------------------|
+| `HORIZONTAL`        | `row`                | `FLEX_ROW`        |
+| `VERTICAL`          | `column`             | `FLEX_COL`        |
+| `NONE`              | _(no flexbox)_       | `NONE`            |
+
+Every Auto Layout container generates:
+
+```css
+display: flex;
+flex-direction: row; /* or column */
+```
+
+#### Primary Axis Alignment (justify-content)
+
+`primaryAxisAlignItems` controls distribution along the flex direction.
+
+| Figma `primaryAxisAlignItems` | CSS `justify-content` |
+|-------------------------------|-----------------------|
+| `MIN`                         | `flex-start`          |
+| `CENTER`                      | `center`              |
+| `MAX`                         | `flex-end`            |
+| `SPACE_BETWEEN`               | `space-between`       |
+
+#### Counter Axis Alignment (align-items)
+
+`counterAxisAlignItems` controls alignment perpendicular to the flex direction.
+
+| Figma `counterAxisAlignItems` | CSS `align-items` |
+|-------------------------------|-------------------|
+| `MIN`                         | `flex-start`      |
+| `CENTER`                      | `center`          |
+| `MAX`                         | `flex-end`        |
+| `BASELINE`                    | `baseline`        |
+
+> **Important:** `STRETCH` does not appear in the `counterAxisAlignItems` extraction mapping. Stretch behavior is controlled at the child level through sizing modes (FILL on the counter-axis). See Section 2 for how FILL on the counter-axis produces `align-self: stretch`.
+
+#### Complete Container Example
+
+A horizontal Auto Layout frame with center alignment and space-between distribution:
+
+```
+Figma properties:
+  layoutMode: HORIZONTAL
+  primaryAxisAlignItems: SPACE_BETWEEN
+  counterAxisAlignItems: CENTER
+```
+
+```css
+display: flex;
+flex-direction: row;
+justify-content: space-between;
+align-items: center;
+```
+
+---
+
+### 2. Sizing Modes (CRITICAL)
+
+Sizing modes are the **most common source of bugs** in Figma-to-CSS generation. Every child in an Auto Layout container has two sizing properties:
+
+- `layoutSizingHorizontal`: `FIXED` | `HUG` | `FILL`
+- `layoutSizingVertical`: `FIXED` | `HUG` | `FILL`
+
+These interact with the parent's flex direction. The same property (e.g., `layoutSizingHorizontal`) produces different CSS depending on whether horizontal is the **primary axis** (parent is `FLEX_ROW`) or the **counter axis** (parent is `FLEX_COL`).
+
+#### Intermediate Types
+
+```typescript
+interface LayoutChildProperties {
+  flexGrow: number;             // From layoutGrow (0 or 1)
+  alignSelf: 'auto' | 'flex-start' | 'center' | 'flex-end' | 'stretch';
+  sizingHorizontal: 'FIXED' | 'HUG' | 'FILL';
+  sizingVertical: 'FIXED' | 'HUG' | 'FILL';
+  minWidth?: number;
+  maxWidth?: number;
+  minHeight?: number;
+  maxHeight?: number;
+}
+```
+
+#### Sizing Mode → CSS Decision Tree
+
+```
+For each child in an Auto Layout parent:
+
+1. Determine which axis is PRIMARY (same as parent flex-direction)
+   - Parent FLEX_ROW → horizontal = primary, vertical = counter
+   - Parent FLEX_COL → vertical = primary, horizontal = counter
+
+2. PRIMARY AXIS sizing:
+   ├─ FILL  → flex-grow: 1; flex-basis: 0;
+   ├─ FIXED → flex-shrink: 0;  (explicit width/height set separately from bounds)
+   └─ HUG   → (omit — let content determine size)
+
+3. COUNTER AXIS sizing:
+   ├─ FILL  → align-self: stretch;
+   │         (EXCEPTION: if child has max-width/max-height constraint,
+   │          use width: 100% / height: 100% instead — see Section 2.5)
+   ├─ FIXED → (explicit width/height set separately from bounds)
+   └─ HUG   → (omit — let content determine size)
+```
+
+#### 2.1 FILL on Primary Axis
+
+FILL on the primary axis means the child expands to take available space. **Both properties are required:**
+
+```css
+flex-grow: 1;
+flex-basis: 0;
+```
+
+> **CRITICAL: `flex-basis: 0` is essential.** Without it, `flex-basis` defaults to `auto`, which uses the element's content size as the starting point. This causes content-heavy siblings to take disproportionately more space while empty elements (like image placeholders) get squeezed to near-zero width. Setting `flex-basis: 0` ensures all FILL children start from zero and share space equally based on their `flex-grow` factor.
+
+**Example — two FILL children in a row:**
+
+```
+Parent: layoutMode: HORIZONTAL
+Child A: layoutSizingHorizontal: FILL (lots of text content)
+Child B: layoutSizingHorizontal: FILL (empty image placeholder)
+```
+
+Correct CSS:
+```css
+/* Both children get equal space */
+.child-a { flex-grow: 1; flex-basis: 0; }
+.child-b { flex-grow: 1; flex-basis: 0; }
+```
+
+Wrong CSS (without flex-basis: 0):
+```css
+/* Child A takes 80%+ because its content is larger */
+.child-a { flex-grow: 1; }  /* BAD — flex-basis defaults to auto */
+.child-b { flex-grow: 1; }  /* BAD — gets squeezed */
+```
+
+#### 2.2 FIXED on Primary Axis
+
+FIXED means the child maintains an exact size. On the primary axis, prevent flex shrinking:
+
+```css
+flex-shrink: 0;
+width: 200px;   /* or height, depending on axis */
+```
+
+The explicit dimension comes from the node's bounds (set elsewhere in generation). The `flex-shrink: 0` prevents the flex container from compressing this element below its specified size.
+
+#### 2.3 HUG (Content-Based)
+
+HUG means the element sizes to its content. No explicit sizing CSS is needed — the default flex behavior handles it:
+
+```css
+/* No width/height, no flex-grow, no flex-shrink override */
+/* The element naturally sizes to its content */
+```
+
+#### 2.4 FILL on Counter Axis
+
+FILL on the counter axis means the child stretches to fill the parent's cross-axis dimension:
+
+```css
+align-self: stretch;
+```
+
+**Example — column layout with horizontal FILL child:**
+
+```
+Parent: layoutMode: VERTICAL
+Child: layoutSizingHorizontal: FILL
+```
+
+```css
+.child {
+  align-self: stretch;
+}
+```
+
+#### 2.5 FILL on Counter Axis with Max Constraint (Special Case)
+
+When a child has FILL on the counter-axis **and** a max-width or max-height constraint, using `align-self: stretch` would ignore the constraint in some cases. Instead, use percentage sizing:
+
+```
+Parent: layoutMode: HORIZONTAL (primary = horizontal)
+Child: layoutSizingVertical: FILL, maxHeight: 300
+```
+
+```css
+.child {
+  height: 100%;
+  max-height: 300px;
+}
+```
+
+This allows the parent's `align-items` to position the element correctly when the max constraint caps its size (e.g., centering a capped-height element).
+
+The rule:
+- **FILL counter-axis + max constraint on counter dimension** → `width: 100%` / `height: 100%` instead of `align-self: stretch`
+- **FILL counter-axis without max constraint** → `align-self: stretch`
+
+#### 2.6 Mixed Sizing
+
+Children within the same parent can have different sizing modes. This is valid and common:
+
+```
+Parent: layoutMode: HORIZONTAL
+
+Child 1: sizingHorizontal: FIXED (sidebar, 280px)
+Child 2: sizingHorizontal: FILL  (main content, takes remaining)
+Child 3: sizingHorizontal: HUG   (icon, sizes to content)
+```
+
+```css
+.sidebar { width: 280px; flex-shrink: 0; }
+.main    { flex-grow: 1; flex-basis: 0; }
+.icon    { /* no explicit sizing */ }
+```
+
+#### 2.7 Align Self Override
+
+A child's `layoutAlign` property in Figma can override the parent's `counterAxisAlignItems`. This maps to `align-self`:
+
+| Figma `layoutAlign` | CSS `align-self` |
+|----------------------|------------------|
+| `INHERIT`            | `auto`           |
+| `MIN`                | `flex-start`     |
+| `CENTER`             | `center`         |
+| `MAX`                | `flex-end`       |
+| `STRETCH`            | `stretch`        |
+
+> **Note:** `align-self` is only emitted when it differs from `auto` **and** the child is not already using `width: 100%` / `height: 100%` for the FILL + max-constraint pattern. The max-constraint pattern takes precedence.
+
+---
+
+### 3. Gap & Spacing
+
+#### Primary Axis Gap
+
+`itemSpacing` sets the gap between children along the primary axis:
+
+| Figma Property  | CSS Property |
+|-----------------|--------------|
+| `itemSpacing`   | `gap`        |
+
+```
+Figma: itemSpacing: 16
+CSS:   gap: 16px;
+```
+
+> **Important:** `itemSpacing` is spacing **between** children, not padding around them. This maps to CSS `gap`, not `padding`.
+
+#### Counter Axis Gap (Wrap Mode Only)
+
+`counterAxisSpacing` sets the gap between wrapped rows/columns. It only applies when `layoutWrap: WRAP`:
+
+| Figma Property        | CSS Property   |
+|-----------------------|----------------|
+| `counterAxisSpacing`  | `row-gap` or `column-gap` (depending on direction) |
+
+#### Gap Direction Mapping
+
+The CSS gap properties depend on the flex direction:
+
+| Layout Mode | Primary Gap (`itemSpacing`) | Cross Gap (`counterAxisSpacing`) |
+|-------------|----------------------------|----------------------------------|
+| `FLEX_ROW`  | `column-gap`               | `row-gap`                        |
+| `FLEX_COL`  | `row-gap`                  | `column-gap`                     |
+
+**Shorthand optimization:** When both `row-gap` and `column-gap` are equal, use the `gap` shorthand:
+
+```css
+/* Both gaps equal → shorthand */
+gap: 16px;
+
+/* Gaps differ → individual properties */
+row-gap: 8px;
+column-gap: 16px;
+```
+
+#### Variable Bindings for Gap
+
+When `itemSpacing` or `counterAxisSpacing` is bound to a Figma Variable, generate CSS `var()` references instead of raw pixel values:
+
+```typescript
+interface VariableReference {
+  id: string;       // Figma variable ID
+  name: string;     // Variable name path (e.g., "spacing/md")
+  isLocal: boolean; // Local to this file vs. external library
+}
+```
+
+**CSS generation with variables:**
+
+```css
+/* Local variable (defined in same file) — no fallback needed */
+gap: var(--spacing-md);
+
+/* External library variable — include px fallback */
+gap: var(--spacing-md, 16px);
+```
+
+The variable name is converted from Figma's slash-delimited path to CSS custom property naming: `spacing/md` → `--spacing-md`.
+
+#### Padding
+
+Figma padding is per-side: `paddingTop`, `paddingRight`, `paddingBottom`, `paddingLeft`.
+
+**Shorthand optimization:**
+
+```css
+/* All four sides equal */
+padding: 24px;
+
+/* Mixed sides — full longhand */
+padding: 24px 16px 24px 16px;
+```
+
+**With variable bindings:**
+
+```css
+/* All four sides bound to the same variable */
+padding: var(--spacing-lg);
+
+/* Mixed — some variable-bound, some raw */
+padding: var(--spacing-lg, 24px) 16px var(--spacing-lg, 24px) 16px;
+```
+
+The shorthand optimization checks both the numeric values **and** the variable IDs. All four sides must have the same value and the same variable binding (or all unbound) to use the single-value shorthand.
+
+---
+
+### 4. Wrap Mode
+
+#### Enabling Wrap
+
+| Figma Property | CSS Property    |
+|----------------|-----------------|
+| `layoutWrap: WRAP` | `flex-wrap: wrap` |
+
+When `layoutWrap` is not `WRAP` (default `NO_WRAP`), no `flex-wrap` property is emitted.
+
+#### Align Content (Wrapped Line Distribution)
+
+When wrapping is enabled, `counterAxisAlignContent` controls how wrapped lines are distributed:
+
+| Figma `counterAxisAlignContent` | CSS `align-content` |
+|---------------------------------|---------------------|
+| `AUTO`                          | `flex-start`        |
+| `SPACE_BETWEEN`                 | `space-between`     |
+
+`align-content` is only emitted when `layoutWrap: WRAP`.
+
+#### Counter Axis Gap in Wrap Mode
+
+`counterAxisSpacing` becomes relevant in wrap mode — it controls the spacing between wrapped rows/columns. Without wrap, `counterAxisSpacing` has no visual effect.
+
+#### Wrap Example
+
+```
+Figma:
+  layoutMode: HORIZONTAL
+  layoutWrap: WRAP
+  itemSpacing: 16
+  counterAxisSpacing: 12
+  counterAxisAlignContent: SPACE_BETWEEN
+```
+
+```css
+display: flex;
+flex-direction: row;
+flex-wrap: wrap;
+column-gap: 16px;
+row-gap: 12px;
+align-content: space-between;
+```
+
+---
+
+### 5. Min/Max Constraints
+
+Figma nodes can have min/max size constraints that map directly to CSS:
+
+| Figma Property | CSS Property | Extraction Rule |
+|----------------|--------------|-----------------|
+| `minWidth`     | `min-width`  | Only if > 0     |
+| `maxWidth`     | `max-width`  | Only if < Infinity |
+| `minHeight`    | `min-height` | Only if > 0     |
+| `maxHeight`    | `max-height` | Only if < Infinity |
+
+Constraints apply to both containers and children. They are extracted when the value is meaningful (not zero for min, not infinity for max).
+
+#### Container Constraints
+
+```typescript
+// Extraction: only include non-trivial values
+if (frame.minWidth !== null && frame.minWidth > 0) {
+  layout.minWidth = frame.minWidth;
+}
+if (frame.maxWidth !== null && frame.maxWidth < Infinity) {
+  layout.maxWidth = frame.maxWidth;
+}
+```
+
+```css
+/* Container with constraints */
+.card {
+  display: flex;
+  flex-direction: column;
+  min-width: 200px;
+  max-width: 600px;
+}
+```
+
+#### Child Constraints
+
+Children in Auto Layout also support min/max. Common patterns:
+
+```css
+/* FILL child with max-width — prevents over-expansion */
+.content {
+  flex-grow: 1;
+  flex-basis: 0;
+  max-width: 800px;
+}
+
+/* FILL child with min-width — prevents collapse */
+.sidebar {
+  flex-grow: 1;
+  flex-basis: 0;
+  min-width: 200px;
+}
+```
+
+#### Interaction with Sizing Modes
+
+- **FILL + max constraint**: The element grows to fill available space but caps at max. See Section 2.5 for the counter-axis special case.
+- **FIXED + min constraint**: The element has a fixed size but won't go below min (relevant when `flex-shrink` allows some compression).
+- **HUG + max constraint**: Content-sized but capped — useful for text containers that shouldn't exceed a reading width.
+
+---
+
+### 6. Absolute Position Children
+
+Figma allows placing children with `layoutPositioning: ABSOLUTE` inside an Auto Layout parent. These children are taken out of the Auto Layout flow.
+
+#### CSS Generation
+
+```css
+/* Auto Layout parent automatically becomes positioning context */
+.parent {
+  display: flex;
+  flex-direction: column;
+  position: relative; /* Required for absolute children */
+}
+
+/* Absolutely positioned child within Auto Layout */
+.overlay {
+  position: absolute;
+  /* Offsets derived from constraint-based positioning */
+  top: 8px;
+  right: 8px;
+}
+```
+
+#### Key Rules
+
+1. **Parent needs `position: relative`**: In Figma, the Auto Layout frame is implicitly the positioning context. In CSS, you must add `position: relative` explicitly.
+2. **Child is removed from flex flow**: The absolute child does not participate in flex sizing or gap distribution.
+3. **Offset calculation**: The child's position within the parent is determined by its constraints (see Section 7 for constraint mapping), not by flex ordering.
+
+---
+
+### 7. Non-Auto-Layout Frames (GROUP, Legacy FRAME)
+
+When a frame has `layoutMode: NONE` or the node is a `GROUP`, children are positioned using absolute coordinates and constraints.
+
+#### GROUP Nodes
+
+GROUP nodes have no layout mode. Their children use absolute positioning based on bounds:
+
+```css
+/* GROUP container */
+.group {
+  position: relative;
+  overflow: hidden; /* Matches Figma's default "Clip content" */
+}
+
+/* GROUP children — absolute positioned */
+.group__child {
+  position: absolute;
+  left: 120px;
+  top: 45px;
+  width: 200px;
+  height: 80px;
+}
+```
+
+#### Coordinate System Difference (CRITICAL for GROUPs)
+
+Figma has different coordinate systems for FRAME vs GROUP children:
+
+| Parent Type | Child coordinates (`x`, `y`) are relative to... |
+|-------------|--------------------------------------------------|
+| `FRAME`     | The frame itself (use directly)                  |
+| `GROUP`     | The containing FRAME, not the group              |
+
+For GROUP children, you must **subtract the group's position** to get coordinates relative to the group:
+
+```typescript
+const isGroupParent = parentType === 'GROUP';
+const relativeX = isGroupParent && parentBounds
+  ? bounds.x - parentBounds.x
+  : bounds.x;
+const relativeY = isGroupParent && parentBounds
+  ? bounds.y - parentBounds.y
+  : bounds.y;
+```
+
+#### Legacy FRAME (No Auto Layout)
+
+A FRAME with `layoutMode: NONE` behaves like a GROUP for positioning purposes but uses frame-relative coordinates (no subtraction needed):
+
+```css
+.legacy-frame {
+  position: relative;
+  overflow: hidden;
+}
+
+.legacy-frame__child {
+  position: absolute;
+  left: 50px;
+  top: 30px;
+  width: 300px;
+  height: 150px;
+}
+```
+
+#### Constraint Mapping
+
+Figma's constraint system positions children relative to their parent frame edges. Constraints apply when the parent resizes:
+
+| Figma Constraint | CSS Positioning | Description |
+|------------------|-----------------|-------------|
+| `LEFT`           | `left: Xpx`    | Fixed distance from left edge |
+| `RIGHT`          | `right: Xpx`   | Fixed distance from right edge |
+| `TOP`            | `top: Xpx`     | Fixed distance from top edge |
+| `BOTTOM`         | `bottom: Xpx`  | Fixed distance from bottom edge |
+| `CENTER`         | Centered via `left: 50%; transform: translateX(-50%)` | Centered on axis |
+| `SCALE`          | Percentage-based positioning | Scales proportionally |
+| `LEFT_RIGHT`     | `left: Xpx; right: Ypx` | Stretches horizontally |
+| `TOP_BOTTOM`     | `top: Xpx; bottom: Ypx` | Stretches vertically |
+
+#### Z-Index in Non-Auto-Layout
+
+For absolutely positioned children, later children (higher index in Figma's layer order) render on top:
+
+```css
+.child-0 { z-index: 0; }
+.child-1 { z-index: 1; }
+.child-2 { z-index: 2; }
+```
+
+Z-index is only set when there are multiple children.
+
+---
+
+### 8. Responsive Multi-Frame Pattern
+
+Figma does not have built-in responsive breakpoints. The pattern for responsive design is to create **multiple frames** — one for each breakpoint — and merge them into unified CSS with media queries.
+
+#### Two Approaches for Responsive Grouping
+
+##### Approach A: #Breakpoint Suffix (Preferred)
+
+Frames are grouped by a `#breakpoint` suffix in their name:
+
+```
+Card #mobile    → base styles (smallest)
+Card #tablet    → @media (min-width: 768px)
+Card #desktop   → @media (min-width: 1024px)
+```
+
+Recognized suffix patterns:
+- `"Card - #desktop"` — dash separator
+- `"Card #tablet"` — space separator
+- `"Card(#mobile)"` — parentheses
+- `"Card [#desktop]"` — brackets
+
+The `#` prefix is the strict marker. Only `#mobile`, `#tablet`, `#desktop` are recognized (case-insensitive).
+
+**Classification rules:**
+- A valid responsive group requires **2+ frames** with the same base name and different `#breakpoint` suffixes
+- Frames without `#breakpoint` suffix are treated as standalone layout frames
+- Orphan variants (only one frame for a base name) are treated as standalone layout frames
+- Duplicate breakpoints within the same group are treated as standalone layout frames
+
+##### Approach B: Variant Component Detection
+
+For COMPONENT_SET nodes, responsive variants are detected through variant properties:
+
+**Recognized responsive property names** (case-insensitive):
+- `Device`, `Breakpoint`, `Screen`, `Viewport`, `Responsive`, `Size`
+
+**Value-to-breakpoint mapping:**
+
+| Variant Value | Maps To    |
+|---------------|------------|
+| `mobile`, `phone`, `small`, `sm`, `xs` | `mobile` |
+| `tablet`, `medium`, `md` | `tablet` |
+| `desktop`, `large`, `lg`, `xl` | `desktop` |
+
+Detection requires at least 2 values that map to different standard breakpoint names.
+
+#### Standard Breakpoints (Mobile-First)
+
+| Breakpoint | min-width | max-width | CSS |
+|------------|-----------|-----------|-----|
+| `mobile`   | _(base)_  | 767px     | No media query (base styles) |
+| `tablet`   | 768px     | 1023px    | `@media (min-width: 768px)` |
+| `desktop`  | 1024px    | _(none)_  | `@media (min-width: 1024px)` |
+
+Breakpoint detection also falls back to frame dimensions:
+- Width < 768px → mobile
+- Width 768–1023px → tablet
+- Width >= 1024px → desktop
+
+#### Mobile-First CSS Generation
+
+The smallest frame provides **base styles** (no media query). Larger frames contribute **override styles** wrapped in `@media (min-width: ...)` blocks:
+
+```css
+/* Base styles from mobile frame */
+.card {
+  display: flex;
+  flex-direction: column;
+  gap: 12px;
+  padding: 16px;
+}
+
+.card__title {
+  font-size: 18px;
+}
+
+/* Tablet overrides — only properties that differ */
+@media (min-width: 768px) {
+  .card {
+    flex-direction: row;
+    gap: 24px;
+    padding: 24px;
+  }
+  .card__title {
+    font-size: 22px;
+  }
+}
+
+/* Desktop overrides — only properties that differ from base */
+@media (min-width: 1024px) {
+  .card {
+    gap: 32px;
+    padding: 32px;
+  }
+  .card__title {
+    font-size: 28px;
+  }
+}
+```
+
+#### BEM Suffix Matching
+
+Elements are matched across breakpoint frames using **BEM class suffix matching**. The BEM block name differs between frames (e.g., `.card---mobile` vs `.card---desktop`), but the element/modifier suffix is identical for elements at the same position:
+
+```
+Mobile frame:   .card---mobile           → suffix: ""        (root)
+                .card---mobile__title    → suffix: "__title"
+                .card---mobile__body     → suffix: "__body"
+
+Desktop frame:  .card---desktop          → suffix: ""        (root)
+                .card---desktop__title   → suffix: "__title"
+                .card---desktop__body    → suffix: "__body"
+```
+
+Matching by suffix: `""` matches `""`, `"__title"` matches `"__title"`, etc.
+
+After matching, selectors are remapped to a unified component class: `.card---mobile__title` and `.card---desktop__title` both become `.card__title` in the output.
+
+#### Style Diffing and Overrides
+
+Only **changed properties** are emitted in media query blocks. The diff algorithm:
+
+1. Compare each property in the larger breakpoint against the base
+2. Include properties that are new or have different values
+3. **Reset layout properties** that exist in base but not in the larger breakpoint
+
+Layout properties that need explicit resets to prevent cascade leaking:
+
+| Property      | Reset Value |
+|---------------|-------------|
+| `align-self`  | `auto`      |
+| `flex-grow`   | `0`         |
+| `flex-shrink` | `1`         |
+| `flex-basis`  | `auto`      |
+
+**Example of reset:**
+
+```css
+/* Mobile base: column layout, child stretches */
+.card__image {
+  align-self: stretch;
+  flex-grow: 1;
+  flex-basis: 0;
+}
+
+/* Desktop: row layout, child is fixed — must reset mobile layout props */
+@media (min-width: 1024px) {
+  .card__image {
+    width: 100%;
+    max-width: 277px;
+    align-self: auto;     /* Reset — no longer stretching */
+    flex-grow: 0;         /* Reset — no longer filling */
+    flex-shrink: 1;       /* Reset — back to default */
+    flex-basis: auto;     /* Reset — back to default */
+  }
+}
+```
+
+#### Responsive Width Transformation
+
+Fixed pixel widths in responsive overrides are transformed to a fluid pattern to prevent overflow at intermediate viewport widths:
+
+```css
+/* Before transformation */
+.card__sidebar {
+  width: 277px;
+}
+
+/* After transformation — fluid with cap */
+.card__sidebar {
+  width: 100%;
+  max-width: 277px;
+}
+```
+
+This only applies to responsive override styles (not base styles) and only when no `max-width` is already explicitly set.
+
+---
+
+### 9. Common Pitfalls & Edge Cases
+
+#### Pitfall: Missing `flex-basis: 0` for FILL Items
+
+**Problem:** Without `flex-basis: 0`, FILL children distribute space based on content size, not equally.
+
+**Rule:** FILL on primary axis always requires both `flex-grow: 1` AND `flex-basis: 0`.
+
+```css
+/* CORRECT */
+.fill-child { flex-grow: 1; flex-basis: 0; }
+
+/* WRONG — content-based distribution */
+.fill-child { flex-grow: 1; }
+```
+
+#### Pitfall: STRETCH Only Exists on Counter Axis
+
+**Problem:** Trying to apply STRETCH behavior on the primary axis.
+
+**Rule:** `STRETCH` / `align-self: stretch` only affects the **counter axis**. On the primary axis, expanding behavior is achieved through FILL (`flex-grow: 1; flex-basis: 0`), not stretch.
+
+#### Pitfall: `itemSpacing` Is Not Padding
+
+**Problem:** Confusing `itemSpacing` (gap between children) with `padding` (space around children).
+
+**Rule:** `itemSpacing` → CSS `gap`. Padding uses the separate `paddingTop/Right/Bottom/Left` properties.
+
+#### Pitfall: GROUP Nodes Have No Layout Mode
+
+**Problem:** Treating GROUP children as flex items.
+
+**Rule:** GROUP nodes never have Auto Layout. All GROUP children must use `position: absolute` with coordinates adjusted for the GROUP's coordinate system (subtract parent position).
+
+#### Pitfall: "Auto" in Figma UI Means HUG, Not FILL
+
+**Problem:** When Figma's UI shows "Auto" for width/height, it maps to `HUG` (content-based sizing), not `FILL` (expand to fill).
+
+**Rule:** "Auto" in the Figma UI → `layoutSizingHorizontal: HUG` or `layoutSizingVertical: HUG`. FILL is shown as "Fill container" in the UI.
+
+#### Pitfall: Layout Property Cascade Leaking
+
+**Problem:** In responsive CSS, mobile base styles for `flex-grow`, `flex-basis`, `align-self`, and `flex-shrink` leak into larger breakpoints via the cascade when the desktop layout no longer uses those properties.
+
+**Rule:** When a layout property exists in the base breakpoint but not in a larger breakpoint, explicitly reset it. See Section 8 for the reset values.
+
+#### Edge Case: FILL Counter-Axis + Max Constraint
+
+When a child has FILL on the counter-axis and a max-width/max-height constraint, use `width: 100%` / `height: 100%` instead of `align-self: stretch`. This preserves the parent's ability to position the element with `align-items` when the constraint caps its size. See Section 2.5.
+
+#### Edge Case: Container primaryAxisSizing and counterAxisSizing
+
+The Auto Layout container itself has sizing modes for its own dimensions:
+
+| Property | Value | Meaning |
+|----------|-------|---------|
+| `primaryAxisSizingMode` | `FIXED` | Container has explicit size on primary axis |
+| `primaryAxisSizingMode` | `AUTO` | Container hugs its content on primary axis |
+| `counterAxisSizingMode` | `FIXED` | Container has explicit size on counter axis |
+| `counterAxisSizingMode` | `AUTO` | Container hugs its content on counter axis |
+
+These determine whether the container itself gets an explicit width/height or sizes to content. They are separate from the child-level `layoutSizingHorizontal`/`layoutSizingVertical` properties.
+
+#### Edge Case: Variable Fallback Strategy
+
+When a Figma Variable is from an **external library** (not local to the file), include a pixel fallback in the `var()` expression:
+
+```css
+/* Local variable — no fallback */
+gap: var(--spacing-md);
+
+/* External library variable — include fallback */
+gap: var(--spacing-md, 16px);
+```
+
+This ensures the CSS works even if the variable definition is not available in the consuming project.
+
+---
+
+### Intermediate Type Reference
+
+The complete intermediate types used between extraction and generation:
+
+```typescript
+interface LayoutProperties {
+  mode: 'NONE' | 'FLEX_ROW' | 'FLEX_COL' | 'GRID';
+  primaryAxisSizing: 'FIXED' | 'AUTO';
+  counterAxisSizing: 'FIXED' | 'AUTO';
+  justify: 'flex-start' | 'flex-end' | 'center' | 'space-between';
+  align: 'flex-start' | 'flex-end' | 'center' | 'baseline' | 'stretch';
+  gap: number;
+  gapVariable?: VariableReference;
+  counterAxisGap?: number;
+  counterAxisGapVariable?: VariableReference;
+  padding: {
+    top: number;
+    right: number;
+    bottom: number;
+    left: number;
+  };
+  paddingVariables?: {
+    top?: VariableReference;
+    right?: VariableReference;
+    bottom?: VariableReference;
+    left?: VariableReference;
+  };
+  wrap: boolean;
+  wrapAlign?: 'flex-start' | 'space-between';
+  minWidth?: number;
+  maxWidth?: number;
+  minHeight?: number;
+  maxHeight?: number;
+}
+
+interface LayoutChildProperties {
+  flexGrow: number;
+  alignSelf: 'auto' | 'flex-start' | 'center' | 'flex-end' | 'stretch';
+  sizingHorizontal: 'FIXED' | 'HUG' | 'FILL';
+  sizingVertical: 'FIXED' | 'HUG' | 'FILL';
+  minWidth?: number;
+  maxWidth?: number;
+  minHeight?: number;
+  maxHeight?: number;
+}
+
+interface VariableReference {
+  id: string;
+  name: string;
+  isLocal: boolean;
+}
+```
+
+---
+
+## Cross-References
+
+- **`figma-api-rest.md`** — Node tree structure, `absoluteBoundingBox` for bounds, file/node fetching for accessing layout data via REST API
+- **`figma-api-plugin.md`** — SceneNode types (FrameNode, ComponentNode, InstanceNode, GroupNode), LayoutMixin properties (`layoutMode`, `layoutSizingHorizontal`, `layoutAlign`, `itemSpacing`, etc.), plugin sandbox model for extraction code
+- **`figma-api-variables.md`** — Variables API for resolving `boundVariables` references, variable collections, modes, and the `figma.variables.getVariableByIdAsync()` method used in extraction
+- **`design-to-code-visual.md`** — Visual properties (fills, strokes, effects) that combine with layout for complete component CSS; visual and layout styles are generated independently and merged
+- **`design-to-code-typography.md`** — Text properties that interact with sizing modes (text auto-resize vs layout sizing), vertical alignment requiring flex, styled segments
+- **`design-to-code-assets.md`** — Vector container detection interacts with Auto Layout detection (Auto Layout overrides vector container), asset nodes skip layout child sizing
+- **`design-to-code-semantic.md`** — BEM naming conventions used in responsive matching and class generation, semantic tag selection that consumes layout context
+- **`css-strategy.md`** — Layered CSS approach (Tailwind for layout bones, CSS Modules for visual skin) that consumes layout CSS output. Property placement decision tree for layout properties (Layer 1).