/figma-generate-library

Part of the figma-generate-library skill.

Naming Conventions Reference

This reference documents every naming convention used in the figma-generate-library workflow. Cover all naming decisions in order: variables, components, pages, variants, styles, separators, status indicators. The last section explains when to match an existing file's conventions vs. using the defaults here.

1. Variable Naming

Slash hierarchy (the universal pattern)

All Figma variables use slash-separated paths. The slash creates visual grouping in the Variables panel and maps directly to the token hierarchy in code.

{category}/{subcategory}/{role}

Real examples from Simple DS and Material 3:

color/bg/primary
color/bg/secondary
color/text/primary
color/text/muted
color/border/default
color/border/focus
color/feedback/error
color/feedback/success
spacing/xs
spacing/sm
spacing/md
spacing/lg
spacing/xl
spacing/2xl
radius/none
radius/sm
radius/md
radius/lg
radius/full
typography/body/font-size
typography/body/line-height
typography/heading/font-size
typography/heading/font-weight

Primitives collection

Primitive variables hold raw values and are not exposed to consumers (scope = []). They use a flat {family}/{step} format matching the color scale convention from Simple DS:

blue/50
blue/100
blue/200
...
blue/900
gray/50
gray/100
...
gray/900
red/500
green/500

Step numbers follow the convention of the target codebase. If the codebase uses 100–900, use that. If it uses 50–950, use that. If there is no codebase convention, use 100–900 in increments of 100.

Semantic collection

Semantic variables alias primitives. They use the role-based {category}/{role} or {category}/{subcategory}/{role} pattern:

color/bg/primary         → alias: primitives/white (light), primitives/gray/900 (dark)
color/bg/secondary       → alias: primitives/gray/100 (light), primitives/gray/800 (dark)
color/text/primary       → alias: primitives/gray/900 (light), primitives/white (dark)
color/text/secondary     → alias: primitives/gray/600 (light), primitives/gray/400 (dark)
color/border/default     → alias: primitives/gray/200 (light), primitives/gray/700 (dark)

Rule: Semantic variables must never hold raw hex values — they always alias a primitive. If you need a new color value, create the primitive first, then create the semantic alias.

Casing

Default: Use lowercase with forward slashes: color/bg/primary, spacing/2xl.

When to deviate:

• If the existing file uses PascalCase (e.g., Material 3 uses Schemes/Primary) — match it.
• If the design team prefers PascalCase for readability in the Variables panel — acceptable as long as the code syntax is separately defined and uses the platform-correct case.
• Mode names can use spaces and mixed case (e.g., SDS Light, Mode 1 → Light) — these are labels, not identifiers.

Never: camelCase inside variable names (colorBgPrimary as a Figma name is wrong — that belongs in Android code syntax only). Never use spaces inside a path segment: color/bg primary is wrong; color/bg/primary is correct.

Key distinction: The casing rule applies to Figma variable names. Code syntax names follow platform conventions regardless of the Figma name case — see §9 for the full picture.

2. Component Naming

Main components: PascalCase, no prefix

Published components intended for library consumers use plain PascalCase names:

Button
Input
Checkbox
Toggle
Avatar
Badge
Card
Dialog
Tooltip
Banner

Do not use a namespace prefix for public components (e.g., do not name them DS/Button or sds-Button). Slashes in component names create nested grouping in the Assets panel, which is correct for sub-components but not for top-level public components.

Sub-components: underscore prefix + slash namespace

Internal sub-components that are NOT meant for library consumers use the _ prefix. This hides them from the Assets panel by default and signals to other designers that they should not be used directly.

_Button/Slot           (internal icon slot for Button)
_Input/Indicator       (internal state indicator for Input)
_Badge/Dot             (internal dot sub-component of Badge)
_Parts/Avatar.Status   (UI3 pattern: _Parts/{ParentName}.{SubPart})
_Slider/Handle         (UI3 pattern: _{ParentName}/{SubPart})

Pattern rules:

• Use _ prefix for ALL internal sub-components — no exceptions.
• Use slash namespacing to group sub-components under their parent: _Button/IconSlot.
• For sub-components shared by multiple parents, use _Parts/{ComponentName}.{SubPart}.

Private documentation components

Components used only for internal documentation (not for production use) use the . prefix:

.ExampleCard
.GuidelineHeader
.DemoFrame

This hides them from consumers while keeping them accessible on the canvas.

3. Page Naming

Five reference design systems use three distinct naming patterns. Choose one pattern and apply it consistently across all pages in the file.

Pattern 1: Plain names (Simple DS, Material 3, Polaris)

The most common pattern. Clean, readable, no decoration.

Cover
---
Foundations
Icons
---
Accordion
Avatars
Buttons
Cards
Dialog
Inputs
Menu
---
Utilities
Component Playground

Use this pattern when starting from scratch or when the target file already uses this style.

Pattern 2: Emoji prefix + status (UI3 Library)

The most expressive pattern. The page name encodes asset type, design status, and code readiness.

Anatomy: [Asset Type Emoji] [Optional FPL Label] [Status Circle] Component Name [Code Status Bracket]

Examples:

Overview
Status Key
---
FPL COMPONENTS (go/fpl)
[C-flag] FPL [Green] Buttons
[C-flag] FPL [Green] Inputs
[C-flag] FPL [Yellow] Popovers [future]
---
UI3 COMPONENTS
[C-flag] [Green] Comments
---
PATTERNS
[P-flag] [Green] Editor / Layers
---
[Book] Cover
[Headstone] Deprecated

Use this pattern only when building a large, multi-team design system where lifecycle tracking is needed, or when the target file already uses it.

Pattern 3: Emoji prefix (Shop Minis)

A lighter version of the UI3 pattern without status circles.

📔 Cover
ℹ️ About
🚀 Getting started
——— THEME ———
Color
Typography
Spacing
——— COMPONENTS ———
Button
Input
Card

Use this pattern when the target file already uses emoji prefixes but does not need lifecycle tracking.

Universal rules (all patterns)

• Cover is always first.
• Separator pages come before and after each logical section.
• Foundation/token pages always come before component pages.
• Utility and internal pages always come last.
• Pick one convention and do not mix patterns within a file.

4. Variant Naming

Property=Value format

All component variant properties and their values use Property=Value format in the Figma component set:

Size=Small, Style=Primary, State=Default
Size=Medium, Style=Secondary, State=Hover
Size=Large, Style=Ghost, State=Disabled

Actual property names match code prop names where possible:

Property value casing

Property values use Title Case in Figma (to be readable in the Variants panel), mapping to lowercase in code:

Boolean properties

Boolean component properties in Figma use true / false as values (Figma's native boolean), not Yes / No or On / Off.

5. Style Naming (Text and Effect Styles)

Text styles: category/name

Display/Large
Display/Medium
Display/Small
Heading/1
Heading/2
Heading/3
Body/Large
Body/Medium
Body/Small
Label/Large
Label/Small
Code/Inline

The category segment maps to the typographic role. Use the same category names as the codebase's typography scale where possible.

Effect styles (shadows): category/name

Shadow/None
Shadow/Subtle
Shadow/Medium
Shadow/Strong
Shadow/Overlay
Elevation/0
Elevation/1
Elevation/2
Elevation/3
Elevation/4
Elevation/5

Use Shadow/ for named semantic shadows. Use Elevation/N for Material Design-style numbered elevation levels.

6. Separator Pages

Separator pages are empty pages whose sole purpose is to create visual breaks in the Figma page panel. Two conventions:

The three-dash convention (---) is the most common and the default for new files. Use it unless the target file uses the decorated-text style.

Where to place separators:

Cover
---                    ← after cover
Foundations
Icons
---                    ← before components
[component pages]
---                    ← before utilities
Utilities

7. Status Indicators (UI3 Emoji System)

The UI3 Library uses colored circle emojis in page names to communicate design readiness at a glance. This system is optional but powerful for large teams.

Code readiness is communicated via brackets appended to the component name:

Documentation status (within component pages):

If building a UI3-style system, each documentation frame gets a status banner with one of these labels:

• APPROVED — fully vetted
• READY FOR REVIEW — awaiting sign-off
• WORK IN PROGRESS — actively being designed
• NEEDS UPDATE — outdated, requires revision
• DO NOT REFERENCE — should not be used

This system is only recommended for large, multi-team systems where lifecycle tracking provides real value. For smaller systems, skip the emoji status indicators and use plain page names.

8. When to Match Existing vs. Use Defaults

Always inspect before naming anything. Run get_metadata or inspectFileStructure to discover existing conventions before creating any pages or variables.

Match the existing file when:

• The file already has pages with a consistent naming pattern (emoji prefixes, separator style, casing).
• The file already has variable collections with an established naming scheme.
• The file was started by a design team and carries intentional decisions.
• Any existing component names use a specific pattern (PascalCase, kebab-case, namespace prefixes).

Use the defaults from this document when:

• Starting a brand-new Figma file with no existing content.
• The existing conventions are inconsistent (mix of styles = no convention to match).
• The user explicitly asks for a fresh design system following best practices.

When code and Figma disagree:

If the codebase uses button-primary but Figma has a component named Button, do not rename the Figma component. Instead:

• Keep the Figma name as Button (PascalCase, human-readable).
• Set variable code syntax to match the exact CSS token name from the codebase.
• Set Code Connect source path to the actual code file and use the exact code component name.

The rule: Figma names are for designers; code syntax and Code Connect source paths carry the exact code identifiers. These two identity systems operate in parallel.

9. Figma Variable Names vs Code Names — The Full Picture

This is one of the most misunderstood areas. Figma names and code names follow different conventions on purpose — they serve different audiences and live in different environments.

Why they differ

The transformation

Figma variable name              Code syntax (WEB)
──────────────────               ─────────────────
color/bg/primary          →      var(--color-bg-primary)
spacing/xs                →      var(--spacing-xs)
radius/md                 →      var(--radius-md)
typography/body/font-size →      var(--typography-body-font-size)

Pattern: replace "/" with "-", wrap in var(--)

**CRITICAL: The `var()` wrapper is REQUIRED for WEB code syntax.** Figma expects the full CSS function syntax — not just the property name. If you set `--color-bg-primary` (without `var()`), Dev Mode will show raw hex values instead of the variable reference. Always set `var(--color-bg-primary)`.

Figma variable name              Code syntax (ANDROID)
──────────────────               ─────────────────────
color/bg/primary          →      colorBgPrimary
spacing/xs                →      spacingXs
radius/md                 →      radiusMd

Pattern: replace "/" with "", capitalize each word after first

Figma variable name              Code syntax (iOS)
──────────────────               ─────────────────
color/bg/primary          →      Color.bgPrimary
spacing/xs                →      Spacing.xs
radius/md                 →      Radius.md

Pattern: first segment becomes class name, remainder becomes property (camelCase)

Real-world examples from the 5 reference files

Key observation from Material 3: The Figma name Schemes/Primary uses PascalCase with a space, but the WEB code syntax is var(--md-sys-color-primary) — entirely kebab-case with a vendor prefix md-sys-. The Figma name and the code syntax bear almost no resemblance. This is intentional and common in mature design systems.

Casing in Figma: lowercase is default, PascalCase is valid for display

The guideline to use lowercase is a default, not a universal rule. Evidence from real files:

Rule: Use lowercase when the Figma name will map directly to the CSS name. Use PascalCase (or match existing file) when the design system has human-readable variable names that are distinct from the technical code names.

When the codebase doesn't use CSS custom properties

Some JavaScript-first systems (Chakra, Ant Design, MUI) don't use CSS var(--...) at all. Their tokens live in JS theme objects:

Chakra:    colors.gray[500]         →  JS: theme.colors.gray[500]
Ant:       colorPrimary             →  JS: token.colorPrimary
MUI:       palette.primary.main     →  JS: theme.palette.primary.main

In these cases, set WEB code syntax to the JS property path rather than a CSS variable:

// For a JS-object-based system like Chakra:
v.setVariableCodeSyntax('WEB', 'colors.gray.500');

// For Ant Design:
v.setVariableCodeSyntax('WEB', 'colorPrimary');

Hierarchy depth: match the codebase

The number of slash levels should mirror the codebase's nesting depth:

Important: Vendor prefixes (--p-, --md-sys-, --cds-) belong in the code syntax, not the Figma variable name. The Figma name color/bg/surface + code syntax var(--p-color-bg-surface) is the correct pattern.

Action at discovery time

During Phase 0 discovery, capture both sides of the mapping explicitly:

For each token found in the codebase:
  CSS variable:   --sds-color-background-brand-default
  Figma name:     color/bg/brand/default        (slash hierarchy, no vendor prefix)
  WEB syntax:     var(--sds-color-background-brand-default)  (exact CSS name)
  ANDROID syntax: sdsColorBackgroundBrandDefault  (camelCase)
  iOS syntax:     Color.backgroundBrandDefault    (dot-notation)

Store this mapping in the state ledger. Use it when calling setVariableCodeSyntax in Phase 1. Never derive the code syntax from the Figma name if you have the original CSS variable name — always use the original.