@fprad0/skill-master-mcp 0.0.12 → 1.0.1

package/docs/skill-candidates/v0.0.10/figma-generate-library/references/documentation-creation.md

@@ -1,834 +1,834 @@
-> Part of the [figma-generate-library skill](../SKILL.md).
-
-# Documentation Creation Reference
-
-This reference covers Phase 2 of the design system build: the cover page, foundations documentation page (color swatches, type specimens, spacing bars, shadow cards, radius demo), page layout dimensions, and inline component documentation. Every code block is complete `use_figma`-ready JavaScript (helper-function form — no IIFE wrapper, no `closePlugin` — meant to be embedded in a larger script).
-
----
-
-## 1. Cover Page
-
-The cover page is always the first page in the file. It is a branded title card that sets context for anyone opening the file.
-
-### What to include
-
-- File/system name as a large heading (48–72px)
-- Version string or date
-- Brief tagline (1 sentence)
-- Optional: color block background using the primary brand color variable
-
-### Cover page dimensions
-
-The cover frame should be **1440 × 900px** — this matches the default Figma canvas and looks correct in the page thumbnail.
-
-### use_figma for cover page
-
-```javascript
-async function createCoverPage(systemName, tagline, version, primaryColorVar) {
-  // primaryColorVar: a Figma Variable object for the brand primary fill
-  const page = figma.createPage();
-  page.name = 'Cover';
-  await figma.setCurrentPageAsync(page);
-
-  await figma.loadFontAsync({ family: 'Inter', style: 'Bold' });
-  await figma.loadFontAsync({ family: 'Inter', style: 'Regular' });
-  await figma.loadFontAsync({ family: 'Inter', style: 'Medium' });
-
-  const frame = figma.createFrame();
-  frame.name = 'Cover';
-  frame.resize(1440, 900);
-  frame.x = 0;
-  frame.y = 0;
-  frame.layoutMode = 'VERTICAL';
-  frame.primaryAxisAlignItems = 'CENTER';
-  frame.counterAxisAlignItems = 'CENTER';
-  frame.itemSpacing = 16;
-  frame.paddingTop = 0;
-  frame.paddingBottom = 0;
-  frame.paddingLeft = 0;
-  frame.paddingRight = 0;
-
-  // Background: bind to primary variable if provided, else solid dark
-  if (primaryColorVar) {
-    const bgPaint = figma.variables.setBoundVariableForPaint(
-      { type: 'SOLID', color: { r: 0.05, g: 0.05, b: 0.05 } },
-      'color',
-      primaryColorVar
-    );
-    frame.fills = [bgPaint];
-  } else {
-    frame.fills = [{ type: 'SOLID', color: { r: 0.06, g: 0.06, b: 0.07 } }];
-  }
-  page.appendChild(frame);
-
-  // System name heading
-  const title = figma.createText();
-  title.fontName = { family: 'Inter', style: 'Bold' };
-  title.characters = systemName;
-  title.fontSize = 64;
-  title.fills = [{ type: 'SOLID', color: { r: 1, g: 1, b: 1 } }];
-  title.textAlignHorizontal = 'CENTER';
-  frame.appendChild(title);
-
-  // Tagline
-  const tag = figma.createText();
-  tag.fontName = { family: 'Inter', style: 'Regular' };
-  tag.characters = tagline;
-  tag.fontSize = 20;
-  tag.fills = [{ type: 'SOLID', color: { r: 1, g: 1, b: 1, a: 0.7 } }];
-  tag.textAlignHorizontal = 'CENTER';
-  frame.appendChild(tag);
-
-  // Version
-  const ver = figma.createText();
-  ver.fontName = { family: 'Inter', style: 'Medium' };
-  ver.characters = version;
-  ver.fontSize = 13;
-  ver.fills = [{ type: 'SOLID', color: { r: 1, g: 1, b: 1, a: 0.45 } }];
-  ver.textAlignHorizontal = 'CENTER';
-  frame.appendChild(ver);
-
-  return { page, frameId: frame.id };
-}
-```
-
----
-
-## 2. Foundations Page
-
-The Foundations page is always placed **before any component pages**. It visually documents the design tokens — colors, typography, spacing, shadows, and border radii — so designers and engineers can see available primitives at a glance.
-
-### Page layout dimensions
-
-The outer documentation frame should be **1440px wide**. Sections stack vertically with **64–100px gaps** between them. Each section frame fills the full 1440px width and hugs its content vertically.
-
-### Full Foundations page skeleton
-
-```javascript
-async function createFoundationsPage() {
-  const page = figma.createPage();
-  page.name = 'Foundations';
-  await figma.setCurrentPageAsync(page);
-
-  await figma.loadFontAsync({ family: 'Inter', style: 'Bold' });
-  await figma.loadFontAsync({ family: 'Inter', style: 'Medium' });
-  await figma.loadFontAsync({ family: 'Inter', style: 'Regular' });
-
-  // Root scroll frame
-  const root = figma.createFrame();
-  root.name = 'Foundations';
-  root.layoutMode = 'VERTICAL';
-  root.primaryAxisAlignItems = 'MIN';
-  root.counterAxisAlignItems = 'MIN';
-  root.itemSpacing = 80;
-  root.paddingTop = 80;
-  root.paddingBottom = 120;
-  root.paddingLeft = 80;
-  root.paddingRight = 80;
-  root.layoutSizingHorizontal = 'FIXED';
-  root.layoutSizingVertical = 'HUG';
-  root.resize(1440, 1);
-  root.fills = [{ type: 'SOLID', color: { r: 1, g: 1, b: 1 } }];
-  page.appendChild(root);
-
-  return { page, root };
-}
-```
-
----
-
-## 3. Color Swatches (bound to variables)
-
-Color swatches must be **bound to actual Figma variables** — never hardcode hex values in swatch fills. This keeps documentation in sync automatically when variable values change.
-
-### Single color swatch
-
-```javascript
-/**
- * Creates a single color swatch card (rectangle + variable name label).
- * The swatch rectangle fill is bound to the provided variable.
- *
- * @param {FrameNode} parent - The auto-layout row to append to.
- * @param {string} varName - Display name (e.g. "color/bg/primary").
- * @param {Variable} variable - The Figma Variable object to bind to.
- * @returns {FrameNode} The swatch frame.
- */
-async function createColorSwatch(parent, varName, variable) {
-  await figma.loadFontAsync({ family: 'Inter', style: 'Regular' });
-
-  const swatchFrame = figma.createFrame();
-  swatchFrame.name = `Swatch/${varName}`;
-  swatchFrame.layoutMode = 'VERTICAL';
-  swatchFrame.primaryAxisAlignItems = 'MIN';
-  swatchFrame.counterAxisAlignItems = 'MIN';
-  swatchFrame.itemSpacing = 6;
-  swatchFrame.layoutSizingHorizontal = 'FIXED';
-  swatchFrame.layoutSizingVertical = 'HUG';
-  swatchFrame.resize(88, 1);
-  swatchFrame.fills = [];
-
-  // Color rectangle — bound to variable
-  const rect = figma.createRectangle();
-  rect.resize(88, 88);
-  rect.cornerRadius = 8;
-  const paint = figma.variables.setBoundVariableForPaint(
-    { type: 'SOLID', color: { r: 0.5, g: 0.5, b: 0.5 } },
-    'color',
-    variable
-  );
-  rect.fills = [paint];
-  swatchFrame.appendChild(rect);
-
-  // Name label
-  const label = figma.createText();
-  label.fontName = { family: 'Inter', style: 'Regular' };
-  label.characters = varName.split('/').pop(); // show leaf name only
-  label.fontSize = 10;
-  label.fills = [{ type: 'SOLID', color: { r: 0.35, g: 0.35, b: 0.35 } }];
-  label.layoutSizingHorizontal = 'FILL';
-  swatchFrame.appendChild(label);
-
-  // Full path tooltip label (smaller, lighter)
-  const pathLabel = figma.createText();
-  pathLabel.fontName = { family: 'Inter', style: 'Regular' };
-  pathLabel.characters = varName;
-  pathLabel.fontSize = 9;
-  pathLabel.fills = [{ type: 'SOLID', color: { r: 0.6, g: 0.6, b: 0.6 } }];
-  pathLabel.layoutSizingHorizontal = 'FILL';
-  swatchFrame.appendChild(pathLabel);
-
-  parent.appendChild(swatchFrame);
-  return swatchFrame;
-}
-```
-
-### Color section builder (primitives row + semantic grid)
-
-```javascript
-/**
- * Creates a complete color documentation section with a section heading,
- * a row of primitive swatches, and a grid of semantic swatches.
- *
- * @param {FrameNode} root - The root vertical stack frame.
- * @param {Variable[]} primitiveVars - Variables from the Primitives collection.
- * @param {Variable[]} semanticVars - Variables from the semantic Color collection.
- */
-async function createColorSection(root, primitiveVars, semanticVars) {
-  await figma.loadFontAsync({ family: 'Inter', style: 'Bold' });
-  await figma.loadFontAsync({ family: 'Inter', style: 'Regular' });
-
-  // Section container
-  const section = figma.createFrame();
-  section.name = 'Section/Colors';
-  section.layoutMode = 'VERTICAL';
-  section.itemSpacing = 24;
-  section.layoutSizingHorizontal = 'FILL';
-  section.layoutSizingVertical = 'HUG';
-  section.fills = [];
-  root.appendChild(section);
-
-  // Section heading
-  const heading = figma.createText();
-  heading.fontName = { family: 'Inter', style: 'Bold' };
-  heading.characters = 'Colors';
-  heading.fontSize = 32;
-  heading.fills = [{ type: 'SOLID', color: { r: 0.07, g: 0.07, b: 0.07 } }];
-  section.appendChild(heading);
-
-  // Description
-  const desc = figma.createText();
-  desc.fontName = { family: 'Inter', style: 'Regular' };
-  desc.characters = 'Primitive color palette and semantic color tokens. Semantic tokens reference primitives — always use semantic tokens in components.';
-  desc.fontSize = 14;
-  desc.fills = [{ type: 'SOLID', color: { r: 0.4, g: 0.4, b: 0.4 } }];
-  desc.layoutSizingHorizontal = 'FILL';
-  section.appendChild(desc);
-
-  // Primitive swatches row
-  const primLabel = figma.createText();
-  primLabel.fontName = { family: 'Inter', style: 'Bold' };
-  primLabel.characters = 'Primitives';
-  primLabel.fontSize = 13;
-  primLabel.fills = [{ type: 'SOLID', color: { r: 0.55, g: 0.55, b: 0.55 } }];
-  section.appendChild(primLabel);
-
-  const primRow = figma.createFrame();
-  primRow.name = 'Primitives/Row';
-  primRow.layoutMode = 'HORIZONTAL';
-  primRow.itemSpacing = 12;
-  primRow.layoutSizingHorizontal = 'FILL';
-  primRow.layoutSizingVertical = 'HUG';
-  primRow.fills = [];
-  primRow.layoutWrap = 'WRAP';
-  section.appendChild(primRow);
-
-  for (const v of primitiveVars) {
-    await createColorSwatch(primRow, v.name, v);
-  }
-
-  // Semantic swatches grid
-  if (semanticVars.length > 0) {
-    const semLabel = figma.createText();
-    semLabel.fontName = { family: 'Inter', style: 'Bold' };
-    semLabel.characters = 'Semantic';
-    semLabel.fontSize = 13;
-    semLabel.fills = [{ type: 'SOLID', color: { r: 0.55, g: 0.55, b: 0.55 } }];
-    section.appendChild(semLabel);
-
-    const semRow = figma.createFrame();
-    semRow.name = 'Semantic/Row';
-    semRow.layoutMode = 'HORIZONTAL';
-    semRow.itemSpacing = 12;
-    semRow.layoutSizingHorizontal = 'FILL';
-    semRow.layoutSizingVertical = 'HUG';
-    semRow.fills = [];
-    semRow.layoutWrap = 'WRAP';
-    section.appendChild(semRow);
-
-    for (const v of semanticVars) {
-      await createColorSwatch(semRow, v.name, v);
-    }
-  }
-
-  return section;
-}
-```
-
----
-
-## 4. Type Specimens
-
-Typography specimens show each text style rendered at its actual size with a sample string, the style name, and its specifications.
-
-### Single type specimen row
-
-```javascript
-/**
- * Creates a single type specimen row: style name (small label) + sample text +
- * specification line (family · style · size · line-height).
- *
- * @param {FrameNode} parent - The parent vertical stack.
- * @param {string} styleName - The text style name (e.g. "Display Large").
- * @param {string} fontFamily - Font family (e.g. "Inter").
- * @param {string} fontStyle - Font style (e.g. "Bold").
- * @param {number} fontSize - Font size in pixels.
- * @param {number} lineHeight - Line height in pixels.
- * @returns {FrameNode} The specimen row frame.
- */
-async function createTypeSpecimen(parent, styleName, fontFamily, fontStyle, fontSize, lineHeight) {
-  await figma.loadFontAsync({ family: fontFamily, style: fontStyle });
-  await figma.loadFontAsync({ family: 'Inter', style: 'Medium' });
-  await figma.loadFontAsync({ family: 'Inter', style: 'Regular' });
-
-  const row = figma.createFrame();
-  row.name = `Type/${styleName}`;
-  row.layoutMode = 'VERTICAL';
-  row.itemSpacing = 6;
-  row.paddingTop = 16;
-  row.paddingBottom = 16;
-  row.layoutSizingHorizontal = 'FILL';
-  row.layoutSizingVertical = 'HUG';
-  row.fills = [];
-  parent.appendChild(row);
-
-  // Style name label (small, muted)
-  const nameText = figma.createText();
-  nameText.fontName = { family: 'Inter', style: 'Medium' };
-  nameText.characters = styleName;
-  nameText.fontSize = 11;
-  nameText.fills = [{ type: 'SOLID', color: { r: 0.55, g: 0.55, b: 0.55 } }];
-  nameText.layoutSizingHorizontal = 'FILL';
-  row.appendChild(nameText);
-
-  // Sample text rendered in the actual style
-  const specimen = figma.createText();
-  specimen.fontName = { family: fontFamily, style: fontStyle };
-  specimen.characters = 'The quick brown fox jumps over the lazy dog';
-  specimen.fontSize = fontSize;
-  specimen.lineHeight = { value: lineHeight, unit: 'PIXELS' };
-  specimen.fills = [{ type: 'SOLID', color: { r: 0.07, g: 0.07, b: 0.07 } }];
-  specimen.layoutSizingHorizontal = 'FILL';
-  row.appendChild(specimen);
-
-  // Specification line
-  const specs = figma.createText();
-  specs.fontName = { family: 'Inter', style: 'Regular' };
-  specs.characters = `${fontFamily} ${fontStyle} · ${fontSize}px · ${lineHeight}px line height`;
-  specs.fontSize = 11;
-  specs.fills = [{ type: 'SOLID', color: { r: 0.65, g: 0.65, b: 0.65 } }];
-  specs.layoutSizingHorizontal = 'FILL';
-  row.appendChild(specs);
-
-  // Divider line
-  const divider = figma.createRectangle();
-  divider.resize(1280, 1);
-  divider.fills = [{ type: 'SOLID', color: { r: 0.9, g: 0.9, b: 0.9 } }];
-  divider.layoutSizingHorizontal = 'FILL';
-  row.appendChild(divider);
-
-  return row;
-}
-```
-
-### Typography section builder
-
-```javascript
-/**
- * Creates a complete typography documentation section.
- * Pass an array of style definitions; the function renders one specimen per entry.
- *
- * @param {FrameNode} root - Root vertical stack.
- * @param {Array<{name, family, style, size, lineHeight}>} typeStyles - Style definitions.
- */
-async function createTypographySection(root, typeStyles) {
-  await figma.loadFontAsync({ family: 'Inter', style: 'Bold' });
-
-  const section = figma.createFrame();
-  section.name = 'Section/Typography';
-  section.layoutMode = 'VERTICAL';
-  section.itemSpacing = 0;
-  section.layoutSizingHorizontal = 'FILL';
-  section.layoutSizingVertical = 'HUG';
-  section.fills = [];
-  root.appendChild(section);
-
-  const heading = figma.createText();
-  heading.fontName = { family: 'Inter', style: 'Bold' };
-  heading.characters = 'Typography';
-  heading.fontSize = 32;
-  heading.fills = [{ type: 'SOLID', color: { r: 0.07, g: 0.07, b: 0.07 } }];
-  section.appendChild(heading);
-
-  for (const ts of typeStyles) {
-    await createTypeSpecimen(section, ts.name, ts.family, ts.style, ts.size, ts.lineHeight);
-  }
-
-  return section;
-}
-```
-
----
-
-## 5. Spacing Bars
-
-Spacing bars show each spacing token as a filled rectangle whose width equals the spacing value. Shorter bars for small values, longer bars for large values — the visual encoding is immediate.
-
-### Spacing bar row
-
-```javascript
-/**
- * Creates a single spacing bar: a colored rectangle sized to the spacing value,
- * with a label showing name + pixel value + code syntax.
- *
- * @param {FrameNode} parent - Parent vertical stack.
- * @param {string} name - Token name (e.g. "spacing/sm").
- * @param {number} value - Spacing value in pixels.
- * @param {Variable} variable - Figma Variable to bind the width to.
- * @param {string} codeSyntax - CSS variable string (e.g. "var(--spacing-sm)").
- */
-async function createSpacingBar(parent, name, value, variable, codeSyntax) {
-  await figma.loadFontAsync({ family: 'Inter', style: 'Regular' });
-
-  const row = figma.createFrame();
-  row.name = `Spacing/${name}`;
-  row.layoutMode = 'HORIZONTAL';
-  row.counterAxisAlignItems = 'CENTER';
-  row.itemSpacing = 16;
-  row.layoutSizingHorizontal = 'FILL';
-  row.layoutSizingVertical = 'HUG';
-  row.fills = [];
-  parent.appendChild(row);
-
-  // The bar rectangle — width bound to spacing variable
-  const bar = figma.createRectangle();
-  bar.resize(value, 16);
-  bar.cornerRadius = 3;
-  bar.fills = [{ type: 'SOLID', color: { r: 0.22, g: 0.47, b: 0.98 } }];
-  // Bind width to the spacing variable so it reflects the actual token value
-  if (variable) {
-    bar.setBoundVariable('width', variable);
-  }
-  row.appendChild(bar);
-
-  // Label: "spacing/sm  8px  var(--spacing-sm)"
-  const label = figma.createText();
-  label.fontName = { family: 'Inter', style: 'Regular' };
-  label.characters = `${name}  ${value}px  ${codeSyntax}`;
-  label.fontSize = 12;
-  label.fills = [{ type: 'SOLID', color: { r: 0.35, g: 0.35, b: 0.35 } }];
-  row.appendChild(label);
-
-  return row;
-}
-```
-
-### Spacing section builder
-
-```javascript
-/**
- * Creates the full spacing documentation section.
- *
- * @param {FrameNode} root - Root vertical stack.
- * @param {Array<{name, value, variable, codeSyntax}>} spacingTokens - Token definitions.
- */
-async function createSpacingSection(root, spacingTokens) {
-  await figma.loadFontAsync({ family: 'Inter', style: 'Bold' });
-
-  const section = figma.createFrame();
-  section.name = 'Section/Spacing';
-  section.layoutMode = 'VERTICAL';
-  section.itemSpacing = 12;
-  section.layoutSizingHorizontal = 'FILL';
-  section.layoutSizingVertical = 'HUG';
-  section.fills = [];
-  root.appendChild(section);
-
-  const heading = figma.createText();
-  heading.fontName = { family: 'Inter', style: 'Bold' };
-  heading.characters = 'Spacing';
-  heading.fontSize = 32;
-  heading.fills = [{ type: 'SOLID', color: { r: 0.07, g: 0.07, b: 0.07 } }];
-  section.appendChild(heading);
-
-  for (const tok of spacingTokens) {
-    await createSpacingBar(section, tok.name, tok.value, tok.variable, tok.codeSyntax);
-  }
-
-  return section;
-}
-```
-
----
-
-## 6. Shadow Cards (Elevation)
-
-Elevation documentation shows cards with progressively stronger drop shadows, labeled with name and effect parameters.
-
-### Single shadow card
-
-```javascript
-/**
- * Creates a shadow card: a white rectangle with a drop shadow effect,
- * labeled with the elevation name and shadow parameters.
- *
- * @param {FrameNode} parent - The horizontal row to append to.
- * @param {string} name - Elevation name (e.g. "Shadow/Medium").
- * @param {DropShadowEffect[]} effects - Array of Figma effect objects.
- */
-async function createShadowCard(parent, name, effects) {
-  await figma.loadFontAsync({ family: 'Inter', style: 'Regular' });
-  await figma.loadFontAsync({ family: 'Inter', style: 'Medium' });
-
-  const card = figma.createFrame();
-  card.name = `ShadowCard/${name}`;
-  card.layoutMode = 'VERTICAL';
-  card.primaryAxisAlignItems = 'CENTER';
-  card.counterAxisAlignItems = 'CENTER';
-  card.itemSpacing = 8;
-  card.paddingTop = 16;
-  card.paddingBottom = 16;
-  card.resize(120, 120);
-  card.cornerRadius = 8;
-  card.fills = [{ type: 'SOLID', color: { r: 1, g: 1, b: 1 } }];
-  card.effects = effects;
-  parent.appendChild(card);
-
-  // Elevation name
-  const nameLabel = figma.createText();
-  nameLabel.fontName = { family: 'Inter', style: 'Medium' };
-  nameLabel.characters = name.split('/').pop();
-  nameLabel.fontSize = 12;
-  nameLabel.textAlignHorizontal = 'CENTER';
-  nameLabel.fills = [{ type: 'SOLID', color: { r: 0.2, g: 0.2, b: 0.2 } }];
-  card.appendChild(nameLabel);
-
-  // Effect parameters as small text
-  if (effects.length > 0) {
-    const e = effects[0];
-    if (e.type === 'DROP_SHADOW') {
-      const params = figma.createText();
-      params.fontName = { family: 'Inter', style: 'Regular' };
-      params.characters = `x:${e.offset.x} y:${e.offset.y}\nblur:${e.radius}`;
-      params.fontSize = 10;
-      params.textAlignHorizontal = 'CENTER';
-      params.fills = [{ type: 'SOLID', color: { r: 0.55, g: 0.55, b: 0.55 } }];
-      card.appendChild(params);
-    }
-  }
-
-  return card;
-}
-```
-
-### Shadow section builder
-
-```javascript
-/**
- * Creates the full elevation/shadow documentation section.
- *
- * @param {FrameNode} root - Root vertical stack.
- * @param {Array<{name, effects}>} shadowTokens - Shadow definitions.
- */
-async function createShadowSection(root, shadowTokens) {
-  await figma.loadFontAsync({ family: 'Inter', style: 'Bold' });
-
-  const section = figma.createFrame();
-  section.name = 'Section/Elevation';
-  section.layoutMode = 'VERTICAL';
-  section.itemSpacing = 24;
-  section.layoutSizingHorizontal = 'FILL';
-  section.layoutSizingVertical = 'HUG';
-  section.fills = [];
-  root.appendChild(section);
-
-  const heading = figma.createText();
-  heading.fontName = { family: 'Inter', style: 'Bold' };
-  heading.characters = 'Elevation';
-  heading.fontSize = 32;
-  heading.fills = [{ type: 'SOLID', color: { r: 0.07, g: 0.07, b: 0.07 } }];
-  section.appendChild(heading);
-
-  // Cards row — extra top padding so shadows are visible
-  const row = figma.createFrame();
-  row.name = 'Elevation/Row';
-  row.layoutMode = 'HORIZONTAL';
-  row.itemSpacing = 32;
-  row.paddingTop = 24;
-  row.paddingBottom = 40;
-  row.layoutSizingHorizontal = 'FILL';
-  row.layoutSizingVertical = 'HUG';
-  row.fills = [{ type: 'SOLID', color: { r: 0.97, g: 0.97, b: 0.97 } }];
-  row.cornerRadius = 8;
-  row.paddingLeft = 24;
-  row.paddingRight = 24;
-  section.appendChild(row);
-
-  for (const tok of shadowTokens) {
-    await createShadowCard(row, tok.name, tok.effects);
-  }
-
-  return section;
-}
-```
-
----
-
-## 7. Border Radius Demo
-
-Border radius documentation shows rectangles at each corner radius value, labeled with the token name and pixel value.
-
-### Single radius card
-
-```javascript
-/**
- * Creates a single border radius card: a square with corner radius applied,
- * labeled with the token name and pixel value.
- *
- * @param {FrameNode} parent - The horizontal row to append to.
- * @param {string} name - Token name (e.g. "radius/md").
- * @param {number} value - Corner radius in pixels (0 for none, 9999 for full).
- * @param {Variable} [variable] - Optional Figma Variable to bind corner radius.
- */
-async function createRadiusCard(parent, name, value, variable) {
-  await figma.loadFontAsync({ family: 'Inter', style: 'Regular' });
-  await figma.loadFontAsync({ family: 'Inter', style: 'Medium' });
-
-  const wrapper = figma.createFrame();
-  wrapper.name = `Radius/${name}`;
-  wrapper.layoutMode = 'VERTICAL';
-  wrapper.primaryAxisAlignItems = 'CENTER';
-  wrapper.counterAxisAlignItems = 'CENTER';
-  wrapper.itemSpacing = 8;
-  wrapper.fills = [];
-  wrapper.layoutSizingHorizontal = 'FIXED';
-  wrapper.layoutSizingVertical = 'HUG';
-  wrapper.resize(96, 1);
-  parent.appendChild(wrapper);
-
-  const rect = figma.createRectangle();
-  rect.resize(72, 72);
-  rect.fills = [{ type: 'SOLID', color: { r: 0.22, g: 0.47, b: 0.98, a: 0.15 } }];
-  rect.strokes = [{ type: 'SOLID', color: { r: 0.22, g: 0.47, b: 0.98 } }];
-  rect.strokeWeight = 1.5;
-
-  // Cap display value — 9999 is how Figma represents "full/pill"
-  const displayRadius = Math.min(value, 36);
-  rect.cornerRadius = displayRadius;
-
-  // Bind to variable if provided
-  if (variable) {
-    rect.setBoundVariable('cornerRadius', variable);
-  }
-  wrapper.appendChild(rect);
-
-  const nameLabel = figma.createText();
-  nameLabel.fontName = { family: 'Inter', style: 'Medium' };
-  nameLabel.characters = name.split('/').pop();
-  nameLabel.fontSize = 11;
-  nameLabel.textAlignHorizontal = 'CENTER';
-  nameLabel.fills = [{ type: 'SOLID', color: { r: 0.2, g: 0.2, b: 0.2 } }];
-  wrapper.appendChild(nameLabel);
-
-  const valueLabel = figma.createText();
-  valueLabel.fontName = { family: 'Inter', style: 'Regular' };
-  valueLabel.characters = value >= 9999 ? 'full' : `${value}px`;
-  valueLabel.fontSize = 10;
-  valueLabel.textAlignHorizontal = 'CENTER';
-  valueLabel.fills = [{ type: 'SOLID', color: { r: 0.55, g: 0.55, b: 0.55 } }];
-  wrapper.appendChild(valueLabel);
-
-  return wrapper;
-}
-```
-
-### Radius section builder
-
-```javascript
-/**
- * Creates the full border radius documentation section.
- *
- * @param {FrameNode} root - Root vertical stack.
- * @param {Array<{name, value, variable}>} radiusTokens - Radius token definitions.
- */
-async function createRadiusSection(root, radiusTokens) {
-  await figma.loadFontAsync({ family: 'Inter', style: 'Bold' });
-
-  const section = figma.createFrame();
-  section.name = 'Section/Radius';
-  section.layoutMode = 'VERTICAL';
-  section.itemSpacing = 24;
-  section.layoutSizingHorizontal = 'FILL';
-  section.layoutSizingVertical = 'HUG';
-  section.fills = [];
-  root.appendChild(section);
-
-  const heading = figma.createText();
-  heading.fontName = { family: 'Inter', style: 'Bold' };
-  heading.characters = 'Border Radius';
-  heading.fontSize = 32;
-  heading.fills = [{ type: 'SOLID', color: { r: 0.07, g: 0.07, b: 0.07 } }];
-  section.appendChild(heading);
-
-  const row = figma.createFrame();
-  row.name = 'Radius/Row';
-  row.layoutMode = 'HORIZONTAL';
-  row.itemSpacing = 24;
-  row.paddingTop = 24;
-  row.paddingBottom = 24;
-  row.paddingLeft = 24;
-  row.paddingRight = 24;
-  row.layoutSizingHorizontal = 'FILL';
-  row.layoutSizingVertical = 'HUG';
-  row.fills = [{ type: 'SOLID', color: { r: 0.97, g: 0.97, b: 0.97 } }];
-  row.cornerRadius = 8;
-  section.appendChild(row);
-
-  for (const tok of radiusTokens) {
-    await createRadiusCard(row, tok.name, tok.value, tok.variable);
-  }
-
-  return section;
-}
-```
-
----
-
-## 8. Documentation Alongside Components
-
-Each component page should include a documentation frame directly on the canvas, placed to the left of the component set. This keeps docs and the component in sync without requiring a separate file.
-
-### Component page documentation frame
-
-```javascript
-/**
- * Creates the documentation frame for a component page: title, description,
- * and usage notes, positioned at x=0 with the component set to its right.
- *
- * @param {PageNode} page - The component page (must already be current).
- * @param {string} componentName - The component name.
- * @param {string} description - What the component does and when to use it.
- * @param {string[]} usageNotes - Bullet points for usage guidance.
- * @returns {FrameNode} The documentation frame.
- */
-async function createComponentDocFrame(page, componentName, description, usageNotes) {
-  await figma.loadFontAsync({ family: 'Inter', style: 'Bold' });
-  await figma.loadFontAsync({ family: 'Inter', style: 'Regular' });
-
-  const doc = figma.createFrame();
-  doc.name = '_Doc';
-  doc.layoutMode = 'VERTICAL';
-  doc.itemSpacing = 16;
-  doc.paddingTop = 40;
-  doc.paddingBottom = 40;
-  doc.paddingLeft = 40;
-  doc.paddingRight = 40;
-  doc.layoutSizingHorizontal = 'FIXED';
-  doc.layoutSizingVertical = 'HUG';
-  doc.resize(360, 1);
-  doc.fills = [];
-  doc.x = 0;
-  doc.y = 0;
-  page.appendChild(doc);
-
-  // Component name — large heading
-  const title = figma.createText();
-  title.fontName = { family: 'Inter', style: 'Bold' };
-  title.characters = componentName;
-  title.fontSize = 28;
-  title.fills = [{ type: 'SOLID', color: { r: 0.07, g: 0.07, b: 0.07 } }];
-  title.layoutSizingHorizontal = 'FILL';
-  doc.appendChild(title);
-
-  // Description
-  const descText = figma.createText();
-  descText.fontName = { family: 'Inter', style: 'Regular' };
-  descText.characters = description;
-  descText.fontSize = 13;
-  descText.lineHeight = { value: 20, unit: 'PIXELS' };
-  descText.fills = [{ type: 'SOLID', color: { r: 0.35, g: 0.35, b: 0.35 } }];
-  descText.layoutSizingHorizontal = 'FILL';
-  doc.appendChild(descText);
-
-  // Divider
-  const divider = figma.createRectangle();
-  divider.resize(280, 1);
-  divider.fills = [{ type: 'SOLID', color: { r: 0.88, g: 0.88, b: 0.88 } }];
-  divider.layoutSizingHorizontal = 'FILL';
-  doc.appendChild(divider);
-
-  // Usage notes
-  if (usageNotes.length > 0) {
-    const usageHeading = figma.createText();
-    usageHeading.fontName = { family: 'Inter', style: 'Bold' };
-    usageHeading.characters = 'Usage';
-    usageHeading.fontSize = 13;
-    usageHeading.fills = [{ type: 'SOLID', color: { r: 0.07, g: 0.07, b: 0.07 } }];
-    doc.appendChild(usageHeading);
-
-    for (const note of usageNotes) {
-      const noteText = figma.createText();
-      noteText.fontName = { family: 'Inter', style: 'Regular' };
-      noteText.characters = `• ${note}`;
-      noteText.fontSize = 12;
-      noteText.lineHeight = { value: 18, unit: 'PIXELS' };
-      noteText.fills = [{ type: 'SOLID', color: { r: 0.4, g: 0.4, b: 0.4 } }];
-      noteText.layoutSizingHorizontal = 'FILL';
-      doc.appendChild(noteText);
-    }
-  }
-
-  return doc;
-}
-```
-
----
-
-## 9. Critical Rules
-
-1. **Bind swatches to variables** — use `setBoundVariableForPaint` for color fills, `setBoundVariable('width', ...)` for spacing bars, and `setBoundVariable('cornerRadius', ...)` for radius cards. Never hardcode values that have corresponding variables.
-2. **Foundations page comes before component pages** — always insert it between the file structure separators and the first component page.
-3. **Show both primitive and semantic layers** — if the system has a Primitives collection and a semantic Color collection, document both on the Foundations page with clear section labels.
-4. **Page frame width = 1440px** — this is the convention across Simple DS, Polaris, and Material 3. Use it unless you detect a different existing convention via `get_metadata`.
-5. **Section spacing = 64–80px** — the gap between color / typography / spacing / shadow / radius sections should be at minimum 64px so the page is scannable.
-6. **Match existing page style** — if the target file uses emoji page name prefixes or a decorative separator style, carry that through to the Foundations page name.
-7. **Include code syntax in labels** — where variables have code syntax set, display the CSS variable name in the swatch/bar label so developers can copy it directly.
+> Part of the [figma-generate-library skill](../SKILL.md).
+
+# Documentation Creation Reference
+
+This reference covers Phase 2 of the design system build: the cover page, foundations documentation page (color swatches, type specimens, spacing bars, shadow cards, radius demo), page layout dimensions, and inline component documentation. Every code block is complete `use_figma`-ready JavaScript (helper-function form — no IIFE wrapper, no `closePlugin` — meant to be embedded in a larger script).
+
+---
+
+## 1. Cover Page
+
+The cover page is always the first page in the file. It is a branded title card that sets context for anyone opening the file.
+
+### What to include
+
+- File/system name as a large heading (48–72px)
+- Version string or date
+- Brief tagline (1 sentence)
+- Optional: color block background using the primary brand color variable
+
+### Cover page dimensions
+
+The cover frame should be **1440 × 900px** — this matches the default Figma canvas and looks correct in the page thumbnail.
+
+### use_figma for cover page
+
+```javascript
+async function createCoverPage(systemName, tagline, version, primaryColorVar) {
+  // primaryColorVar: a Figma Variable object for the brand primary fill
+  const page = figma.createPage();
+  page.name = 'Cover';
+  await figma.setCurrentPageAsync(page);
+
+  await figma.loadFontAsync({ family: 'Inter', style: 'Bold' });
+  await figma.loadFontAsync({ family: 'Inter', style: 'Regular' });
+  await figma.loadFontAsync({ family: 'Inter', style: 'Medium' });
+
+  const frame = figma.createFrame();
+  frame.name = 'Cover';
+  frame.resize(1440, 900);
+  frame.x = 0;
+  frame.y = 0;
+  frame.layoutMode = 'VERTICAL';
+  frame.primaryAxisAlignItems = 'CENTER';
+  frame.counterAxisAlignItems = 'CENTER';
+  frame.itemSpacing = 16;
+  frame.paddingTop = 0;
+  frame.paddingBottom = 0;
+  frame.paddingLeft = 0;
+  frame.paddingRight = 0;
+
+  // Background: bind to primary variable if provided, else solid dark
+  if (primaryColorVar) {
+    const bgPaint = figma.variables.setBoundVariableForPaint(
+      { type: 'SOLID', color: { r: 0.05, g: 0.05, b: 0.05 } },
+      'color',
+      primaryColorVar
+    );
+    frame.fills = [bgPaint];
+  } else {
+    frame.fills = [{ type: 'SOLID', color: { r: 0.06, g: 0.06, b: 0.07 } }];
+  }
+  page.appendChild(frame);
+
+  // System name heading
+  const title = figma.createText();
+  title.fontName = { family: 'Inter', style: 'Bold' };
+  title.characters = systemName;
+  title.fontSize = 64;
+  title.fills = [{ type: 'SOLID', color: { r: 1, g: 1, b: 1 } }];
+  title.textAlignHorizontal = 'CENTER';
+  frame.appendChild(title);
+
+  // Tagline
+  const tag = figma.createText();
+  tag.fontName = { family: 'Inter', style: 'Regular' };
+  tag.characters = tagline;
+  tag.fontSize = 20;
+  tag.fills = [{ type: 'SOLID', color: { r: 1, g: 1, b: 1, a: 0.7 } }];
+  tag.textAlignHorizontal = 'CENTER';
+  frame.appendChild(tag);
+
+  // Version
+  const ver = figma.createText();
+  ver.fontName = { family: 'Inter', style: 'Medium' };
+  ver.characters = version;
+  ver.fontSize = 13;
+  ver.fills = [{ type: 'SOLID', color: { r: 1, g: 1, b: 1, a: 0.45 } }];
+  ver.textAlignHorizontal = 'CENTER';
+  frame.appendChild(ver);
+
+  return { page, frameId: frame.id };
+}
+```
+
+---
+
+## 2. Foundations Page
+
+The Foundations page is always placed **before any component pages**. It visually documents the design tokens — colors, typography, spacing, shadows, and border radii — so designers and engineers can see available primitives at a glance.
+
+### Page layout dimensions
+
+The outer documentation frame should be **1440px wide**. Sections stack vertically with **64–100px gaps** between them. Each section frame fills the full 1440px width and hugs its content vertically.
+
+### Full Foundations page skeleton
+
+```javascript
+async function createFoundationsPage() {
+  const page = figma.createPage();
+  page.name = 'Foundations';
+  await figma.setCurrentPageAsync(page);
+
+  await figma.loadFontAsync({ family: 'Inter', style: 'Bold' });
+  await figma.loadFontAsync({ family: 'Inter', style: 'Medium' });
+  await figma.loadFontAsync({ family: 'Inter', style: 'Regular' });
+
+  // Root scroll frame
+  const root = figma.createFrame();
+  root.name = 'Foundations';
+  root.layoutMode = 'VERTICAL';
+  root.primaryAxisAlignItems = 'MIN';
+  root.counterAxisAlignItems = 'MIN';
+  root.itemSpacing = 80;
+  root.paddingTop = 80;
+  root.paddingBottom = 120;
+  root.paddingLeft = 80;
+  root.paddingRight = 80;
+  root.layoutSizingHorizontal = 'FIXED';
+  root.layoutSizingVertical = 'HUG';
+  root.resize(1440, 1);
+  root.fills = [{ type: 'SOLID', color: { r: 1, g: 1, b: 1 } }];
+  page.appendChild(root);
+
+  return { page, root };
+}
+```
+
+---
+
+## 3. Color Swatches (bound to variables)
+
+Color swatches must be **bound to actual Figma variables** — never hardcode hex values in swatch fills. This keeps documentation in sync automatically when variable values change.
+
+### Single color swatch
+
+```javascript
+/**
+ * Creates a single color swatch card (rectangle + variable name label).
+ * The swatch rectangle fill is bound to the provided variable.
+ *
+ * @param {FrameNode} parent - The auto-layout row to append to.
+ * @param {string} varName - Display name (e.g. "color/bg/primary").
+ * @param {Variable} variable - The Figma Variable object to bind to.
+ * @returns {FrameNode} The swatch frame.
+ */
+async function createColorSwatch(parent, varName, variable) {
+  await figma.loadFontAsync({ family: 'Inter', style: 'Regular' });
+
+  const swatchFrame = figma.createFrame();
+  swatchFrame.name = `Swatch/${varName}`;
+  swatchFrame.layoutMode = 'VERTICAL';
+  swatchFrame.primaryAxisAlignItems = 'MIN';
+  swatchFrame.counterAxisAlignItems = 'MIN';
+  swatchFrame.itemSpacing = 6;
+  swatchFrame.layoutSizingHorizontal = 'FIXED';
+  swatchFrame.layoutSizingVertical = 'HUG';
+  swatchFrame.resize(88, 1);
+  swatchFrame.fills = [];
+
+  // Color rectangle — bound to variable
+  const rect = figma.createRectangle();
+  rect.resize(88, 88);
+  rect.cornerRadius = 8;
+  const paint = figma.variables.setBoundVariableForPaint(
+    { type: 'SOLID', color: { r: 0.5, g: 0.5, b: 0.5 } },
+    'color',
+    variable
+  );
+  rect.fills = [paint];
+  swatchFrame.appendChild(rect);
+
+  // Name label
+  const label = figma.createText();
+  label.fontName = { family: 'Inter', style: 'Regular' };
+  label.characters = varName.split('/').pop(); // show leaf name only
+  label.fontSize = 10;
+  label.fills = [{ type: 'SOLID', color: { r: 0.35, g: 0.35, b: 0.35 } }];
+  label.layoutSizingHorizontal = 'FILL';
+  swatchFrame.appendChild(label);
+
+  // Full path tooltip label (smaller, lighter)
+  const pathLabel = figma.createText();
+  pathLabel.fontName = { family: 'Inter', style: 'Regular' };
+  pathLabel.characters = varName;
+  pathLabel.fontSize = 9;
+  pathLabel.fills = [{ type: 'SOLID', color: { r: 0.6, g: 0.6, b: 0.6 } }];
+  pathLabel.layoutSizingHorizontal = 'FILL';
+  swatchFrame.appendChild(pathLabel);
+
+  parent.appendChild(swatchFrame);
+  return swatchFrame;
+}
+```
+
+### Color section builder (primitives row + semantic grid)
+
+```javascript
+/**
+ * Creates a complete color documentation section with a section heading,
+ * a row of primitive swatches, and a grid of semantic swatches.
+ *
+ * @param {FrameNode} root - The root vertical stack frame.
+ * @param {Variable[]} primitiveVars - Variables from the Primitives collection.
+ * @param {Variable[]} semanticVars - Variables from the semantic Color collection.
+ */
+async function createColorSection(root, primitiveVars, semanticVars) {
+  await figma.loadFontAsync({ family: 'Inter', style: 'Bold' });
+  await figma.loadFontAsync({ family: 'Inter', style: 'Regular' });
+
+  // Section container
+  const section = figma.createFrame();
+  section.name = 'Section/Colors';
+  section.layoutMode = 'VERTICAL';
+  section.itemSpacing = 24;
+  section.layoutSizingHorizontal = 'FILL';
+  section.layoutSizingVertical = 'HUG';
+  section.fills = [];
+  root.appendChild(section);
+
+  // Section heading
+  const heading = figma.createText();
+  heading.fontName = { family: 'Inter', style: 'Bold' };
+  heading.characters = 'Colors';
+  heading.fontSize = 32;
+  heading.fills = [{ type: 'SOLID', color: { r: 0.07, g: 0.07, b: 0.07 } }];
+  section.appendChild(heading);
+
+  // Description
+  const desc = figma.createText();
+  desc.fontName = { family: 'Inter', style: 'Regular' };
+  desc.characters = 'Primitive color palette and semantic color tokens. Semantic tokens reference primitives — always use semantic tokens in components.';
+  desc.fontSize = 14;
+  desc.fills = [{ type: 'SOLID', color: { r: 0.4, g: 0.4, b: 0.4 } }];
+  desc.layoutSizingHorizontal = 'FILL';
+  section.appendChild(desc);
+
+  // Primitive swatches row
+  const primLabel = figma.createText();
+  primLabel.fontName = { family: 'Inter', style: 'Bold' };
+  primLabel.characters = 'Primitives';
+  primLabel.fontSize = 13;
+  primLabel.fills = [{ type: 'SOLID', color: { r: 0.55, g: 0.55, b: 0.55 } }];
+  section.appendChild(primLabel);
+
+  const primRow = figma.createFrame();
+  primRow.name = 'Primitives/Row';
+  primRow.layoutMode = 'HORIZONTAL';
+  primRow.itemSpacing = 12;
+  primRow.layoutSizingHorizontal = 'FILL';
+  primRow.layoutSizingVertical = 'HUG';
+  primRow.fills = [];
+  primRow.layoutWrap = 'WRAP';
+  section.appendChild(primRow);
+
+  for (const v of primitiveVars) {
+    await createColorSwatch(primRow, v.name, v);
+  }
+
+  // Semantic swatches grid
+  if (semanticVars.length > 0) {
+    const semLabel = figma.createText();
+    semLabel.fontName = { family: 'Inter', style: 'Bold' };
+    semLabel.characters = 'Semantic';
+    semLabel.fontSize = 13;
+    semLabel.fills = [{ type: 'SOLID', color: { r: 0.55, g: 0.55, b: 0.55 } }];
+    section.appendChild(semLabel);
+
+    const semRow = figma.createFrame();
+    semRow.name = 'Semantic/Row';
+    semRow.layoutMode = 'HORIZONTAL';
+    semRow.itemSpacing = 12;
+    semRow.layoutSizingHorizontal = 'FILL';
+    semRow.layoutSizingVertical = 'HUG';
+    semRow.fills = [];
+    semRow.layoutWrap = 'WRAP';
+    section.appendChild(semRow);
+
+    for (const v of semanticVars) {
+      await createColorSwatch(semRow, v.name, v);
+    }
+  }
+
+  return section;
+}
+```
+
+---
+
+## 4. Type Specimens
+
+Typography specimens show each text style rendered at its actual size with a sample string, the style name, and its specifications.
+
+### Single type specimen row
+
+```javascript
+/**
+ * Creates a single type specimen row: style name (small label) + sample text +
+ * specification line (family · style · size · line-height).
+ *
+ * @param {FrameNode} parent - The parent vertical stack.
+ * @param {string} styleName - The text style name (e.g. "Display Large").
+ * @param {string} fontFamily - Font family (e.g. "Inter").
+ * @param {string} fontStyle - Font style (e.g. "Bold").
+ * @param {number} fontSize - Font size in pixels.
+ * @param {number} lineHeight - Line height in pixels.
+ * @returns {FrameNode} The specimen row frame.
+ */
+async function createTypeSpecimen(parent, styleName, fontFamily, fontStyle, fontSize, lineHeight) {
+  await figma.loadFontAsync({ family: fontFamily, style: fontStyle });
+  await figma.loadFontAsync({ family: 'Inter', style: 'Medium' });
+  await figma.loadFontAsync({ family: 'Inter', style: 'Regular' });
+
+  const row = figma.createFrame();
+  row.name = `Type/${styleName}`;
+  row.layoutMode = 'VERTICAL';
+  row.itemSpacing = 6;
+  row.paddingTop = 16;
+  row.paddingBottom = 16;
+  row.layoutSizingHorizontal = 'FILL';
+  row.layoutSizingVertical = 'HUG';
+  row.fills = [];
+  parent.appendChild(row);
+
+  // Style name label (small, muted)
+  const nameText = figma.createText();
+  nameText.fontName = { family: 'Inter', style: 'Medium' };
+  nameText.characters = styleName;
+  nameText.fontSize = 11;
+  nameText.fills = [{ type: 'SOLID', color: { r: 0.55, g: 0.55, b: 0.55 } }];
+  nameText.layoutSizingHorizontal = 'FILL';
+  row.appendChild(nameText);
+
+  // Sample text rendered in the actual style
+  const specimen = figma.createText();
+  specimen.fontName = { family: fontFamily, style: fontStyle };
+  specimen.characters = 'The quick brown fox jumps over the lazy dog';
+  specimen.fontSize = fontSize;
+  specimen.lineHeight = { value: lineHeight, unit: 'PIXELS' };
+  specimen.fills = [{ type: 'SOLID', color: { r: 0.07, g: 0.07, b: 0.07 } }];
+  specimen.layoutSizingHorizontal = 'FILL';
+  row.appendChild(specimen);
+
+  // Specification line
+  const specs = figma.createText();
+  specs.fontName = { family: 'Inter', style: 'Regular' };
+  specs.characters = `${fontFamily} ${fontStyle} · ${fontSize}px · ${lineHeight}px line height`;
+  specs.fontSize = 11;
+  specs.fills = [{ type: 'SOLID', color: { r: 0.65, g: 0.65, b: 0.65 } }];
+  specs.layoutSizingHorizontal = 'FILL';
+  row.appendChild(specs);
+
+  // Divider line
+  const divider = figma.createRectangle();
+  divider.resize(1280, 1);
+  divider.fills = [{ type: 'SOLID', color: { r: 0.9, g: 0.9, b: 0.9 } }];
+  divider.layoutSizingHorizontal = 'FILL';
+  row.appendChild(divider);
+
+  return row;
+}
+```
+
+### Typography section builder
+
+```javascript
+/**
+ * Creates a complete typography documentation section.
+ * Pass an array of style definitions; the function renders one specimen per entry.
+ *
+ * @param {FrameNode} root - Root vertical stack.
+ * @param {Array<{name, family, style, size, lineHeight}>} typeStyles - Style definitions.
+ */
+async function createTypographySection(root, typeStyles) {
+  await figma.loadFontAsync({ family: 'Inter', style: 'Bold' });
+
+  const section = figma.createFrame();
+  section.name = 'Section/Typography';
+  section.layoutMode = 'VERTICAL';
+  section.itemSpacing = 0;
+  section.layoutSizingHorizontal = 'FILL';
+  section.layoutSizingVertical = 'HUG';
+  section.fills = [];
+  root.appendChild(section);
+
+  const heading = figma.createText();
+  heading.fontName = { family: 'Inter', style: 'Bold' };
+  heading.characters = 'Typography';
+  heading.fontSize = 32;
+  heading.fills = [{ type: 'SOLID', color: { r: 0.07, g: 0.07, b: 0.07 } }];
+  section.appendChild(heading);
+
+  for (const ts of typeStyles) {
+    await createTypeSpecimen(section, ts.name, ts.family, ts.style, ts.size, ts.lineHeight);
+  }
+
+  return section;
+}
+```
+
+---
+
+## 5. Spacing Bars
+
+Spacing bars show each spacing token as a filled rectangle whose width equals the spacing value. Shorter bars for small values, longer bars for large values — the visual encoding is immediate.
+
+### Spacing bar row
+
+```javascript
+/**
+ * Creates a single spacing bar: a colored rectangle sized to the spacing value,
+ * with a label showing name + pixel value + code syntax.
+ *
+ * @param {FrameNode} parent - Parent vertical stack.
+ * @param {string} name - Token name (e.g. "spacing/sm").
+ * @param {number} value - Spacing value in pixels.
+ * @param {Variable} variable - Figma Variable to bind the width to.
+ * @param {string} codeSyntax - CSS variable string (e.g. "var(--spacing-sm)").
+ */
+async function createSpacingBar(parent, name, value, variable, codeSyntax) {
+  await figma.loadFontAsync({ family: 'Inter', style: 'Regular' });
+
+  const row = figma.createFrame();
+  row.name = `Spacing/${name}`;
+  row.layoutMode = 'HORIZONTAL';
+  row.counterAxisAlignItems = 'CENTER';
+  row.itemSpacing = 16;
+  row.layoutSizingHorizontal = 'FILL';
+  row.layoutSizingVertical = 'HUG';
+  row.fills = [];
+  parent.appendChild(row);
+
+  // The bar rectangle — width bound to spacing variable
+  const bar = figma.createRectangle();
+  bar.resize(value, 16);
+  bar.cornerRadius = 3;
+  bar.fills = [{ type: 'SOLID', color: { r: 0.22, g: 0.47, b: 0.98 } }];
+  // Bind width to the spacing variable so it reflects the actual token value
+  if (variable) {
+    bar.setBoundVariable('width', variable);
+  }
+  row.appendChild(bar);
+
+  // Label: "spacing/sm  8px  var(--spacing-sm)"
+  const label = figma.createText();
+  label.fontName = { family: 'Inter', style: 'Regular' };
+  label.characters = `${name}  ${value}px  ${codeSyntax}`;
+  label.fontSize = 12;
+  label.fills = [{ type: 'SOLID', color: { r: 0.35, g: 0.35, b: 0.35 } }];
+  row.appendChild(label);
+
+  return row;
+}
+```
+
+### Spacing section builder
+
+```javascript
+/**
+ * Creates the full spacing documentation section.
+ *
+ * @param {FrameNode} root - Root vertical stack.
+ * @param {Array<{name, value, variable, codeSyntax}>} spacingTokens - Token definitions.
+ */
+async function createSpacingSection(root, spacingTokens) {
+  await figma.loadFontAsync({ family: 'Inter', style: 'Bold' });
+
+  const section = figma.createFrame();
+  section.name = 'Section/Spacing';
+  section.layoutMode = 'VERTICAL';
+  section.itemSpacing = 12;
+  section.layoutSizingHorizontal = 'FILL';
+  section.layoutSizingVertical = 'HUG';
+  section.fills = [];
+  root.appendChild(section);
+
+  const heading = figma.createText();
+  heading.fontName = { family: 'Inter', style: 'Bold' };
+  heading.characters = 'Spacing';
+  heading.fontSize = 32;
+  heading.fills = [{ type: 'SOLID', color: { r: 0.07, g: 0.07, b: 0.07 } }];
+  section.appendChild(heading);
+
+  for (const tok of spacingTokens) {
+    await createSpacingBar(section, tok.name, tok.value, tok.variable, tok.codeSyntax);
+  }
+
+  return section;
+}
+```
+
+---
+
+## 6. Shadow Cards (Elevation)
+
+Elevation documentation shows cards with progressively stronger drop shadows, labeled with name and effect parameters.
+
+### Single shadow card
+
+```javascript
+/**
+ * Creates a shadow card: a white rectangle with a drop shadow effect,
+ * labeled with the elevation name and shadow parameters.
+ *
+ * @param {FrameNode} parent - The horizontal row to append to.
+ * @param {string} name - Elevation name (e.g. "Shadow/Medium").
+ * @param {DropShadowEffect[]} effects - Array of Figma effect objects.
+ */
+async function createShadowCard(parent, name, effects) {
+  await figma.loadFontAsync({ family: 'Inter', style: 'Regular' });
+  await figma.loadFontAsync({ family: 'Inter', style: 'Medium' });
+
+  const card = figma.createFrame();
+  card.name = `ShadowCard/${name}`;
+  card.layoutMode = 'VERTICAL';
+  card.primaryAxisAlignItems = 'CENTER';
+  card.counterAxisAlignItems = 'CENTER';
+  card.itemSpacing = 8;
+  card.paddingTop = 16;
+  card.paddingBottom = 16;
+  card.resize(120, 120);
+  card.cornerRadius = 8;
+  card.fills = [{ type: 'SOLID', color: { r: 1, g: 1, b: 1 } }];
+  card.effects = effects;
+  parent.appendChild(card);
+
+  // Elevation name
+  const nameLabel = figma.createText();
+  nameLabel.fontName = { family: 'Inter', style: 'Medium' };
+  nameLabel.characters = name.split('/').pop();
+  nameLabel.fontSize = 12;
+  nameLabel.textAlignHorizontal = 'CENTER';
+  nameLabel.fills = [{ type: 'SOLID', color: { r: 0.2, g: 0.2, b: 0.2 } }];
+  card.appendChild(nameLabel);
+
+  // Effect parameters as small text
+  if (effects.length > 0) {
+    const e = effects[0];
+    if (e.type === 'DROP_SHADOW') {
+      const params = figma.createText();
+      params.fontName = { family: 'Inter', style: 'Regular' };
+      params.characters = `x:${e.offset.x} y:${e.offset.y}\nblur:${e.radius}`;
+      params.fontSize = 10;
+      params.textAlignHorizontal = 'CENTER';
+      params.fills = [{ type: 'SOLID', color: { r: 0.55, g: 0.55, b: 0.55 } }];
+      card.appendChild(params);
+    }
+  }
+
+  return card;
+}
+```
+
+### Shadow section builder
+
+```javascript
+/**
+ * Creates the full elevation/shadow documentation section.
+ *
+ * @param {FrameNode} root - Root vertical stack.
+ * @param {Array<{name, effects}>} shadowTokens - Shadow definitions.
+ */
+async function createShadowSection(root, shadowTokens) {
+  await figma.loadFontAsync({ family: 'Inter', style: 'Bold' });
+
+  const section = figma.createFrame();
+  section.name = 'Section/Elevation';
+  section.layoutMode = 'VERTICAL';
+  section.itemSpacing = 24;
+  section.layoutSizingHorizontal = 'FILL';
+  section.layoutSizingVertical = 'HUG';
+  section.fills = [];
+  root.appendChild(section);
+
+  const heading = figma.createText();
+  heading.fontName = { family: 'Inter', style: 'Bold' };
+  heading.characters = 'Elevation';
+  heading.fontSize = 32;
+  heading.fills = [{ type: 'SOLID', color: { r: 0.07, g: 0.07, b: 0.07 } }];
+  section.appendChild(heading);
+
+  // Cards row — extra top padding so shadows are visible
+  const row = figma.createFrame();
+  row.name = 'Elevation/Row';
+  row.layoutMode = 'HORIZONTAL';
+  row.itemSpacing = 32;
+  row.paddingTop = 24;
+  row.paddingBottom = 40;
+  row.layoutSizingHorizontal = 'FILL';
+  row.layoutSizingVertical = 'HUG';
+  row.fills = [{ type: 'SOLID', color: { r: 0.97, g: 0.97, b: 0.97 } }];
+  row.cornerRadius = 8;
+  row.paddingLeft = 24;
+  row.paddingRight = 24;
+  section.appendChild(row);
+
+  for (const tok of shadowTokens) {
+    await createShadowCard(row, tok.name, tok.effects);
+  }
+
+  return section;
+}
+```
+
+---
+
+## 7. Border Radius Demo
+
+Border radius documentation shows rectangles at each corner radius value, labeled with the token name and pixel value.
+
+### Single radius card
+
+```javascript
+/**
+ * Creates a single border radius card: a square with corner radius applied,
+ * labeled with the token name and pixel value.
+ *
+ * @param {FrameNode} parent - The horizontal row to append to.
+ * @param {string} name - Token name (e.g. "radius/md").
+ * @param {number} value - Corner radius in pixels (0 for none, 9999 for full).
+ * @param {Variable} [variable] - Optional Figma Variable to bind corner radius.
+ */
+async function createRadiusCard(parent, name, value, variable) {
+  await figma.loadFontAsync({ family: 'Inter', style: 'Regular' });
+  await figma.loadFontAsync({ family: 'Inter', style: 'Medium' });
+
+  const wrapper = figma.createFrame();
+  wrapper.name = `Radius/${name}`;
+  wrapper.layoutMode = 'VERTICAL';
+  wrapper.primaryAxisAlignItems = 'CENTER';
+  wrapper.counterAxisAlignItems = 'CENTER';
+  wrapper.itemSpacing = 8;
+  wrapper.fills = [];
+  wrapper.layoutSizingHorizontal = 'FIXED';
+  wrapper.layoutSizingVertical = 'HUG';
+  wrapper.resize(96, 1);
+  parent.appendChild(wrapper);
+
+  const rect = figma.createRectangle();
+  rect.resize(72, 72);
+  rect.fills = [{ type: 'SOLID', color: { r: 0.22, g: 0.47, b: 0.98, a: 0.15 } }];
+  rect.strokes = [{ type: 'SOLID', color: { r: 0.22, g: 0.47, b: 0.98 } }];
+  rect.strokeWeight = 1.5;
+
+  // Cap display value — 9999 is how Figma represents "full/pill"
+  const displayRadius = Math.min(value, 36);
+  rect.cornerRadius = displayRadius;
+
+  // Bind to variable if provided
+  if (variable) {
+    rect.setBoundVariable('cornerRadius', variable);
+  }
+  wrapper.appendChild(rect);
+
+  const nameLabel = figma.createText();
+  nameLabel.fontName = { family: 'Inter', style: 'Medium' };
+  nameLabel.characters = name.split('/').pop();
+  nameLabel.fontSize = 11;
+  nameLabel.textAlignHorizontal = 'CENTER';
+  nameLabel.fills = [{ type: 'SOLID', color: { r: 0.2, g: 0.2, b: 0.2 } }];
+  wrapper.appendChild(nameLabel);
+
+  const valueLabel = figma.createText();
+  valueLabel.fontName = { family: 'Inter', style: 'Regular' };
+  valueLabel.characters = value >= 9999 ? 'full' : `${value}px`;
+  valueLabel.fontSize = 10;
+  valueLabel.textAlignHorizontal = 'CENTER';
+  valueLabel.fills = [{ type: 'SOLID', color: { r: 0.55, g: 0.55, b: 0.55 } }];
+  wrapper.appendChild(valueLabel);
+
+  return wrapper;
+}
+```
+
+### Radius section builder
+
+```javascript
+/**
+ * Creates the full border radius documentation section.
+ *
+ * @param {FrameNode} root - Root vertical stack.
+ * @param {Array<{name, value, variable}>} radiusTokens - Radius token definitions.
+ */
+async function createRadiusSection(root, radiusTokens) {
+  await figma.loadFontAsync({ family: 'Inter', style: 'Bold' });
+
+  const section = figma.createFrame();
+  section.name = 'Section/Radius';
+  section.layoutMode = 'VERTICAL';
+  section.itemSpacing = 24;
+  section.layoutSizingHorizontal = 'FILL';
+  section.layoutSizingVertical = 'HUG';
+  section.fills = [];
+  root.appendChild(section);
+
+  const heading = figma.createText();
+  heading.fontName = { family: 'Inter', style: 'Bold' };
+  heading.characters = 'Border Radius';
+  heading.fontSize = 32;
+  heading.fills = [{ type: 'SOLID', color: { r: 0.07, g: 0.07, b: 0.07 } }];
+  section.appendChild(heading);
+
+  const row = figma.createFrame();
+  row.name = 'Radius/Row';
+  row.layoutMode = 'HORIZONTAL';
+  row.itemSpacing = 24;
+  row.paddingTop = 24;
+  row.paddingBottom = 24;
+  row.paddingLeft = 24;
+  row.paddingRight = 24;
+  row.layoutSizingHorizontal = 'FILL';
+  row.layoutSizingVertical = 'HUG';
+  row.fills = [{ type: 'SOLID', color: { r: 0.97, g: 0.97, b: 0.97 } }];
+  row.cornerRadius = 8;
+  section.appendChild(row);
+
+  for (const tok of radiusTokens) {
+    await createRadiusCard(row, tok.name, tok.value, tok.variable);
+  }
+
+  return section;
+}
+```
+
+---
+
+## 8. Documentation Alongside Components
+
+Each component page should include a documentation frame directly on the canvas, placed to the left of the component set. This keeps docs and the component in sync without requiring a separate file.
+
+### Component page documentation frame
+
+```javascript
+/**
+ * Creates the documentation frame for a component page: title, description,
+ * and usage notes, positioned at x=0 with the component set to its right.
+ *
+ * @param {PageNode} page - The component page (must already be current).
+ * @param {string} componentName - The component name.
+ * @param {string} description - What the component does and when to use it.
+ * @param {string[]} usageNotes - Bullet points for usage guidance.
+ * @returns {FrameNode} The documentation frame.
+ */
+async function createComponentDocFrame(page, componentName, description, usageNotes) {
+  await figma.loadFontAsync({ family: 'Inter', style: 'Bold' });
+  await figma.loadFontAsync({ family: 'Inter', style: 'Regular' });
+
+  const doc = figma.createFrame();
+  doc.name = '_Doc';
+  doc.layoutMode = 'VERTICAL';
+  doc.itemSpacing = 16;
+  doc.paddingTop = 40;
+  doc.paddingBottom = 40;
+  doc.paddingLeft = 40;
+  doc.paddingRight = 40;
+  doc.layoutSizingHorizontal = 'FIXED';
+  doc.layoutSizingVertical = 'HUG';
+  doc.resize(360, 1);
+  doc.fills = [];
+  doc.x = 0;
+  doc.y = 0;
+  page.appendChild(doc);
+
+  // Component name — large heading
+  const title = figma.createText();
+  title.fontName = { family: 'Inter', style: 'Bold' };
+  title.characters = componentName;
+  title.fontSize = 28;
+  title.fills = [{ type: 'SOLID', color: { r: 0.07, g: 0.07, b: 0.07 } }];
+  title.layoutSizingHorizontal = 'FILL';
+  doc.appendChild(title);
+
+  // Description
+  const descText = figma.createText();
+  descText.fontName = { family: 'Inter', style: 'Regular' };
+  descText.characters = description;
+  descText.fontSize = 13;
+  descText.lineHeight = { value: 20, unit: 'PIXELS' };
+  descText.fills = [{ type: 'SOLID', color: { r: 0.35, g: 0.35, b: 0.35 } }];
+  descText.layoutSizingHorizontal = 'FILL';
+  doc.appendChild(descText);
+
+  // Divider
+  const divider = figma.createRectangle();
+  divider.resize(280, 1);
+  divider.fills = [{ type: 'SOLID', color: { r: 0.88, g: 0.88, b: 0.88 } }];
+  divider.layoutSizingHorizontal = 'FILL';
+  doc.appendChild(divider);
+
+  // Usage notes
+  if (usageNotes.length > 0) {
+    const usageHeading = figma.createText();
+    usageHeading.fontName = { family: 'Inter', style: 'Bold' };
+    usageHeading.characters = 'Usage';
+    usageHeading.fontSize = 13;
+    usageHeading.fills = [{ type: 'SOLID', color: { r: 0.07, g: 0.07, b: 0.07 } }];
+    doc.appendChild(usageHeading);
+
+    for (const note of usageNotes) {
+      const noteText = figma.createText();
+      noteText.fontName = { family: 'Inter', style: 'Regular' };
+      noteText.characters = `• ${note}`;
+      noteText.fontSize = 12;
+      noteText.lineHeight = { value: 18, unit: 'PIXELS' };
+      noteText.fills = [{ type: 'SOLID', color: { r: 0.4, g: 0.4, b: 0.4 } }];
+      noteText.layoutSizingHorizontal = 'FILL';
+      doc.appendChild(noteText);
+    }
+  }
+
+  return doc;
+}
+```
+
+---
+
+## 9. Critical Rules
+
+1. **Bind swatches to variables** — use `setBoundVariableForPaint` for color fills, `setBoundVariable('width', ...)` for spacing bars, and `setBoundVariable('cornerRadius', ...)` for radius cards. Never hardcode values that have corresponding variables.
+2. **Foundations page comes before component pages** — always insert it between the file structure separators and the first component page.
+3. **Show both primitive and semantic layers** — if the system has a Primitives collection and a semantic Color collection, document both on the Foundations page with clear section labels.
+4. **Page frame width = 1440px** — this is the convention across Simple DS, Polaris, and Material 3. Use it unless you detect a different existing convention via `get_metadata`.
+5. **Section spacing = 64–80px** — the gap between color / typography / spacing / shadow / radius sections should be at minimum 64px so the page is scannable.
+6. **Match existing page style** — if the target file uses emoji page name prefixes or a decorative separator style, carry that through to the Foundations page name.
+7. **Include code syntax in labels** — where variables have code syntax set, display the CSS variable name in the swatch/bar label so developers can copy it directly.