figma-code-agent 1.0.0

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

@@ -0,0 +1,1003 @@
+# Text Extraction & CSS Typography
+
+## Purpose
+
+Authoritative reference for extracting Figma text properties and generating accurate CSS typography. Encodes production-proven mapping rules covering the complete pipeline: extracting font families, weights, sizes, line heights, letter spacing, alignment, decoration, and text case from Figma TextNodes, handling mixed-style (rich text) segments with per-character styling and hyperlinks, and generating pixel-accurate CSS. This module covers everything needed to convert a Figma TEXT node into correct HTML and CSS.
+
+## When to Use
+
+Reference this module when you need to:
+
+- Convert a Figma `fontFamily` to a CSS `font-family` with appropriate fallback stack
+- Map Figma font style names ("Semi Bold", "Bold Italic") to numeric CSS `font-weight`
+- Convert Figma line height (percentage or pixel) to unitless CSS `line-height` ratio
+- Handle Figma `letterSpacing` in pixels and percentages
+- Map Figma text alignment (horizontal and vertical) to CSS properties
+- Convert `textDecoration` and `textCase` to CSS `text-decoration` and `text-transform`
+- Map `textAutoResize` behavior to CSS wrapping and overflow properties
+- Extract and render multi-style text (styled segments with different colors, weights, sizes)
+- Handle hyperlinks within text segments (`<a href="...">`)
+- Generate ordered and unordered list HTML from Figma list metadata
+- Apply typography token lookup for CSS custom property substitution
+- Generate Google Fonts URLs from collected font data
+- Avoid common typography conversion pitfalls (line height %, "Regular" weight, mixed-style nodes)
+
+---
+
+## Content
+
+### 1. Font Family Mapping
+
+Figma stores the font family as a `fontFamily` string property on TextNode (e.g., `"Inter"`, `"Roboto Mono"`, `"SF Pro Display"`). This must be converted to a CSS `font-family` declaration with an appropriate fallback stack.
+
+#### Extraction
+
+```typescript
+// From Figma TextNode
+const fontFamily: string = textNode.fontName.family
+// e.g., "Inter", "Roboto", "Fira Code", "Georgia"
+```
+
+When `fontName` is `figma.mixed` (the node has multiple fonts), extract the first character's font as the dominant family:
+
+```typescript
+let fontName: FontName
+if (typeof textNode.fontName === 'symbol') {
+  // Mixed fonts - use first character as dominant
+  fontName = textNode.getRangeFontName(0, 1) as FontName
+} else {
+  fontName = textNode.fontName
+}
+```
+
+#### CSS Generation
+
+**Default (no token lookup):** Wrap in quotes and add a generic fallback:
+
+```css
+font-family: 'Inter', sans-serif;
+font-family: 'Roboto Mono', monospace;
+font-family: 'Georgia', serif;
+```
+
+**With token lookup:** If a font family token exists, use the CSS custom property:
+
+```css
+font-family: var(--font-primary);
+font-family: var(--font-mono);
+```
+
+#### Fallback Stack Selection
+
+| Font Category | Detection | Fallback |
+|---------------|-----------|----------|
+| Sans-serif | Default assumption | `sans-serif` |
+| Monospace | Name contains "mono", "code", "consolas", "courier", "menlo", etc. | `monospace` |
+| Serif | Name contains "serif", "georgia", "times", "garamond", "baskerville" | `serif` |
+
+#### Monospace Font Detection
+
+The following font name patterns indicate a monospace font:
+
+```
+mono, code, consolas, courier, fira code, jetbrains, menlo,
+monaco, source code, ubuntu mono, sf mono, roboto mono, ibm plex mono
+```
+
+Detection is case-insensitive substring matching against the font family name.
+
+#### System Fonts
+
+System fonts are already available on the user's OS and should NOT be loaded from Google Fonts. Common system fonts:
+
+```
+Arial, Helvetica, Helvetica Neue, Times, Times New Roman, Georgia,
+Verdana, Tahoma, Courier, Courier New, Lucida Console, Monaco,
+Segoe UI, SF Pro, SF Pro Display, SF Pro Text, system-ui, -apple-system,
+Optima, Futura, Avenir, Avenir Next, Gill Sans, Baskerville, Didot,
+Consolas, Menlo, Palatino, Garamond, Century Gothic, Arial Black
+```
+
+#### Google Fonts URL Generation
+
+For non-system fonts, generate a Google Fonts `<link>` URL:
+
+```
+https://fonts.googleapis.com/css2?family=Inter:wght@400;600;700&family=Roboto+Mono:wght@400&display=swap
+```
+
+**Rules:**
+- Group variants by family
+- Include all used weights per family
+- Append `italic` suffix for italic variants (e.g., `700italic`)
+- Replace spaces with `+` in family names
+- Always add `display=swap` for performance
+- Exclude system fonts from the URL
+
+---
+
+### 2. Font Weight from Style String
+
+Figma does not store font weight as a number. Instead, it uses a style name string (e.g., `"Regular"`, `"Bold"`, `"Semi Bold"`, `"Bold Italic"`). This must be parsed into a numeric CSS `font-weight`.
+
+#### Weight Mapping Table
+
+| Figma Style Name | CSS `font-weight` | Notes |
+|------------------|-------------------|-------|
+| `Thin` | `100` | Hairline weight |
+| `ExtraLight` | `200` | Also "Ultra Light" |
+| `Light` | `300` | |
+| `Regular` | `400` | Default. **NOT** output as `font-weight: regular` |
+| `Medium` | `500` | |
+| `SemiBold` | `600` | Also "Semi Bold", "Demi Bold" |
+| `Bold` | `700` | |
+| `ExtraBold` | `800` | Also "Ultra Bold" |
+| `Black` | `900` | Also "Heavy" |
+
+#### Extraction Logic
+
+The style-to-weight mapping uses substring matching to handle compound styles:
+
+```typescript
+function styleToWeight(style: string): number {
+  const weightMap: Record<string, number> = {
+    'Thin': 100,
+    'ExtraLight': 200,
+    'Light': 300,
+    'Regular': 400,
+    'Medium': 500,
+    'SemiBold': 600,
+    'Bold': 700,
+    'ExtraBold': 800,
+    'Black': 900,
+  }
+
+  // Handle compound styles like "Bold Italic"
+  for (const [name, weight] of Object.entries(weightMap)) {
+    if (style.includes(name)) return weight
+  }
+  return 400 // Default to regular
+}
+```
+
+**Key behavior:** The loop checks in insertion order. "ExtraBold" is checked before "Bold", and "ExtraLight" before "Light", preventing false matches on compound names.
+
+#### Italic Detection
+
+Italic is detected separately from weight by checking if the style string contains "Italic":
+
+```typescript
+if (text.font.style.toLowerCase().includes('italic')) {
+  styles.fontStyle = 'italic'
+}
+```
+
+#### Combined Style Examples
+
+| Figma Style | CSS Output |
+|-------------|------------|
+| `"Regular"` | `font-weight: 400;` |
+| `"Bold"` | `font-weight: 700;` |
+| `"Bold Italic"` | `font-weight: 700; font-style: italic;` |
+| `"SemiBold Italic"` | `font-weight: 600; font-style: italic;` |
+| `"Light"` | `font-weight: 300;` |
+| `"Thin Italic"` | `font-weight: 100; font-style: italic;` |
+
+#### Token Integration
+
+With token lookup, weight maps to a CSS variable:
+
+```css
+/* Without tokens */
+font-weight: 700;
+
+/* With tokens */
+font-weight: var(--font-bold);
+```
+
+Token names follow the pattern `--font-{weightName}`:
+
+| Weight | Token Name |
+|--------|------------|
+| 100 | `--font-thin` |
+| 200 | `--font-extralight` |
+| 300 | `--font-light` |
+| 400 | `--font-regular` |
+| 500 | `--font-medium` |
+| 600 | `--font-semibold` |
+| 700 | `--font-bold` |
+| 800 | `--font-extrabold` |
+| 900 | `--font-black` |
+
+---
+
+### 3. Font Size
+
+Figma stores `fontSize` as a number in pixels (e.g., `16`, `24`, `48`).
+
+#### Extraction
+
+```typescript
+let fontSize: number
+if (typeof textNode.fontSize === 'symbol') {
+  // Mixed sizes - use first character's size
+  fontSize = textNode.getRangeFontSize(0, 1) as number
+} else {
+  fontSize = textNode.fontSize
+}
+```
+
+#### CSS Generation
+
+**Default:** Direct pixel output:
+
+```css
+font-size: 16px;
+font-size: 24px;
+```
+
+**With token lookup:** Map to a CSS variable using a type scale:
+
+```css
+font-size: var(--text-base);   /* 16px */
+font-size: var(--text-lg);     /* 18px */
+font-size: var(--text-2xl);    /* 24px */
+```
+
+#### Type Scale Naming
+
+Font size tokens use a T-shirt size scale centered on a "base" size (the collected size closest to 16px):
+
+| Scale Name | Position Relative to Base |
+|------------|--------------------------|
+| `--text-xs` | base - 2 |
+| `--text-sm` | base - 1 |
+| `--text-base` | base (closest to 16px) |
+| `--text-lg` | base + 1 |
+| `--text-xl` | base + 2 |
+| `--text-2xl` | base + 3 |
+| `--text-3xl` | base + 4 |
+| `--text-4xl` | base + 5 |
+| `--text-5xl` | base + 6 |
+| `--text-6xl` | base + 7 |
+
+If a size falls outside the scale range, it uses `--text-{px}` (e.g., `--text-72`).
+
+---
+
+### 4. Line Height Conversion (Critical)
+
+Line height is one of the most error-prone Figma-to-CSS conversions. Figma stores line height in multiple units, and all must be converted to **unitless CSS ratios** for correct scaling.
+
+#### Figma Line Height Units
+
+| Figma `lineHeight.unit` | Figma Value | Meaning |
+|--------------------------|-------------|---------|
+| `AUTO` | N/A | Browser default line height |
+| `PERCENT` | e.g., `150` | 150% of font size |
+| `PIXELS` | e.g., `24` | Fixed 24px line height |
+
+#### Conversion Rules
+
+```typescript
+function getLineHeight(lineHeight: LineHeight | symbol, fontSize: number): number | 'auto' {
+  if (typeof lineHeight === 'symbol') return 'auto'  // figma.mixed
+  if (lineHeight.unit === 'AUTO') return 'auto'
+  if (lineHeight.unit === 'PERCENT') {
+    // Percentage → unitless ratio: 150% → 1.5
+    return lineHeight.value / 100
+  }
+  // PIXELS → unitless ratio: 24px on 16px font → 1.5
+  return lineHeight.value / fontSize
+}
+```
+
+#### Critical: Percentage Means % of Font Size
+
+In Figma, a line height of "150%" means **150% of the font size**, not 150% of some other dimension. A 16px font with 150% line height has a computed line height of 24px.
+
+**Conversion formula:** `lineHeightPercentage / 100 = unitless ratio`
+
+- 120% -> `line-height: 1.2`
+- 150% -> `line-height: 1.5`
+- 200% -> `line-height: 2`
+
+#### Critical: Always Use Unitless Ratios in CSS
+
+**Why unitless?** Unitless `line-height` scales correctly when `font-size` changes (e.g., responsive scaling, user zoom). Pixel or percentage `line-height` in CSS does NOT scale.
+
+```css
+/* CORRECT — unitless ratio, scales with font-size */
+line-height: 1.50;
+
+/* AVOID — fixed pixel value, does not scale */
+line-height: 24px;
+
+/* AVOID — percentage in CSS behaves differently than in Figma */
+line-height: 150%;
+```
+
+#### CSS Generation
+
+```typescript
+if (text.lineHeight === 'auto') {
+  styles.lineHeight = 'normal'
+} else {
+  styles.lineHeight = text.lineHeight.toFixed(2)
+}
+```
+
+| Figma Line Height | Font Size | CSS Output |
+|-------------------|-----------|------------|
+| AUTO | any | `line-height: normal;` |
+| 150% | 16px | `line-height: 1.50;` |
+| 120% | 16px | `line-height: 1.20;` |
+| 24px | 16px | `line-height: 1.50;` |
+| 144px | 128px | `line-height: 1.13;` |
+
+---
+
+### 5. Letter Spacing
+
+Figma stores `letterSpacing` with a unit (PIXELS or PERCENT) and a numeric value.
+
+#### Extraction
+
+```typescript
+function getLetterSpacing(letterSpacing: LetterSpacing | symbol): number {
+  if (typeof letterSpacing === 'symbol') return 0  // figma.mixed
+  if (letterSpacing.unit === 'PERCENT') {
+    // Percentage of font size - returned as raw value for CSS gen
+    return letterSpacing.value
+  }
+  return letterSpacing.value  // PIXELS
+}
+```
+
+#### CSS Generation
+
+**Pixel values:** Output directly:
+
+```css
+letter-spacing: 0.5px;
+letter-spacing: -0.2px;
+```
+
+**Percentage values:** Figma percentage letter spacing is relative to font size. In CSS, this maps to `em` units:
+
+```css
+/* Figma: 5% letter spacing on any font size */
+letter-spacing: 0.05em;
+
+/* Figma: -2% letter spacing */
+letter-spacing: -0.02em;
+```
+
+**Zero or near-zero:** Omit the property entirely:
+
+```typescript
+if (text.letterSpacing !== 0) {
+  styles.letterSpacing = `${text.letterSpacing}px`
+}
+```
+
+---
+
+### 6. Text Alignment
+
+Figma text nodes have both horizontal and vertical alignment.
+
+#### Horizontal Alignment
+
+| Figma `textAlignHorizontal` | CSS `text-align` |
+|-----------------------------|------------------|
+| `LEFT` | `left` |
+| `CENTER` | `center` |
+| `RIGHT` | `right` |
+| `JUSTIFIED` | `justify` |
+
+Extraction maps directly to CSS-ready values:
+
+```typescript
+function mapHorizontalAlign(align: string): 'left' | 'center' | 'right' | 'justify' {
+  const map: Record<string, string> = {
+    'LEFT': 'left',
+    'CENTER': 'center',
+    'RIGHT': 'right',
+    'JUSTIFIED': 'justify',
+  }
+  return map[align] || 'left'
+}
+```
+
+#### Vertical Alignment
+
+Figma text nodes support vertical alignment within their bounding box. This requires flexbox in CSS because `vertical-align` only works on inline/table elements.
+
+| Figma `textAlignVertical` | CSS Output |
+|---------------------------|------------|
+| `TOP` | _(omit - default)_ |
+| `CENTER` | `display: flex; align-items: center;` |
+| `BOTTOM` | `display: flex; align-items: flex-end;` |
+
+```typescript
+if (text.align.vertical !== 'top') {
+  styles.display = 'flex'
+  styles.alignItems = text.align.vertical === 'center' ? 'center' : 'flex-end'
+}
+```
+
+**Warning:** Adding `display: flex` to a text element for vertical alignment can conflict with the text's natural inline layout. This is an acceptable trade-off for fixed-dimension text boxes with vertical centering, but be aware of potential interaction with `text-align` (which still works on flex items via `justify-content` or `text-align` on the flex item's text content).
+
+---
+
+### 7. Text Decoration & Transform
+
+#### Text Decoration
+
+Figma uses `textDecoration` with values `NONE`, `UNDERLINE`, and `STRIKETHROUGH`.
+
+| Figma `textDecoration` | CSS `text-decoration` |
+|------------------------|-----------------------|
+| `NONE` | _(omit)_ |
+| `UNDERLINE` | `underline` |
+| `STRIKETHROUGH` | `line-through` |
+
+```typescript
+if (text.decoration !== 'none') {
+  styles.textDecoration = text.decoration === 'strikethrough'
+    ? 'line-through'
+    : text.decoration
+}
+```
+
+**Note:** Figma's `STRIKETHROUGH` maps to CSS `line-through`, not `strikethrough`. This is a common mapping error.
+
+When `textDecoration` is `figma.mixed` (the symbol type), default to `'none'`:
+
+```typescript
+function mapDecoration(decoration: string | symbol): 'none' | 'underline' | 'strikethrough' {
+  if (typeof decoration === 'symbol') return 'none'  // figma.mixed
+  const map = { 'NONE': 'none', 'UNDERLINE': 'underline', 'STRIKETHROUGH': 'strikethrough' }
+  return map[decoration] || 'none'
+}
+```
+
+#### Text Transform (Case)
+
+Figma uses `textCase` with values `ORIGINAL`, `UPPER`, `LOWER`, and `TITLE`.
+
+| Figma `textCase` | CSS `text-transform` |
+|-------------------|---------------------|
+| `ORIGINAL` | _(omit)_ |
+| `UPPER` | `uppercase` |
+| `LOWER` | `lowercase` |
+| `TITLE` | `capitalize` |
+
+```typescript
+if (text.textCase !== 'none') {
+  styles.textTransform = text.textCase
+}
+```
+
+The extraction maps `ORIGINAL` to `'none'`, which is then omitted from CSS output.
+
+---
+
+### 8. Text Auto-Resize Behavior
+
+Figma's `textAutoResize` property controls how a text node's bounding box responds to its content. This maps to CSS wrapping, overflow, and sizing behavior.
+
+#### Mapping Table
+
+| Figma `textAutoResize` | Behavior | CSS Output |
+|-------------------------|----------|------------|
+| `WIDTH_AND_HEIGHT` | Text box resizes both dimensions to fit content. Single line, no wrapping. | `white-space: nowrap;` |
+| `HEIGHT` | Width is fixed, height grows to fit. Text wraps at fixed width. | _(default CSS behavior - no extra properties)_ |
+| `NONE` | Both dimensions are fixed. Text may overflow or clip. | `overflow: hidden;` (may add `width` and `height`) |
+| `TRUNCATE` | Fixed dimensions with ellipsis on overflow. | `overflow: hidden; text-overflow: ellipsis; white-space: nowrap;` |
+
+#### CSS Generation
+
+```typescript
+// WIDTH_AND_HEIGHT: single-line text, no wrap
+if (text.textAutoResize === 'WIDTH_AND_HEIGHT') {
+  styles.whiteSpace = 'nowrap'
+}
+
+// TRUNCATE: ellipsis overflow
+if (text.textAutoResize === 'TRUNCATE') {
+  styles.overflow = 'hidden'
+  styles.textOverflow = 'ellipsis'
+  styles.whiteSpace = 'nowrap'
+}
+
+// NONE: fixed dimensions, clip overflow
+if (text.textAutoResize === 'NONE') {
+  styles.overflow = 'hidden'
+}
+
+// HEIGHT: default wrapping behavior, no extra CSS needed
+```
+
+#### Interaction with Layout Sizing
+
+`textAutoResize` interacts with the parent Auto Layout's sizing modes:
+
+- **WIDTH_AND_HEIGHT** in a FILL container: The `white-space: nowrap` prevents wrapping, but `flex-grow: 1` still allows the text to claim available space. The text will not wrap even if the container is narrower.
+- **HEIGHT** in a FILL container: The text width fills the container and wraps normally. This is the most common scenario for body text.
+- **TRUNCATE** in a fixed-width container: Ellipsis appears when text overflows the fixed width.
+
+---
+
+### 9. Styled Text Segments (Rich Text)
+
+Figma supports per-character styling within a single TEXT node. A heading might have one word in bold and another in a different color. This is handled through **styled segments** -- ranges of characters with their own styling properties.
+
+#### When Styled Segments Are Needed
+
+Segment extraction is triggered when any of these conditions are true:
+
+```typescript
+const hasMixedFills = typeof textNode.fills === 'symbol'     // Different colors
+const hasMixedFont = typeof textNode.fontName === 'symbol'   // Different fonts
+const hasMixedSize = typeof textNode.fontSize === 'symbol'   // Different sizes
+const hasMixedWeight = typeof textNode.fontWeight === 'symbol' // Different weights
+const hasLinks = hasHyperlinks(textNode)                      // Hyperlinks present
+```
+
+If none of these conditions are true, the text node has uniform styling and styled segments are not extracted (the node-level properties are sufficient).
+
+#### Extraction via getStyledTextSegments
+
+Figma's `getStyledTextSegments` API returns segments with consistent styling:
+
+```typescript
+const segments = textNode.getStyledTextSegments([
+  'fills',
+  'fontName',
+  'fontSize',
+  'fontWeight',
+  'letterSpacing',
+  'lineHeight',
+  'textDecoration',
+  'textCase',
+  'hyperlink',
+])
+```
+
+Each segment contains:
+- `start` / `end` -- character indices
+- `characters` -- the text content
+- `fills` -- array of paint fills for this segment
+- `fontName` -- `{ family, style }` for this segment
+- `fontSize` -- size for this segment
+- `hyperlink` -- `{ type: 'URL' | 'NODE', value: string }` if linked
+
+#### Intermediate Type
+
+```typescript
+interface StyledSegment {
+  start: number
+  end: number
+  text: string
+  fills?: Array<{ color: string; opacity?: number; variable?: VariableReference }>
+  font?: {
+    family: string
+    style: string
+    size: number
+    weight: number
+  }
+  letterSpacing?: number
+  lineHeight?: number | 'auto'
+  decoration?: 'none' | 'underline' | 'strikethrough'
+  textCase?: 'none' | 'uppercase' | 'lowercase' | 'capitalize'
+  hyperlink?: HyperlinkData
+}
+
+interface HyperlinkData {
+  type: 'URL' | 'NODE'
+  value: string
+}
+```
+
+#### HTML Generation for Styled Segments
+
+Each segment becomes a `<span>` (or `<a>` for hyperlinks) with only the properties that differ from the base text style:
+
+```html
+<!-- Base style on parent element -->
+<p class="hero__heading" style="font-family: 'Inter', sans-serif; font-size: 48px; font-weight: 700;">
+  <!-- Segment with different color -->
+  <span class="hero__heading__segment-1" style="color: #1A1A1A;">Build </span>
+  <!-- Segment with different color and weight -->
+  <span class="hero__heading__segment-2" style="color: #6366F1; font-weight: 800;">beautiful </span>
+  <!-- Segment matching base - still wrapped for consistency -->
+  <span class="hero__heading__segment-3" style="color: #1A1A1A;">interfaces</span>
+</p>
+```
+
+#### Hyperlink Segments
+
+When a segment has a hyperlink, it renders as an `<a>` tag instead of `<span>`:
+
+```html
+<p class="footer__text">
+  <span class="footer__text__segment-1">Read our </span>
+  <a class="footer__text__segment-2" href="https://example.com/privacy"
+     target="_blank" rel="noopener noreferrer">privacy policy</a>
+  <span class="footer__text__segment-3"> for details.</span>
+</p>
+```
+
+**Nested anchor prevention:** If the text node itself is already rendered as an `<a>` tag (e.g., from semantic name detection like "link-with-icon"), hyperlink segments render as `<span>` instead of `<a>` to avoid invalid nested anchor elements.
+
+#### Hyperlink Detection
+
+```typescript
+function hasHyperlinks(textNode: TextNode): boolean {
+  // Uniform hyperlink (all text is linked)
+  if (textNode.hyperlink && typeof textNode.hyperlink !== 'symbol') {
+    return true
+  }
+  // Mixed hyperlinks (some ranges are linked)
+  if (typeof textNode.hyperlink === 'symbol') {
+    return true
+  }
+  return false
+}
+```
+
+Hyperlinks can be of two types:
+- `URL` -- external web link (`{ type: 'URL', value: 'https://...' }`)
+- `NODE` -- internal Figma node link (`{ type: 'NODE', value: 'nodeId' }`) -- typically not converted to HTML href
+
+#### Variable Binding on Segment Colors
+
+Styled segments can have Figma Variables bound to their fill colors. The extraction resolves these asynchronously:
+
+```typescript
+const variable = await extractPaintVariableAsync(fill)
+// Returns: { id: string, name: string, isLocal: boolean } | undefined
+```
+
+When a variable is present, the CSS uses `var()` instead of a raw hex value:
+
+```css
+/* Local variable */
+color: var(--color-link-default);
+
+/* External library variable (with fallback) */
+color: var(--color-brand-primary, #6366F1);
+```
+
+---
+
+### 10. List Styles
+
+Figma text nodes can contain list formatting. The `listOptions` property on the text node indicates the list type.
+
+#### Detection
+
+```typescript
+const listOptions = (textNode as any).listOptions
+if (listOptions && typeof listOptions !== 'symbol') {
+  if (listOptions.type === 'ORDERED') {
+    textData.listStyle = 'ordered'
+  } else if (listOptions.type === 'UNORDERED') {
+    textData.listStyle = 'unordered'
+  }
+}
+```
+
+**Note:** `listOptions` may not be available in all Figma API contexts. The extraction wraps access in a try/catch.
+
+#### HTML Generation
+
+List text is split by newlines, and each line becomes a `<li>`:
+
+```typescript
+if (node.text.listStyle) {
+  const lines = node.text.content.split(/\r?\n/).filter(line => line.trim())
+  const listTag = node.text.listStyle === 'ordered' ? 'ol' : 'ul'
+
+  const listItems = lines.map((line, index) => ({
+    tag: 'li',
+    className: `${className}__item-${index + 1}`,
+    children: [line.trim()],
+  }))
+
+  // Wrap in list container
+  children.push({
+    tag: listTag,
+    className: `${className}__list`,
+    children: listItems,
+  })
+}
+```
+
+#### Generated HTML Examples
+
+**Unordered list:**
+
+```html
+<div class="features__text">
+  <ul class="features__text__list">
+    <li class="features__text__item-1">Fast performance</li>
+    <li class="features__text__item-2">Easy to use</li>
+    <li class="features__text__item-3">Beautiful design</li>
+  </ul>
+</div>
+```
+
+**Ordered list:**
+
+```html
+<div class="steps__text">
+  <ol class="steps__text__list">
+    <li class="steps__text__item-1">Create your account</li>
+    <li class="steps__text__item-2">Choose a template</li>
+    <li class="steps__text__item-3">Publish your site</li>
+  </ol>
+</div>
+```
+
+---
+
+### 11. Typography Token Integration
+
+The typography token system collects font families, sizes, and weights from the entire extracted node tree and generates semantic CSS custom property names.
+
+#### Token Collection
+
+The `collectTypography` function traverses the ExtractedNode tree and collects:
+
+- **Font families** -- unique family names with usage counts
+- **Font sizes** -- unique pixel sizes with usage counts
+- **Font weights** -- unique numeric weights with usage counts
+
+```typescript
+interface TypographyTokens {
+  families: FontFamilyToken[]  // e.g., [{ name: '--font-primary', value: 'Inter', usageCount: 42 }]
+  sizes: FontSizeToken[]      // e.g., [{ name: '--text-base', value: 16, usageCount: 28 }]
+  weights: FontWeightToken[]  // e.g., [{ name: '--font-bold', value: 700, usageCount: 15 }]
+}
+```
+
+#### Font Family Token Naming
+
+Families are named based on their role:
+
+| Role | Detection | Token Name |
+|------|-----------|------------|
+| Primary | Most-used font family | `--font-primary` |
+| Monospace | Name matches monospace patterns | `--font-mono` |
+| Secondary | Second font (first non-primary) | `--font-secondary` |
+| Others | Remaining fonts by index | `--font-family-{n}` |
+
+#### Font Size Token Naming
+
+Sizes use the type scale (Section 3) with the "base" position anchored to the collected size closest to 16px.
+
+**Example collected sizes:** `[12, 14, 16, 18, 24, 32, 48]`
+
+| Size | Scale Position | Token Name |
+|------|---------------|------------|
+| 12px | base - 2 | `--text-xs` |
+| 14px | base - 1 | `--text-sm` |
+| 16px | base (closest to 16) | `--text-base` |
+| 18px | base + 1 | `--text-lg` |
+| 24px | base + 2 | `--text-xl` |
+| 32px | base + 3 | `--text-2xl` |
+| 48px | base + 4 | `--text-3xl` |
+
+#### Font Weight Token Naming
+
+Weights use standard CSS weight names:
+
+| Weight | Token Name |
+|--------|------------|
+| 100 | `--font-thin` |
+| 200 | `--font-extralight` |
+| 300 | `--font-light` |
+| 400 | `--font-regular` |
+| 500 | `--font-medium` |
+| 600 | `--font-semibold` |
+| 700 | `--font-bold` |
+| 800 | `--font-extrabold` |
+| 900 | `--font-black` |
+
+Non-standard weights (e.g., 450) use `--font-weight-{n}`.
+
+#### Token Lookup During Generation
+
+During CSS generation, raw values are checked against the token lookup map:
+
+```typescript
+// Font family lookup
+styles.fontFamily = lookupFontFamily(lookup, text.font.family)
+// Returns: var(--font-primary) if found, else 'Inter', sans-serif
+
+// Font size lookup
+styles.fontSize = lookupFontSize(lookup, text.font.size)
+// Returns: var(--text-lg) if found, else '18px'
+
+// Font weight lookup
+styles.fontWeight = lookupFontWeight(lookup, text.font.weight)
+// Returns: var(--font-bold) if found, else '700'
+```
+
+#### Generated CSS with Tokens
+
+```css
+/* Without tokens */
+.heading {
+  font-family: 'Inter', sans-serif;
+  font-size: 32px;
+  font-weight: 700;
+  line-height: 1.25;
+}
+
+/* With tokens */
+.heading {
+  font-family: var(--font-primary);
+  font-size: var(--text-2xl);
+  font-weight: var(--font-bold);
+  line-height: 1.25;
+}
+```
+
+---
+
+### 12. Common Pitfalls
+
+#### Pitfall: Line Height Percentage Misinterpretation
+
+**Problem:** Figma's 150% line height is treated as CSS `line-height: 150%` instead of `line-height: 1.5`.
+
+**Rule:** Always convert Figma line height percentages to unitless ratios by dividing by 100. Figma's percentage means "% of font size", which is exactly what a unitless CSS `line-height` ratio represents. Never output `line-height: 150%` from Figma data.
+
+```css
+/* CORRECT */
+line-height: 1.50;
+
+/* WRONG */
+line-height: 150%;
+line-height: 24px;
+```
+
+#### Pitfall: "Regular" Is Not a CSS Font Weight
+
+**Problem:** Outputting `font-weight: regular` instead of `font-weight: 400`.
+
+**Rule:** The Figma style name "Regular" must be mapped to the numeric value `400`. CSS `font-weight` only accepts numbers (100-900) or keywords (`normal`, `bold`, `lighter`, `bolder`). The word "regular" is not valid CSS.
+
+#### Pitfall: Mixed-Style Nodes Need Segment Extraction
+
+**Problem:** Reading `textNode.fontName` on a node with mixed fonts returns `figma.mixed` (a Symbol), not a FontName object. Treating it as a string or object causes runtime errors.
+
+**Rule:** Always check `typeof textNode.fontName === 'symbol'` before accessing `.family` or `.style`. When mixed, either:
+1. Use `getRangeFontName(0, 1)` for the dominant style
+2. Extract styled segments for per-character accuracy
+
+The same applies to `fontSize`, `fills`, `fontWeight`, `letterSpacing`, `lineHeight`, `textDecoration`, and `textCase` -- all can be `figma.mixed`.
+
+#### Pitfall: Vertical Alignment Requires Flex
+
+**Problem:** Setting `vertical-align: middle` on a block-level text element (it only works on inline or table cells).
+
+**Rule:** Figma's vertical text alignment (CENTER, BOTTOM) requires `display: flex` with `align-items` on the text element. This is the only reliable cross-browser approach for vertically aligning text within a fixed-height container.
+
+```css
+/* CORRECT - vertical center */
+display: flex;
+align-items: center;
+text-align: left;
+
+/* WRONG */
+vertical-align: middle;
+```
+
+#### Pitfall: Flex on Text Conflicts with Inline Content
+
+**Problem:** Adding `display: flex` for vertical alignment changes the text element from block/inline to flex container, which can affect how inline children (spans, links) are laid out.
+
+**Rule:** When a text node has both vertical alignment (CENTER/BOTTOM) and styled segments, the flex container will lay out the `<span>` children as flex items. This is generally acceptable because text spans naturally flow inline-like within a flex container with `flex-wrap: wrap`, but test with long mixed-style text.
+
+#### Pitfall: Strikethrough Mapping
+
+**Problem:** Using CSS `text-decoration: strikethrough` (not valid CSS).
+
+**Rule:** Figma's `STRIKETHROUGH` maps to CSS `text-decoration: line-through`. The extraction stores the intermediate value as `'strikethrough'` and the generation step converts it:
+
+```typescript
+styles.textDecoration = text.decoration === 'strikethrough' ? 'line-through' : text.decoration
+```
+
+#### Pitfall: Text Color Comes from Fills, Not a Color Property
+
+**Problem:** Looking for a `color` property on Figma text nodes.
+
+**Rule:** Figma text nodes use the `fills` array for their text color, the same way non-text nodes use fills for background color. For text nodes, the first SOLID fill becomes `color` (not `background-color`):
+
+```typescript
+if (node.text && node.fills && node.fills.length > 0) {
+  const fill = node.fills[0]
+  if (fill.type === 'SOLID') {
+    styles.color = fill.color  // Text color, NOT background
+  } else if (fill.type === 'GRADIENT') {
+    // Gradient text uses background-clip technique
+    styles.backgroundImage = gradientCSS
+    styles.backgroundClip = 'text'
+    styles.WebkitBackgroundClip = 'text'
+    styles.color = 'transparent'
+  }
+}
+```
+
+#### Pitfall: Gradient Text Requires Special CSS
+
+**Problem:** Applying a gradient fill to text as `background-color`.
+
+**Rule:** Gradient text in CSS requires the `background-clip: text` technique:
+
+```css
+.gradient-text {
+  background-image: linear-gradient(90deg, #6366F1 0%, #EC4899 100%);
+  background-clip: text;
+  -webkit-background-clip: text;
+  color: transparent;
+}
+```
+
+#### Edge Case: Paragraph Spacing
+
+Figma's `paragraphSpacing` (space between paragraphs separated by newlines) does not have a direct CSS equivalent. When present and non-zero, it can be approximated with `margin-bottom` on paragraph elements or `padding-bottom` on line groups, but this requires splitting text at paragraph boundaries.
+
+#### Edge Case: Single Segment Optimization
+
+If `getStyledTextSegments` returns only one segment and there are no hyperlinks, the styled segments are discarded and the node-level properties are used instead. This avoids unnecessary `<span>` wrapping for uniformly-styled text.
+
+---
+
+### Intermediate Type Reference
+
+The complete intermediate type used between extraction and generation:
+
+```typescript
+interface TextData {
+  content: string
+  font: {
+    family: string   // e.g., "Inter"
+    style: string    // e.g., "Bold Italic"
+    size: number     // e.g., 16
+    weight: number   // e.g., 700
+  }
+  align: {
+    horizontal: 'left' | 'center' | 'right' | 'justify'
+    vertical: 'top' | 'center' | 'bottom'
+  }
+  letterSpacing: number        // In pixels (0 = omit)
+  lineHeight: number | 'auto'  // Unitless ratio or 'auto'
+  paragraphSpacing: number     // Pixels between paragraphs
+  decoration: 'none' | 'underline' | 'strikethrough'
+  textCase: 'none' | 'uppercase' | 'lowercase' | 'capitalize'
+  textAutoResize?: 'NONE' | 'WIDTH_AND_HEIGHT' | 'HEIGHT' | 'TRUNCATE'
+  listStyle?: 'ordered' | 'unordered'
+  styledSegments?: StyledSegment[]
+}
+```
+
+---
+
+## Cross-References
+
+- **`figma-api-rest.md`** -- Node text properties in REST API response (`characters`, `style` object with font family/weight/size), text node type identification
+- **`figma-api-plugin.md`** -- TextNode API, `fontName`, `fontSize`, `textAlignHorizontal/Vertical`, `textAutoResize`, `getStyledTextSegments()`, `getRangeFontName()`, `getRangeHyperlink()`, `hyperlink`, `listOptions`, `figma.mixed` handling
+- **`figma-api-variables.md`** -- Variable resolution for text fill colors, `figma.variables.getVariableByIdAsync()`, `boundVariables` on SolidPaint fills, local vs external variable handling
+- **`design-to-code-layout.md`** -- Parent Auto Layout context that determines text sizing behavior (FILL width, HUG height), flex container interaction with vertical text alignment
+- **`design-to-code-visual.md`** -- Fill extraction patterns shared with text color extraction (SOLID, GRADIENT), RGB-to-hex conversion, opacity handling, variable binding resolution
+- **`design-to-code-assets.md`** -- Asset detection on text nodes with image fills (image fill on text = background image, not image replacement)
+- **`design-to-code-semantic.md`** -- Semantic HTML tag selection for text elements (h1-h6, p, span, a), heading hierarchy with single h1 rule, BEM class naming for text segments, interactive context preventing headings inside buttons/links
+- **`css-strategy.md`** -- Typography tokens as CSS custom properties in the tokens layer (Layer 2), font-family in Tailwind config, property placement for typography properties (Layer 3).
+- **`design-tokens.md`** -- Typography token extraction (font families, sizes, weights), type scale naming, token lookup during CSS generation, threshold-based promotion.