figma-code-agent 1.0.0

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

@@ -0,0 +1,1145 @@
+# Visual Properties → CSS Mapping
+
+## Purpose
+
+Authoritative reference for converting Figma visual properties into CSS. Encodes production-proven mapping rules covering the complete pipeline: extracting fills, strokes, effects, corner radii, gradients, opacity, and blend modes from Figma nodes, transforming them into intermediate types, and generating pixel-accurate CSS. This module covers everything that gives a node its visual appearance beyond layout (which is handled by the layout module).
+
+## When to Use
+
+Reference this module when you need to:
+
+- Convert Figma fills (solid, gradient, image) to CSS `background-color` or `background-image`
+- Map Figma gradient transforms to CSS gradient angles and stop positions
+- Convert Figma strokes (with alignment INSIDE/CENTER/OUTSIDE) to CSS borders or box-shadows
+- Map Figma effects (shadows, blurs) to CSS `box-shadow`, `filter`, and `backdrop-filter`
+- Handle uniform and per-corner border radius with shorthand optimization
+- Apply node-level and fill-level opacity correctly without double-application
+- Resolve Figma variable bindings on visual properties to CSS custom properties
+- Understand the RGB 0-1 to 0-255 conversion and hex normalization
+- Handle multiple fills with correct layer ordering (Figma vs CSS reversal)
+- Generate design tokens from collected visual properties (colors, shadows, radii)
+- Avoid common visual property conversion pitfalls
+
+---
+
+## Content
+
+### 1. Fills → CSS Background
+
+Figma fills are paint layers applied to a node. Each fill has a type (SOLID, gradient variants, IMAGE), visibility, and opacity. Only visible fills should be converted to CSS.
+
+#### Extracted Fill Types
+
+```typescript
+type FillData =
+  | { type: 'SOLID'; color: string; opacity: number; variable?: VariableReference }
+  | { type: 'GRADIENT'; gradient: GradientData }
+  | { type: 'IMAGE'; imageHash: string; scaleMode: string }
+
+interface VariableReference {
+  id: string        // Figma variable ID
+  name: string      // Variable name path (e.g., "color/link/default")
+  isLocal: boolean  // Local to this file vs external library
+}
+```
+
+#### SOLID Fill → CSS
+
+Figma stores RGB channels as floats in the 0-1 range. They must be converted to 0-255 integers for CSS.
+
+**RGB Conversion Formula:**
+
+```
+CSS channel = Math.round(figmaChannel * 255)
+```
+
+**Hex color generation:**
+
+```typescript
+function rgbToHex(color: RGB, opacity: number = 1): string {
+  const { r, g, b } = color
+  if (opacity < 1) {
+    return `rgba(${Math.round(r * 255)}, ${Math.round(g * 255)}, ${Math.round(b * 255)}, ${opacity.toFixed(2)})`
+  }
+  return `#${Math.round(r * 255).toString(16).padStart(2, '0')}${Math.round(g * 255).toString(16).padStart(2, '0')}${Math.round(b * 255).toString(16).padStart(2, '0')}`
+}
+```
+
+| Figma Fill | CSS Output |
+|------------|------------|
+| `{ r: 1, g: 0, b: 0 }`, opacity 1.0 | `background-color: #ff0000` |
+| `{ r: 0.2, g: 0.4, b: 0.6 }`, opacity 0.8 | `background-color: rgba(51, 102, 153, 0.80)` |
+| `{ r: 1, g: 1, b: 1 }`, opacity 1.0 | `background-color: #ffffff` |
+| `{ r: 0, g: 0, b: 0 }`, opacity 0.5 | `background-color: rgba(0, 0, 0, 0.50)` |
+
+**Opacity handling for hex colors:**
+
+When a solid fill has `opacity < 1`, the alpha is embedded in the color value as `rgba()`. This is fill-level opacity, distinct from node-level opacity (see Section 6).
+
+```typescript
+function applyOpacity(hexColor: string, opacity: number): string {
+  if (hexColor.startsWith('rgba')) {
+    return hexColor.replace(/[\d.]+\)$/, `${opacity})`)
+  }
+  const hex = hexColor.replace('#', '')
+  const r = parseInt(hex.substring(0, 2), 16)
+  const g = parseInt(hex.substring(2, 4), 16)
+  const b = parseInt(hex.substring(4, 6), 16)
+  return `rgba(${r}, ${g}, ${b}, ${opacity})`
+}
+```
+
+#### IMAGE Fill → CSS
+
+Image fills reference an `imageHash` that maps to an exported asset file.
+
+| Figma `scaleMode` | CSS `background-size` |
+|--------------------|----------------------|
+| `FILL` (default)   | `cover`              |
+| `FIT`              | `contain`            |
+| `CROP`             | `cover` (with position) |
+| `TILE`             | `auto` (with `background-repeat: repeat`) |
+
+```css
+/* IMAGE fill with FILL scale mode */
+background-image: url(../assets/image-abc123.png);
+background-size: cover;
+background-position: center;
+background-repeat: no-repeat;
+
+/* IMAGE fill with FIT scale mode */
+background-image: url(../assets/image-abc123.png);
+background-size: contain;
+background-position: center;
+background-repeat: no-repeat;
+```
+
+**Fallback:** When an image hash cannot be resolved to a filename, use a placeholder background color:
+
+```css
+background-color: #f0f0f0;
+```
+
+#### Multiple Fills — Layer Order Reversal (CRITICAL)
+
+Figma renders fills **bottom-to-top**: the first fill in the array is the bottom layer (painted first, visually behind). CSS `background` layers render **top-to-bottom**: the first value is the top layer (visually in front).
+
+**Rule: Reverse the fills array when generating CSS.**
+
+```
+Figma fills array:  [fill_0 (bottom), fill_1 (middle), fill_2 (top)]
+CSS backgrounds:    [fill_2 (top),    fill_1 (middle), fill_0 (bottom)]
+```
+
+When layering multiple fills in CSS, solid colors must be converted to `linear-gradient(color, color)` because CSS cannot mix `background-color` with multiple `background-image` layers.
+
+```typescript
+// Multiple fills generation (reversed order)
+const reversedFills = [...fills].reverse()
+const backgroundImages: string[] = []
+
+for (const fill of reversedFills) {
+  if (fill.type === 'SOLID') {
+    // Solid colors become degenerate gradients for layering
+    backgroundImages.push(`linear-gradient(${color}, ${color})`)
+  } else if (fill.type === 'GRADIENT') {
+    backgroundImages.push(generateGradientCSS(fill.gradient))
+  } else if (fill.type === 'IMAGE') {
+    backgroundImages.push(`url(../assets/${filename})`)
+  }
+}
+```
+
+**CSS output for multiple fills:**
+
+```css
+/* Gradient over solid color */
+background-image: linear-gradient(90deg, #ff0000 0%, #0000ff 100%), linear-gradient(#f5f5f5, #f5f5f5);
+background-size: cover, cover;
+background-position: center, center;
+background-repeat: no-repeat, no-repeat;
+```
+
+#### Visibility Filtering
+
+Skip fills where `visible === false`. Figma allows toggling individual fill layer visibility, so always check before processing.
+
+```typescript
+for (const paint of fills) {
+  if (!paint.visible) continue  // Skip invisible fills
+  // ... process fill
+}
+```
+
+#### Mixed Fills on Text Nodes
+
+Text nodes can have `fills === figma.mixed` when different character ranges have different colors. For extraction, use the first character's fill as the dominant color:
+
+```typescript
+if (fills === figma.mixed && node.type === 'TEXT') {
+  const rangeFills = (node as TextNode).getRangeFills(0, 1)
+  if (Array.isArray(rangeFills) && rangeFills.length > 0) {
+    fills = rangeFills
+  }
+}
+```
+
+Full styled-segment support (per-character colors) is handled by the typography module.
+
+---
+
+### 2. Gradient Mapping
+
+Figma supports four gradient types. Each has color stops and a transform matrix that defines the gradient's orientation and shape.
+
+#### Extracted Gradient Types
+
+```typescript
+interface GradientData {
+  type: 'LINEAR' | 'RADIAL' | 'ANGULAR' | 'DIAMOND'
+  stops: Array<{ color: string; position: number }>
+  angle?: number  // Only for LINEAR (calculated from transform matrix)
+}
+```
+
+#### Gradient Type → CSS Function
+
+| Figma Gradient Type | CSS Function | Notes |
+|---------------------|-------------|-------|
+| `GRADIENT_LINEAR`   | `linear-gradient(Ndeg, ...stops)` | Angle from transform matrix |
+| `GRADIENT_RADIAL`   | `radial-gradient(circle, ...stops)` | Figma default is ellipse; `circle` is a safe approximation |
+| `GRADIENT_ANGULAR`  | `conic-gradient(...stops)` | Maps directly to CSS conic |
+| `GRADIENT_DIAMOND`  | `radial-gradient(circle, ...stops)` | No direct CSS equivalent; approximate with radial |
+
+#### Linear Gradient Angle Conversion (The Math)
+
+Figma represents gradient direction using a 2x3 affine transform matrix. The angle must be extracted and converted to CSS conventions.
+
+**Figma transform matrix structure:**
+
+```
+Transform = [[a, c, e], [b, d, f]]
+```
+
+Where `(a, b)` is the unit vector for the gradient direction.
+
+**Coordinate system differences:**
+
+| Property | Figma | CSS |
+|----------|-------|-----|
+| 0 degrees | Left-to-right (positive X) | Bottom-to-top (upward) |
+| Direction | Counter-clockwise | Clockwise |
+| Default horizontal | 0 degrees | 90 degrees |
+
+**Conversion formula:**
+
+```typescript
+function calculateGradientAngle(transform: Transform): number {
+  // Extract gradient direction vector
+  const [[a], [b]] = transform
+
+  // Calculate Figma angle (counter-clockwise from positive X axis)
+  const figmaAngle = Math.atan2(-b, a) * (180 / Math.PI)
+
+  // Convert to CSS angle:
+  // CSS 0deg = up, 90deg = right, 180deg = down, 270deg = left (clockwise)
+  // Figma default horizontal gradient (0deg) should map to CSS 90deg
+  const cssAngle = 90 - figmaAngle
+
+  // Normalize to 0-360 range
+  return Math.round(((cssAngle % 360) + 360) % 360)
+}
+```
+
+**Step-by-step explanation:**
+
+1. Extract the direction vector `(a, b)` from the first column of the transform matrix
+2. Compute the Figma angle using `atan2(-b, a)` — the negation of `b` accounts for Figma's Y-axis direction
+3. Convert from Figma's convention (0 degrees = right, counter-clockwise) to CSS convention (0 degrees = up, clockwise) by computing `90 - figmaAngle`
+4. Normalize the result to the 0-360 degree range using modular arithmetic
+
+**Common angle examples:**
+
+| Figma Transform (a, b) | Figma Angle | CSS Angle | Visual Direction |
+|-------------------------|-------------|-----------|-----------------|
+| `(1, 0)` | 0 degrees | 90deg | Left to right |
+| `(0, -1)` | 90 degrees | 0deg | Bottom to top |
+| `(-1, 0)` | 180 degrees | 270deg | Right to left |
+| `(0, 1)` | -90 degrees | 180deg | Top to bottom |
+
+#### Color Stop Formatting
+
+Figma stop positions are 0-1 floats. CSS expects percentages.
+
+```typescript
+const stops = gradient.stops
+  .map(stop => `${stop.color} ${Math.round(stop.position * 100)}%`)
+  .join(', ')
+```
+
+| Figma Stop | CSS Stop |
+|------------|----------|
+| `{ color: '#ff0000', position: 0 }` | `#ff0000 0%` |
+| `{ color: '#0000ff', position: 0.5 }` | `#0000ff 50%` |
+| `{ color: '#00ff00', position: 1 }` | `#00ff00 100%` |
+
+#### Complete Gradient CSS Generation
+
+```typescript
+function generateGradientCSS(gradient: GradientData): string {
+  const stops = gradient.stops
+    .map(stop => `${stop.color} ${Math.round(stop.position * 100)}%`)
+    .join(', ')
+
+  switch (gradient.type) {
+    case 'LINEAR': {
+      const angle = gradient.angle ?? 180
+      return `linear-gradient(${angle}deg, ${stops})`
+    }
+    case 'RADIAL':
+      return `radial-gradient(circle, ${stops})`
+    case 'ANGULAR':
+      return `conic-gradient(${stops})`
+    case 'DIAMOND':
+      // No direct CSS equivalent — approximate with radial
+      return `radial-gradient(circle, ${stops})`
+    default:
+      return `linear-gradient(180deg, ${stops})`
+  }
+}
+```
+
+**CSS output examples:**
+
+```css
+/* Linear gradient, 45 degrees */
+background-image: linear-gradient(45deg, #ff0000 0%, #0000ff 100%);
+
+/* Radial gradient */
+background-image: radial-gradient(circle, #ffffff 0%, #000000 100%);
+
+/* Conic/angular gradient */
+background-image: conic-gradient(#ff0000 0%, #00ff00 33%, #0000ff 66%, #ff0000 100%);
+```
+
+#### Gradient Text
+
+When a text node has a gradient fill, use the gradient-text technique:
+
+```css
+background-image: linear-gradient(90deg, #ff0000 0%, #0000ff 100%);
+background-clip: text;
+-webkit-background-clip: text;
+color: transparent;
+```
+
+---
+
+### 3. Strokes → CSS Border / Box-Shadow
+
+Figma strokes have color, weight, alignment, and optional per-side weights. The stroke alignment determines which CSS property to use.
+
+#### Extracted Stroke Type
+
+```typescript
+interface StrokeData {
+  color: string                  // Hex or rgba string
+  opacity: number                // 0-1
+  weight: number                 // Uniform weight (0 if per-side)
+  align: 'INSIDE' | 'OUTSIDE' | 'CENTER'
+  weights?: {                    // Per-side weights (if different)
+    top: number
+    right: number
+    bottom: number
+    left: number
+  }
+}
+```
+
+#### Stroke Alignment → CSS Property
+
+Figma's stroke alignment determines where the stroke sits relative to the node boundary. Each alignment needs a different CSS approach.
+
+| Figma `strokeAlign` | CSS Approach | Rationale |
+|---------------------|-------------|-----------|
+| `CENTER` | `border: Wpx solid color` | CSS `border` is painted centered on the edge (default CSS behavior) |
+| `INSIDE` | `box-shadow: inset 0 0 0 Wpx color` | Inset shadow doesn't change element dimensions, unlike `border` which adds to width/height |
+| `OUTSIDE` | `box-shadow: 0 0 0 Wpx color` or `outline: Wpx solid color` | Outset shadow or outline paints outside without affecting layout |
+
+> **Important:** CSS `border` adds to the element's rendered dimensions (unless `box-sizing: border-box` is set). Figma's INSIDE stroke does NOT change the frame's dimensions. Using `box-shadow: inset` for INSIDE strokes preserves dimensional accuracy.
+
+**CENTER stroke (default approach):**
+
+```css
+/* Figma: strokeAlign CENTER, weight 2px, color #333333 */
+border: 2px solid #333333;
+```
+
+**INSIDE stroke (use inset box-shadow):**
+
+```css
+/* Figma: strokeAlign INSIDE, weight 2px, color #333333 */
+box-shadow: inset 0 0 0 2px #333333;
+```
+
+**OUTSIDE stroke (use outset box-shadow or outline):**
+
+```css
+/* Figma: strokeAlign OUTSIDE, weight 2px, color #333333 */
+box-shadow: 0 0 0 2px #333333;
+/* Alternative: */
+outline: 2px solid #333333;
+```
+
+> **Implementation note:** A simpler approach maps all strokes to `border`. The box-shadow approach for INSIDE/OUTSIDE is the recommended production pattern for pixel-accurate results.
+
+#### Per-Side Stroke Weights
+
+Figma supports different stroke weights per side via `strokeTopWeight`, `strokeRightWeight`, `strokeBottomWeight`, `strokeLeftWeight`. These are available on frames and components.
+
+```typescript
+// Detection: per-side weights exist when strokeWeight is mixed
+// or when individual side weights differ from each other
+if (stroke.weights) {
+  const { top, right, bottom, left } = stroke.weights
+  if (top > 0) styles.borderTop = `${top}px solid ${color}`
+  if (right > 0) styles.borderRight = `${right}px solid ${color}`
+  if (bottom > 0) styles.borderBottom = `${bottom}px solid ${color}`
+  if (left > 0) styles.borderLeft = `${left}px solid ${color}`
+} else if (stroke.weight > 0) {
+  styles.border = `${stroke.weight}px solid ${color}`
+}
+```
+
+**CSS output for per-side strokes:**
+
+```css
+/* Only bottom border (common for underlines, dividers) */
+border-bottom: 2px solid #e0e0e0;
+
+/* Different top and bottom (card with header accent) */
+border-top: 4px solid #1a73e8;
+border-bottom: 1px solid #e0e0e0;
+```
+
+#### Dash Patterns
+
+Figma's `strokeDashPattern` defines a dash-gap array (e.g., `[10, 5]` means 10px dash, 5px gap). CSS approximation:
+
+| Figma `strokeDashPattern` | CSS `border-style` |
+|---------------------------|-------------------|
+| `[]` (empty/none) | `solid` |
+| `[dash, gap]` | `dashed` |
+| `[1, gap]` (dot pattern) | `dotted` |
+
+CSS `dashed` and `dotted` do not support custom dash lengths. For exact dash patterns, SVG `stroke-dasharray` is required.
+
+#### Stroke Visibility and Type Filtering
+
+Only solid, visible strokes are processed during extraction:
+
+```typescript
+for (const paint of strokes) {
+  if (!paint.visible || paint.type !== 'SOLID') continue
+  // ... extract stroke data
+}
+```
+
+Gradient strokes and image strokes are not supported in CSS border — they require SVG or more complex CSS workarounds (e.g., border-image).
+
+---
+
+### 4. Effects → CSS Shadows & Filters
+
+Figma effects include shadows and blurs. Each effect has a type, visibility, and type-specific properties.
+
+#### Extracted Effect Types
+
+```typescript
+type EffectData =
+  | { type: 'DROP_SHADOW'; offset: { x: number; y: number }; radius: number; spread: number; color: string }
+  | { type: 'INNER_SHADOW'; offset: { x: number; y: number }; radius: number; spread: number; color: string }
+  | { type: 'BLUR'; radius: number }
+  | { type: 'BACKGROUND_BLUR'; radius: number }
+```
+
+#### Effect Type → CSS Property
+
+| Figma Effect Type | CSS Property | CSS Syntax |
+|-------------------|-------------|------------|
+| `DROP_SHADOW` | `box-shadow` | `Xpx Ypx Rpx Spx color` |
+| `INNER_SHADOW` | `box-shadow` (inset) | `inset Xpx Ypx Rpx Spx color` |
+| `LAYER_BLUR` | `filter` | `blur(Rpx)` |
+| `BACKGROUND_BLUR` | `backdrop-filter` | `blur(Rpx)` |
+
+#### DROP_SHADOW → box-shadow
+
+```css
+/* Figma: DROP_SHADOW { offset: {x: 0, y: 4}, radius: 8, spread: 0, color: rgba(0,0,0,0.25) } */
+box-shadow: 0px 4px 8px 0px rgba(0, 0, 0, 0.25);
+```
+
+Parameter mapping:
+
+| Figma Property | CSS `box-shadow` Position | Description |
+|----------------|--------------------------|-------------|
+| `offset.x` | 1st value | Horizontal offset |
+| `offset.y` | 2nd value | Vertical offset |
+| `radius` | 3rd value (blur-radius) | Gaussian blur radius |
+| `spread` | 4th value (spread-radius) | Expand/contract shadow; defaults to 0 in Figma |
+| `color` | 5th value | Shadow color with alpha |
+
+#### INNER_SHADOW → box-shadow inset
+
+Same parameters as DROP_SHADOW but with the `inset` keyword prepended:
+
+```css
+/* Figma: INNER_SHADOW { offset: {x: 0, y: 2}, radius: 4, spread: 0, color: rgba(0,0,0,0.10) } */
+box-shadow: inset 0px 2px 4px 0px rgba(0, 0, 0, 0.10);
+```
+
+#### LAYER_BLUR → filter: blur()
+
+Layer blur applies a Gaussian blur to the entire element and its contents.
+
+```css
+/* Figma: LAYER_BLUR { radius: 8 } */
+filter: blur(8px);
+```
+
+#### BACKGROUND_BLUR → backdrop-filter: blur()
+
+Background blur blurs the content behind the element (used for frosted glass effects). Requires the element to have a semi-transparent background.
+
+```css
+/* Figma: BACKGROUND_BLUR { radius: 20 } */
+backdrop-filter: blur(20px);
+-webkit-backdrop-filter: blur(20px);  /* Safari support */
+```
+
+> **Browser support note:** `backdrop-filter` is widely supported but older browsers may need the `-webkit-` prefix. Always include both for cross-browser compatibility.
+
+#### Multiple Effects
+
+A single node can have multiple effects of different types. They combine in CSS according to their property:
+
+- **Multiple shadows** (drop + inner): comma-separated in a single `box-shadow` declaration
+- **Multiple filters**: space-separated in a single `filter` declaration
+- **backdrop-filter**: only one `backdrop-filter` value per element
+
+```typescript
+function generateEffectStyles(effects: EffectData[]): CSSStyles {
+  const shadows: string[] = []
+  const filters: string[] = []
+
+  for (const effect of effects) {
+    if (effect.type === 'DROP_SHADOW') {
+      shadows.push(`${effect.offset.x}px ${effect.offset.y}px ${effect.radius}px ${effect.spread}px ${effect.color}`)
+    } else if (effect.type === 'INNER_SHADOW') {
+      shadows.push(`inset ${effect.offset.x}px ${effect.offset.y}px ${effect.radius}px ${effect.spread}px ${effect.color}`)
+    } else if (effect.type === 'BLUR') {
+      filters.push(`blur(${effect.radius}px)`)
+    } else if (effect.type === 'BACKGROUND_BLUR') {
+      styles.backdropFilter = `blur(${effect.radius}px)`
+    }
+  }
+
+  if (shadows.length > 0) {
+    styles.boxShadow = shadows.join(', ')
+  }
+  if (filters.length > 0) {
+    styles.filter = filters.join(' ')
+  }
+}
+```
+
+**CSS output with multiple effects:**
+
+```css
+/* Drop shadow + inner shadow combined */
+box-shadow: 0px 4px 12px 0px rgba(0, 0, 0, 0.15), inset 0px 1px 2px 0px rgba(0, 0, 0, 0.06);
+
+/* Blur filter */
+filter: blur(4px);
+
+/* Frosted glass: backdrop blur + semi-transparent background */
+backdrop-filter: blur(20px);
+-webkit-backdrop-filter: blur(20px);
+background-color: rgba(255, 255, 255, 0.70);
+```
+
+#### Effect Visibility Filtering
+
+Like fills, effects have a `visible` property. Always check before processing:
+
+```typescript
+for (const effect of effects) {
+  if (!effect.visible) continue  // Skip toggled-off effects
+  // ... process effect
+}
+```
+
+---
+
+### 5. Corner Radius
+
+Corner radius controls the rounding of a node's corners. Figma supports both uniform and per-corner values.
+
+#### Extracted Corner Radius Type
+
+```typescript
+type CornerRadius = number | {
+  topLeft: number
+  topRight: number
+  bottomRight: number
+  bottomLeft: number
+}
+```
+
+- `number` — Uniform radius applied to all four corners
+- `object` — Per-corner radii (Figma returns this when `cornerRadius === figma.mixed`)
+
+#### Uniform Radius → CSS
+
+When all corners share the same value:
+
+```css
+/* Figma: cornerRadius = 8 */
+border-radius: 8px;
+```
+
+#### Per-Corner Radius → CSS
+
+When corners have different values, Figma returns individual properties (`topLeftRadius`, `topRightRadius`, `bottomRightRadius`, `bottomLeftRadius`):
+
+```css
+/* Figma: TL=8, TR=8, BR=0, BL=0 (rounded top only) */
+border-radius: 8px 8px 0px 0px;
+
+/* Figma: TL=16, TR=0, BR=16, BL=0 (diagonal corners) */
+border-radius: 16px 0px 16px 0px;
+```
+
+**CSS shorthand order:** `top-left top-right bottom-right bottom-left` (clockwise from top-left).
+
+#### Shorthand Optimization
+
+When extracting per-corner radii, check if all four values are equal. If so, use the shorter uniform syntax:
+
+```typescript
+function generateCornerRadiusStyles(cornerRadius: CornerRadius): CSSStyles {
+  if (typeof cornerRadius === 'number') {
+    if (cornerRadius > 0) {
+      return { borderRadius: `${cornerRadius}px` }
+    }
+    return {}
+  }
+
+  const { topLeft, topRight, bottomRight, bottomLeft } = cornerRadius
+  // Optimize: if all corners equal, use shorthand
+  if (topLeft === topRight && topRight === bottomRight && bottomRight === bottomLeft) {
+    if (topLeft > 0) return { borderRadius: `${topLeft}px` }
+    return {}
+  }
+  // Otherwise use full four-value syntax
+  return { borderRadius: `${topLeft}px ${topRight}px ${bottomRight}px ${bottomLeft}px` }
+}
+```
+
+#### Circle Detection
+
+When `border-radius` equals or exceeds half the element's smallest dimension, the element becomes circular (or pill-shaped for rectangles):
+
+```css
+/* Circle: radius >= min(width, height) / 2 */
+border-radius: 50%;
+
+/* Pill shape: large radius on a rectangle */
+border-radius: 9999px;
+```
+
+> **Detection heuristic:** If `cornerRadius >= min(width, height) / 2`, consider using `border-radius: 50%` for circles or `border-radius: 9999px` for pill shapes. The 9999px approach is commonly used because it works regardless of element dimensions.
+
+#### Zero and Undefined Radius
+
+| Value | Meaning | CSS Output |
+|-------|---------|------------|
+| `cornerRadius` not present on node | No rounding capability | No `border-radius` property |
+| `cornerRadius === 0` | Explicitly no rounding | No `border-radius` property (omit) |
+| `cornerRadius === undefined` (extracted) | No radius data | No `border-radius` property (omit) |
+
+Both `0` and `undefined` result in no CSS output. Do not emit `border-radius: 0px` — it is redundant.
+
+#### Variable Bindings for Radius
+
+Corner radius values can be bound to Figma variables (see Section 7 for the general pattern). When a variable is bound:
+
+```css
+/* Variable-bound radius */
+border-radius: var(--radius-md);
+
+/* With token lookup fallback */
+border-radius: var(--radius-md, 8px);
+```
+
+---
+
+### 6. Opacity & Blend Modes
+
+#### Node-Level Opacity
+
+Every Figma node has an `opacity` property (0-1 float). Only emit CSS when opacity is less than 1:
+
+```typescript
+function generateOpacityStyles(opacity: number): CSSStyles {
+  if (opacity < 1) {
+    return { opacity: String(opacity) }
+  }
+  return {}
+}
+```
+
+```css
+/* Figma: opacity = 0.5 */
+opacity: 0.5;
+```
+
+#### Fill-Level Opacity
+
+Individual fills have their own opacity. This is embedded in the color's alpha channel, NOT as a separate CSS property:
+
+```
+Node opacity = 0.8     →  CSS: opacity: 0.8
+Fill opacity = 0.5     →  CSS: background-color: rgba(R, G, B, 0.5)
+```
+
+These are independent — they do NOT combine into a single CSS property.
+
+#### Opacity Compounding (Visual Result)
+
+The visual opacity of a fill is the product of node-level and fill-level opacity:
+
+```
+Visual opacity = node.opacity * fill.opacity
+```
+
+However, in CSS they are expressed separately:
+
+```css
+/* Node opacity 0.8, fill opacity 0.5 */
+/* Visual result: 0.8 * 0.5 = 0.4 effective opacity */
+opacity: 0.8;
+background-color: rgba(255, 0, 0, 0.5);
+```
+
+> **Warning:** Do NOT multiply them together into a single property. CSS `opacity` affects the entire element and all its children, while fill alpha only affects that specific background layer.
+
+#### Blend Modes
+
+Figma's `blendMode` property maps to CSS `mix-blend-mode`. Most Figma blend modes have direct CSS equivalents:
+
+| Figma `blendMode` | CSS `mix-blend-mode` |
+|--------------------|---------------------|
+| `NORMAL` | `normal` (default, omit) |
+| `MULTIPLY` | `multiply` |
+| `SCREEN` | `screen` |
+| `OVERLAY` | `overlay` |
+| `DARKEN` | `darken` |
+| `LIGHTEN` | `lighten` |
+| `COLOR_DODGE` | `color-dodge` |
+| `COLOR_BURN` | `color-burn` |
+| `HARD_LIGHT` | `hard-light` |
+| `SOFT_LIGHT` | `soft-light` |
+| `DIFFERENCE` | `difference` |
+| `EXCLUSION` | `exclusion` |
+| `HUE` | `hue` |
+| `SATURATION` | `saturation` |
+| `COLOR` | `color` |
+| `LUMINOSITY` | `luminosity` |
+
+**Figma-only blend modes** (no direct CSS equivalent):
+
+| Figma `blendMode` | CSS Approximation |
+|--------------------|-------------------|
+| `PASS_THROUGH` | `normal` (default for groups; children blend independently) |
+| `LINEAR_DODGE` | No equivalent (approximate with `screen`) |
+| `LINEAR_BURN` | No equivalent (approximate with `multiply`) |
+
+```css
+/* Figma: blendMode MULTIPLY */
+mix-blend-mode: multiply;
+
+/* For backgrounds specifically */
+background-blend-mode: overlay;
+```
+
+> **When to use which:** `mix-blend-mode` blends the element with content below it. `background-blend-mode` blends multiple background layers within the same element.
+
+---
+
+### 7. Variable Binding for Visual Properties
+
+Figma Variables allow designers to bind property values to named tokens. When a visual property is variable-bound, the CSS output should use `var()` instead of raw values.
+
+#### Variable Resolution Pipeline
+
+```
+Figma Variable ID → Variable Lookup → Variable Name → CSS Variable Name → var() Reference
+```
+
+**Name conversion:** Figma uses `/` as path separator (e.g., `color/link/default`). CSS uses `-` (e.g., `--color-link-default`).
+
+```typescript
+function figmaVariableToCssName(variableName: string): string {
+  return '--' + variableName
+    .toLowerCase()
+    .replace(/\//g, '-')      // Slashes to dashes
+    .replace(/\s+/g, '-')     // Spaces to dashes
+    .replace(/[^a-z0-9-_]/g, '') // Remove invalid chars
+}
+```
+
+| Figma Variable Name | CSS Variable |
+|---------------------|-------------|
+| `color/link/default` | `--color-link-default` |
+| `color/background/primary` | `--color-background-primary` |
+| `spacing/lg` | `--spacing-lg` |
+| `radius/md` | `--radius-md` |
+
+#### Paint-Level Variable Binding (Primary)
+
+Figma binds variables at the paint (fill) level. Each paint object can have `boundVariables.color.id`:
+
+```typescript
+// Check paint-level binding first (preferred)
+const paintBoundVars = (paint as any).boundVariables
+if (paintBoundVars && paintBoundVars.color && paintBoundVars.color.id) {
+  const variable = await lookupVariable(paintBoundVars.color.id)
+  // variable.name → "color/link/default"
+}
+```
+
+#### Node-Level Variable Binding (Fallback)
+
+Some Figma API versions expose bindings at the node level instead of (or in addition to) the paint level:
+
+```typescript
+// Fallback: check node-level binding
+const boundVars = (node as any).boundVariables
+if (boundVars && boundVars.fills) {
+  // Multiple possible structures:
+  // 1. Array: boundVars.fills[index] = { id: 'VariableID:xxx' }
+  // 2. Nested: boundVars.fills[index] = { color: { id: 'VariableID:xxx' } }
+  // 3. Object: boundVars.fills = { '0': { ... } }
+}
+```
+
+**Resolution order:**
+1. Paint-level `paint.boundVariables.color.id` (preferred)
+2. Node-level `node.boundVariables.fills[index].id` (fallback)
+3. Node-level `node.boundVariables.fills[index].color.id` (alternate structure)
+4. Node-level `node.boundVariables.fill.id` (singular form, some API versions)
+
+#### Local vs External Library Variables
+
+Variables can be local (defined in the same file) or from an external library. This affects fallback strategy:
+
+```typescript
+function lookupFillColor(fill: FillData): ColorLookupResult {
+  if (fill.variable && fill.variable.name) {
+    const cssVarName = figmaVariableToCssName(fill.variable.name)
+
+    if (fill.variable.isLocal) {
+      // Local variable: no fallback needed (defined in our tokens.css)
+      return { value: `var(${cssVarName})` }
+    }
+
+    // External library variable: include raw value as fallback
+    return {
+      value: `var(${cssVarName}, ${fill.color})`,
+      comment: `/* fallback: "${fill.variable.name}" is from external library */`
+    }
+  }
+  // No variable: use raw color
+  return { value: fill.color }
+}
+```
+
+**CSS output:**
+
+```css
+/* Local variable — no fallback needed */
+background-color: var(--color-primary);
+
+/* External library variable — include fallback */
+background-color: var(--color-link-default, #1a73e8); /* fallback: "color/link/default" is from external library */
+```
+
+#### Variables on Other Visual Properties
+
+The same variable binding pattern applies to:
+
+| Property | Variable Path | CSS Variable Example |
+|----------|-------------|---------------------|
+| Fill color | `paint.boundVariables.color` | `var(--color-primary)` |
+| Stroke color | `paint.boundVariables.color` | `var(--color-border-default)` |
+| Corner radius | `node.boundVariables.cornerRadius` | `var(--radius-md)` |
+| Effect color | `effect.boundVariables.color` | `var(--color-shadow)` |
+
+#### Token Lookup (Value-Based Resolution)
+
+When no variable binding exists, colors can still be mapped to tokens via reverse lookup. The token system collects all colors, assigns semantic names, and creates a lookup map:
+
+```typescript
+// Build lookup: raw color value → CSS variable reference
+const lookup: TokenLookup = {
+  colors: new Map([
+    ['#1a73e8', 'var(--color-primary)'],
+    ['#333333', 'var(--color-neutral-800)'],
+  ]),
+  radii: new Map([
+    [8, 'var(--radius-md)'],
+    [16, 'var(--radius-lg)'],
+  ]),
+}
+
+// Usage: resolve raw value to token
+function lookupColor(lookup: TokenLookup, value: string): string {
+  const normalized = value.toLowerCase()
+  return lookup.colors.get(normalized) || value
+}
+```
+
+**Hex normalization is critical:** Always lowercase hex values before lookup to ensure `#1A73E8` matches `#1a73e8`.
+
+---
+
+### 8. Common Pitfalls
+
+#### RGB 0-1 Float Range (NOT 0-255)
+
+Figma's RGB channels are **0-1 floats**, not 0-255 integers. This is the single most common conversion bug.
+
+```typescript
+// WRONG: Using Figma values directly
+`rgb(${color.r}, ${color.g}, ${color.b})`  // rgb(0.2, 0.4, 0.6) — INVALID
+
+// CORRECT: Multiply by 255 and round
+`rgb(${Math.round(color.r * 255)}, ${Math.round(color.g * 255)}, ${Math.round(color.b * 255)})`
+```
+
+#### Fill Order Reversal
+
+Figma paints fills **bottom-to-top** (index 0 = bottom layer). CSS paints backgrounds **top-to-bottom** (first value = top layer). Forgetting to reverse causes layers to appear in the wrong visual order.
+
+```typescript
+// WRONG: Using Figma order directly
+const backgrounds = fills.map(f => toCSS(f))
+
+// CORRECT: Reverse for CSS order
+const backgrounds = [...fills].reverse().map(f => toCSS(f))
+```
+
+#### INSIDE Stroke Dimension Impact
+
+CSS `border` adds to the element's rendered dimensions. Figma's INSIDE stroke does not change the frame's bounding box. Using `border` for INSIDE strokes causes elements to be larger than designed.
+
+```css
+/* WRONG for INSIDE stroke: */
+border: 2px solid #333;  /* Element is now 4px wider and taller */
+
+/* CORRECT for INSIDE stroke: */
+box-shadow: inset 0 0 0 2px #333;  /* No dimension change */
+```
+
+#### cornerRadius: undefined vs 0
+
+Both `undefined` (property not present) and `0` (explicitly zero) mean no rounding. Do not emit `border-radius: 0px` — it is redundant and adds unnecessary CSS.
+
+```typescript
+// WRONG: Emitting zero radius
+if (cornerRadius !== undefined) {
+  styles.borderRadius = `${cornerRadius}px`  // Emits "border-radius: 0px"
+}
+
+// CORRECT: Skip zero and undefined
+if (cornerRadius !== undefined && cornerRadius !== 0) {
+  // Only emit when there is actual rounding
+}
+```
+
+#### Gradient Angle Mismatch
+
+Figma's 0 degrees is **not** CSS's 0 degrees. Directly using the Figma angle in CSS produces a rotated gradient.
+
+```css
+/* Figma says 0° (horizontal, left-to-right) */
+
+/* WRONG: */
+linear-gradient(0deg, ...)  /* CSS 0° = bottom-to-top */
+
+/* CORRECT: Apply conversion formula */
+linear-gradient(90deg, ...)  /* CSS 90° = left-to-right */
+```
+
+Always use the `calculateGradientAngle()` conversion with the transform matrix, not any raw "angle" value from Figma.
+
+#### Opacity Compounding
+
+Node opacity and fill opacity are independent in CSS. Do not multiply them into a single value.
+
+```css
+/* Figma: node opacity 0.8, fill with rgba(255,0,0,0.5) */
+
+/* WRONG: Combined opacity */
+opacity: 0.4;
+background-color: #ff0000;
+
+/* CORRECT: Separate opacity sources */
+opacity: 0.8;
+background-color: rgba(255, 0, 0, 0.5);
+```
+
+#### Invisible Fills and Effects
+
+Figma allows toggling individual fill layers and effects on/off via the `visible` property. Always check visibility before processing:
+
+```typescript
+// WRONG: Processing all fills
+for (const fill of fills) { /* ... */ }
+
+// CORRECT: Filter invisible fills
+for (const fill of fills) {
+  if (!fill.visible) continue
+  // ... process fill
+}
+```
+
+#### Mixed Stroke Weight Handling
+
+When `strokeWeight === figma.mixed`, individual side weights exist. Do not treat `figma.mixed` as a number — it will cause NaN in CSS output.
+
+```typescript
+// WRONG: Using strokeWeight directly
+styles.border = `${node.strokeWeight}px solid ${color}`  // May produce "Symbol(mixed)px"
+
+// CORRECT: Check for mixed first
+if (node.strokeWeight === figma.mixed) {
+  // Use per-side weights: strokeTopWeight, strokeRightWeight, etc.
+} else {
+  styles.border = `${node.strokeWeight}px solid ${color}`
+}
+```
+
+#### Hex Normalization for Token Lookup
+
+Colors must be normalized before looking up in the token map. Figma may return `#1A73E8` but the token was stored as `#1a73e8`.
+
+```typescript
+// WRONG: Direct lookup
+lookup.colors.get(fill.color)  // Misses due to case mismatch
+
+// CORRECT: Normalize first
+lookup.colors.get(fill.color.toLowerCase())
+```
+
+---
+
+### 9. Color Token Integration
+
+Colors extracted from visual properties can be promoted to design tokens for reuse across the generated codebase. This section covers how the pipeline collects, names, and emits color tokens.
+
+#### Color Collection
+
+All colors are collected from a node tree by traversing fills, strokes, and effects. Each unique color (after normalization) is tracked with its usage count.
+
+```typescript
+// Sources of colors:
+// 1. Solid fills → fill.color
+// 2. Strokes → stroke.color
+// 3. Shadow effects → effect.color
+// (Gradient stops are skipped in v1)
+```
+
+#### Semantic Color Naming
+
+Colors are assigned semantic names based on HSL analysis:
+
+| HSL Range | Semantic | CSS Variable Pattern |
+|-----------|----------|---------------------|
+| Saturation < 10% | `neutral` | `--color-neutral-{100-900}` (by lightness) |
+| Hue 0-20 or 340-360 | `error` | `--color-error` |
+| Hue 30-60 | `warning` | `--color-warning` |
+| Hue 90-150 | `success` | `--color-success` |
+| Most-used saturated color | `primary` | `--color-primary` |
+| Second most-used saturated | `secondary` | `--color-secondary` |
+| Remaining saturated | `accent` | `--color-accent`, `--color-accent-2`, ... |
+
+**Neutral scale:** Maps lightness to a 100-900 scale (inverted: 100 = lightest, 900 = darkest):
+
+```typescript
+const step = Math.round((1 - lightness / 100) * 8 + 1) * 100
+// Lightness 95% → step 100 (near white)
+// Lightness 50% → step 500 (medium gray)
+// Lightness 5%  → step 900 (near black)
+```
+
+#### Effect Token Naming
+
+Shadows and radii are also promoted to tokens using a size scale:
+
+```
+Shadows: --shadow-sm, --shadow-md, --shadow-lg, --shadow-xl, --shadow-2xl
+Radii:   --radius-sm, --radius-md, --radius-lg, --radius-xl, --radius-full
+```
+
+Shadow tokens are ordered by blur radius (smallest = `sm`). Radius tokens are ordered by pixel value.
+
+---
+
+### 10. Complete Visual Style Generation
+
+All visual properties are generated together and merged into a single CSS object:
+
+```typescript
+function generateVisualStyles(
+  fills: FillData[] | undefined,
+  strokes: StrokeData[] | undefined,
+  effects: EffectData[] | undefined,
+  cornerRadius: CornerRadius | undefined,
+  opacity: number,
+  lookup?: TokenLookup
+): CSSStyles {
+  return {
+    ...generateBackgroundStyles(fills, lookup),
+    ...generateBorderStyles(strokes, lookup),
+    ...generateCornerRadiusStyles(cornerRadius, lookup),
+    ...generateEffectStyles(effects),
+    ...generateOpacityStyles(opacity),
+  }
+}
+```
+
+**Complete CSS output example:**
+
+```css
+/* A card component with all visual properties */
+background-color: var(--color-neutral-100);
+border: 1px solid var(--color-neutral-300);
+border-radius: var(--radius-lg);
+box-shadow: 0px 2px 8px 0px rgba(0, 0, 0, 0.08);
+opacity: 0.95;
+```
+
+---
+
+## Cross-References
+
+- **`figma-api-rest.md`** — Node visual properties in the REST API response (`fills`, `strokes`, `effects`, `cornerRadius`, `opacity`, `blendMode`)
+- **`figma-api-variables.md`** — Variables API for resolving variable bindings (`boundVariables`, variable collections, modes)
+- **`design-to-code-layout.md`** — Companion module for layout (Auto Layout → Flexbox); visual and layout styles are generated independently and merged
+- **`design-to-code-typography.md`** — Text-specific fill handling (styled segments, per-character colors)
+- **`design-to-code-assets.md`** — Image asset resolution for IMAGE fills (export settings, deduplication, file naming), visual styles skipped for exported asset nodes
+- **`design-to-code-semantic.md`** — Semantic tag selection that determines whether visual styles are applied (skipped for `<img>` tags from vector containers), gradient text rendering integration
+- **`css-strategy.md`** — How visual CSS integrates with the layered CSS strategy (Tailwind + Custom Properties + CSS Modules). Property placement decision tree for visual properties (Layer 3).
+- **`design-tokens.md`** — Token extraction and promotion rules for colors, shadows, and radii collected from visual properties. HSL-based semantic color naming. Token lookup integration during CSS generation.