Figma Documentation Rules

Figma design system files serve two purposes: they are the source of truth for visual decisions, and they are documentation that designers and developers reference daily. These rules ensure documentation pages are consistent, maintainable, and useful.

Page Structure

Every documentation page follows the same layout:

1. Header component instance — a reusable component containing the project logo area, page title, and subtitle.
2. Content frame — a frame with vertical auto-layout, consistent padding, and a white fill. The frame width should match the project's primary design breakpoint.

This two-part structure keeps every page visually consistent and makes it immediately clear which page you are on.

Token Documentation Layout

Token documentation uses tabular rows to display each token's swatch and metadata:

• Left side: color swatch (bound to the Figma variable) + bold token name.
• Right side: hex value, right-aligned.
• Grouping: rows are organised into sections by element — background, foreground, border, action, overlay, etc.
• Section headers: each group has a title and optional description explaining the category.

This layout mirrors how developers consume tokens in code: name on the left, value on the right, grouped by purpose.

Layer Naming

Every frame and group must have a semantic name:

• Use descriptive names: "Background Section", "Token Row", "Typography Specimens".
• Never leave auto-generated names: "Frame 47", "Group 3", "Rectangle 12".
• Component instances retain their component name automatically — do not rename them.

Font Declaration

Document which font families and styles the project uses:

• Specify the heading font family and weight (e.g., "Display: Inter SemiBold").
• Specify the body font family and weight (e.g., "Body: Inter Regular").
• Specify the monospace font if used (e.g., "Mono: JetBrains Mono").

Variable Binding Rules

When creating token documentation with bound swatches:

• Color swatches: use setBoundVariableForPaint() to bind fills to variables. This keeps documentation swatches live — when the variable value changes, the swatch updates automatically.
• Corner radius: bind per-corner radius properties (topLeftRadius, topRightRadius, etc.), not the shorthand cornerRadius property. The shorthand does not persist variable bindings correctly.
• All values in px: Figma works exclusively in pixels. REM conversion happens in code, not in Figma. When documenting scale tokens, show the px value in Figma and note the REM equivalent in a separate column or annotation.

Breakpoint Scaling Tables

When a project targets multiple breakpoints or device sizes with different root font sizes:

• Include a table with one column per breakpoint.
• Each row shows a token name, its REM value, and the resolved px value at each breakpoint.
• Auto-calculate px values: px = REM × root font size.

Example structure:

This makes it immediately clear how spacing and typography scale across targets.

Cross-References

Every token row should map to its CSS custom property name. Use Figma path notation for the variable reference:

• Figma path: Collection / Group / token-name
• CSS property: --token-name

This dual reference helps developers find the corresponding value in both Figma and code without guessing.

No Boolean Component Properties

Single Documentation Breakpoint

Figma documentation pages should target one breakpoint — the primary design target. Do not create multiple versions of documentation pages for different breakpoints.

Other breakpoints are handled in code. The Figma documentation captures the design intent; responsive adaptation is an implementation concern.

Documentation Component Set

All documentation pages use a shared set of .documentation/* components. These live in the Figma file under the .documentation namespace and are published as library components.

.documentation/Header

Component header used at the top of every component documentation page.

• Type: Component, Auto Layout (Vertical)
• Properties:
  • Title (Text) — component name
  • Description (Text) — one-line summary
  • Status Badge (Boolean) — shows draft/ready status
  • Storybook Link (Text) — URL to the component's Storybook page

.documentation/Table

Prop table for documenting a component's API surface.

• Type: Component, Auto Layout (Vertical, Fill/Hug)
• Structure: Bold header row + instance slots for .documentation/Table/Row
• Usage: One table per component. Add rows by inserting .documentation/Table/Row instances.

.documentation/Table/Row

A single row in a prop table.

• Type: Component, Auto Layout (Horizontal, Hug/Hug)
• Properties:
  • Prop (Text) — property name
  • Type (Text) — type signature (e.g., 'neutral' | 'warning')
  • Default (Text) — default value
  • Description (Text) — what the prop controls

.documentation/Anatomy

Visual breakdown of a component's internal structure.

• Type: Component, Auto Layout (Vertical)
• Structure: Image/Frame slot (component preview with callout markers) + Annotation list slot (numbered descriptions of each region)

.documentation/DoAndDont

Side-by-side comparison of correct and incorrect usage.

• Type: Component, Auto Layout (Horizontal)
• Structure: Two equal-width frames. Left frame has a green bottom border (Do). Right frame has a red bottom border (Don't).
• Usage: Place example instances or screenshots in each frame. Add a short caption below each.

.documentation/Divider

Visual separator between documentation sections.

• Type: Component, 1px height line, width Fill Container
• Color: --border-subtle

Assembling a Documentation Page

A complete component documentation page follows this order:

1. .documentation/Header — title, description, status, Storybook link
2. .documentation/Divider
3. .documentation/Table — all props documented
4. .documentation/Divider
5. .documentation/Anatomy — visual breakdown
6. .documentation/Divider
7. .documentation/DoAndDont — usage guidance

Definition of Done

A Figma documentation page is complete when:

• Header component instance is present with correct title
• All tokens in the category are shown with bound swatches
• Hex values are resolved and visible
• Layer names are semantic (no "Frame 47")
• Font families are loaded and rendering correctly
• A screenshot of the page has been reviewed for visual accuracy

Figma Variable Structure

How to organise Figma Variable collections to support the dimensional model.

Collections per Dimension

Each dimension gets its own variable collection. This keeps the collection list navigable and makes it clear which tokens belong to which concern.

Mode Naming

Mode names use the exact vocabulary from the Component API:

• Sentiment modes: neutral, warning, highlight, new, success, error
• Emphasis modes: high, medium, low
• State modes: rest, hover, active, disabled, resolving
• Size modes: xs, sm, md, lg, xl

Cascade Direction

Color collections alias upward through the cascade:

State.Button[hover].background
  → aliases → Emphasis.Button[high].background/hover
    → aliases → Sentiment.Button[neutral].high/bg/hover
      → aliases → Semantic Color[Value].bg/brand/hover
        → aliases → Primitive Color[Dark].brand-dark/400

Every alias link must be a VARIABLE_ALIAS reference in Figma, not a hardcoded value. This ensures theme switching and sentiment changes propagate automatically.

Dual-File Pattern

For larger systems, split into two Figma files:

1. Token file — all variable collections, no component designs
2. Component file — component designs that consume variables from the token file via library publishing

This keeps the token file lightweight and allows token changes to propagate to all component files via library updates.

See Also