A practical naming guide for Figma variables
A small system for naming primitives, semantic tokens, component variables, and modes so design and code can stay aligned.
Variable naming is not clerical work. It is how a team explains which decisions are stable and which decisions are allowed to change.
I like to separate variables into three layers: primitives, semantics, and component-level decisions. Primitives describe raw values. Semantic variables describe intent. Component variables describe a specific implementation need.
Primitive names can be plain: green-500, gray-900, space-4, radius-2. They should not pretend to know where they will be used. Their job is to provide a controlled material palette.
Semantic names should explain purpose: color-bg-page, color-text-muted, color-border-strong, color-action-primary. These are the names designers and engineers should reach for most often because they survive redesigns better than literal color names.
Component variables are useful when a component has real local behavior: button-primary-bg, card-border, input-focus-ring. The trap is making every visual decision component-specific. That creates a design system that cannot be themed or maintained.
Modes should describe product context, not just aesthetics. Light and dark are modes. Brand, seasonal campaign, enterprise, or high-contrast can also be modes when the product actually needs them.
Good naming also needs restraint. If the team cannot predict which token to use, the system is too clever. A smaller set of obvious names will beat a larger set of technically complete names every time.
The test is handoff. If an engineer can inspect a Figma component and understand the intended CSS variable without asking the designer, the naming is doing its job.