Component naming conventions that work in Figma and code

Figma's guide to preparing files for its AI agent says semantic layer names such as HeroImage or PriceLabel support more accurate code generation than defaults like Group 7, and it calls component properties "one of the most useful signals you can give the agent." Naming is now an input to every tool that reads your files.

Component naming conventions are the rules for what you call components, variant properties, props, tokens, and files. A convention that works across Figma and code uses one word for one thing everywhere: the Figma component, the React component, its props and values, and the tokens it reads all share the same names.

Why does naming parity matter now?

Names are the join key between design and code. Figma's Code Connect shows how literal this gets: its figma.enum helper maps Figma variant options to code values, and the docs note that enum values are not normalized, so option names must match exactly. AI tools behave the same way. An agent asked for a Button with size="sm" can reuse your component only if Button and sm are what you actually called them.

Every mismatch between a Figma name and a code name is a lookup table someone has to maintain.

How should you name components?

Start from code, which has the stricter rules. React requires component names to start with a capital letter, so PascalCase is the baseline. Then use the same string in Figma.

• Singular nouns: Button, Card, Avatar. Not Buttons or CardComponent.
• No abbreviations: Description, not Desc; Button, not Btn.
• One word per concept: pick Dialog or Modal, then use it everywhere.
• Parts take the parent's prefix: CardHeader, CardContent, CardFooter, on both surfaces.
• Files follow the component: button.tsx and button.stories.tsx, in whichever casing your repo already uses.
• Slash paths for folders only: Figma's agent guide notes that slash notation such as Button/Primary/Large creates nested groups. Use that for library structure, such as Forms/Input, and keep variation in variant properties.

If you inherit an older file, note that when Figma combines slash-named components into variants, the text before the first slash becomes the component set name and later segments become property values with generic names. Rename those properties to match the props.

Variant properties and props: one vocabulary

The rule: if a Figma property maps to a prop, it uses the prop's name and the prop's values, spelled the same way. shadcn/ui's Button is a useful reference: a variant prop with values such as outline, ghost, and destructive, and a size prop with values such as sm and lg. A Figma Button with properties called Type and Scale holding Primary and Medium describes the same component in a different language.

Booleans

Figma's boolean component properties only control layer visibility. That makes them right for toggles such as showIcon, but a boolean that changes appearance, such as disabled or checked, has to be a variant property with true and false values in Figma. Name it after the HTML or ARIA attribute it mirrors: disabled, required, checked, selected. Radix follows the same pattern, with open, defaultOpen, and onOpenChange on its Dialog.

Enums

When two booleans can't both be true, they are one enum: separate primary and secondary booleans allow an impossible state, and variant="primary" doesn't. Use the same lowercase values in Figma and code.

Design-only properties

Hover and pressed are Figma variants with no prop, because CSS handles them. Call that property state and mark it design-only in its description.

The parity table

Pin this reference in both the Figma file and the repo.

How should you name design tokens?

Name tokens by purpose. Figma's agent guide makes the point directly: color/surface/primary says how a value should be used, while blue-500 doesn't. Keep primitives such as blue/600 for the palette.

Slashes in Figma variable names create nested groups, so color/surface/primary sits in a color group containing surface. In code the same path becomes --color-surface-primary in CSS or color.surface.primary in a theme object. If you exchange tokens in the Design Tokens Community Group format, whose first stable version is 2025.10, know its rules: names can't start with $ or contain {, }, or ., names are case-sensitive, and paths join group and token names with periods.

What should you avoid?

Most naming problems are one of these:

• Appearance in semantic names: BlueButton, text-grey. They break at the first rebrand.
• Position in names: LeftPanel, TopBar. Layouts move; names shouldn't.
• Version suffixes: ButtonNew, CardV2. Use versioning and deprecation instead.
• Product names in shared components: CheckoutButton belongs in the product, not the system.
• Different casing per surface: Primary in Figma, primary in code.

Run a naming audit each quarter: export component and property names from Figma, list exports and props from code, and diff the two. Each line in the diff is a rename or a documented exception.

Where Pegasus fits

Pegasus is built on naming parity. Its Figma library and React code share the same component names, the same variant structure, and the same tokens, so the core of the parity table (component names, variants, and tokens) is already in place across the library.

The 470 design tokens live in Figma as variables for color, type, spacing, radius, and shadow, with light and dark modes, and one token source themes both those variables and the code's theme object. The code is TypeScript React built on shadcn/ui and Base UI primitives.

Because names match, the local MCP server can expose the component catalog (components, props, variants, and tokens) to MCP clients such as Claude Code and Cursor. An agent that asks for a component by name gets the one your designers placed. Follow the same table for your own components and they will fit that catalog.

FAQ

What is the best naming convention for Figma components?

Use the same PascalCase name as the code component, such as Button or CardHeader. Use slash paths only to group components into folders, and express variation through variant properties whose names and values match the code's props. Avoid abbreviations, plurals, colors, positions, and version suffixes in component names.

Should Figma variant names match React props?

Yes. When a Figma variant property has the same name and values as a React prop, designers and engineers share one vocabulary and tools can connect the two without a mapping table. Figma's Code Connect, for example, needs exact option names for enum mappings. The exception is design-only properties, such as hover state, which should be labeled as design-only in Figma.

How should you name boolean props in a design system?

Name booleans after the HTML or ARIA attribute they mirror, such as disabled, checked, required, or open. In Figma, a boolean that changes appearance must be a variant property with true and false values, because boolean component properties only control layer visibility. Replace mutually exclusive booleans with one enum.

Should design tokens use slashes, dots, or dashes?

Use the separator each platform expects and keep the path identical. Figma variables use slashes, which create nested groups. CSS custom properties use dashes, as in --color-surface-primary. JSON theme objects and the Design Tokens Community Group format use dots to join group and token names. The sequence of names must stay constant; the separator can change.

Sources

• AI workflows collection: Refine your components and variables for the Figma agent, Figma Help Center (2026)
• Create and use variants, Figma Help Center (2026)
• Explore component properties, Figma Help Center (2026)
• Code Connect React, Figma developer docs (2026)
• Your First Component, React docs
• Design Tokens Format Module 2025.10, Design Tokens Community Group (2025)
• Button, shadcn/ui (2026)
• Dialog, Radix Primitives (2026)