@fprad0/skill-master-mcp 0.0.9 → 0.0.11

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

@@ -0,0 +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.