

Naming is the most consequential decision you make when setting up design tokens in Figma. The right naming conventions make a variable library self-documenting, scalable, and developer-friendly. The wrong ones produce a system that's hard to navigate, prone to misuse, and painful to transform into code.
This article covers naming conventions at each tier of the token hierarchy in Figma (primitives, semantic aliases, and component tokens) plus how to use slash notation for grouping, how to scope variables for better usability, and how to approach renaming an existing variable library without breaking references.
Article 14 — Setting up design tokens in Figma covers the collection and mode architecture that sits underneath these naming decisions. The tool-agnostic naming principles are in Article 05 — Naming your design tokens. This article focuses on the Figma-specific implementation.
Figma uses / as a group separator in variable names. A variable named color/blue/500 appears inside a color group, inside a blue subgroup. This is how you express hierarchy within a collection without needing separate collections for every category.
The forward slash is doing real structural work, not just visual organization. When tokens are exported to JSON, the slash notation maps to nested object structure. color/blue/500 becomes color.blue["500"] in the output. How you use it in Figma shapes what your token JSON looks like downstream.
A few principles for working with slash notation:
Be consistent with depth. If your color primitives are two levels deep (color/blue), don't mix in three-level names (color/brand/primary) without a reason. Inconsistent depth makes the library hard to scan and produces uneven JSON structure.
Use slashes to separate category from role, not to express full sentences. color/action/primary is good. color/button/background/default/hover/state is too deep. It's trying to do the work of a component token and a semantic token simultaneously.
Match your naming depth to your tier. Primitives typically need two or three levels (color/blue/500). Semantics need three or four (color/action/primary-hover). Component tokens are naturally deeper (color/input/border/active).
Primitives are raw values, the ingredients of your system. Their names should be neutral, context-free, and meaningful to both designers and developers. Primitives shouldn't imply how they're used, which brand they belong to, or which theme they support. That context comes at the semantic layer.
For color names, clarity beats cleverness. Use recognizable hue names (blue, red, green, purple) rather than invented or brand-specific names. If you need to distinguish subtler hues, lean toward names that are broadly understood rather than proprietary.
For the individual steps within a hue, numeric ramps are the standard approach. The 100–900 scale is widely used and gives you the flexibility to add intermediate values without breaking the naming convention:
color/blue/100
color/blue/300
color/blue/500
color/blue/700
color/blue/900
For colors that don't need a ramp (absolute values like black and white that you don't intend to shade) a base group keeps them separate and signals their singular nature:
color/base/black
color/base/white
Before finalizing your color naming, talk to your developers. Color naming conventions often already exist in the codebase, and aligning upfront avoids a renaming exercise later.
Use numeric values for spacing variables: the actual pixel value, or a numeric ramp that reflects it:
spacing/base/4
spacing/base/8
spacing/base/16
spacing/base/24
spacing/base/32
If your scale is small enough to be navigable with T-shirt sizes, those work too:
spacing/base/xs
spacing/base/sm
spacing/base/md
spacing/base/lg
spacing/base/xl
What matters most is that one scale serves all spacing needs (margins, padding, gaps, vertical rhythm) rather than having separate scales for different contexts. A unified spacing primitive means a unified spacing system.
Avoid variables for fixed widths, heights, and breakpoints in your shared primitive collection. These are too context-specific to be stable primitives and tend to vary by platform and viewport in ways that make them poor candidates for tokenization at the primitive level.
Keep typography primitives unopinionated. Name font families by their actual name rather than their role:
typography/family/DMSans
typography/family/Fraunces
typography/family/IBMPlexMono
This avoids the problem of a name like typography/family/sans becoming misleading when a brand changes its font. The semantic layer assigns the role; the primitive just stores the value.
For font weights, use numeric values rather than descriptive strings:
typography/weight/400
typography/weight/600
typography/weight/700
Numeric weights are platform-agnostic, unambiguous, and easier to transform. Strings like bold or semibold vary in interpretation across tools and platforms.
For type sizes and line heights, use a numeric ramp that reflects actual values or a simple ordinal scale:
typography/size/12
typography/size/14
typography/size/16
typography/size/20
One important principle: keep color out of typography primitives. Color belongs in the color system, even when it's applied to text. Mixing color decisions into typography variables makes it much harder to theme text colors independently, which is exactly what you need to do in dark mode. Define color/text/primary in your color semantic layer, not inside a typography variable.
Once your primitive collection is set up, unpublish it from your Figma library. Designers shouldn't be reaching into the primitive layer to style components. That's what the semantic layer is for. Hiding primitives from the library panel removes the temptation and steers everyone toward the semantic variables that are intended for direct use.
Semantic variables are where naming does the most work. The name should communicate the role of a value (what it's for and where it's used) not the value itself.
Base-level semantic variables cover the common, shared color, spacing, and typography decisions that apply across the whole product. Name them by function:
color/base/brand/primary/default
color/base/brand/primary/hover
color/base/background/default
color/base/background/subtle
color/base/border/default
color/base/border/disabled
color/base/text/primary
color/base/text/secondary
color/base/text/disabled
typography/base/family/heading
typography/base/family/body
typography/base/size/h1
typography/base/size/body
typography/base/weight/heading
The base grouping distinguishes these shared semantics from component-specific tokens in the same collection. Alias them to primitives wherever possible. color/base/border/default should point to color/neutral/200 (or whatever your border color is in the palette), not hardcode a hex value. Aliasing is what makes future changes manageable.
A good semantic name describes purpose, not appearance. It would still be accurate if the underlying value changed significantly: a different hue, a lighter shade, a different font entirely. Test any proposed name against this: if color/base/background/default changed from near-white to near-black (light to dark mode), does the name still make sense? If yes, it's a good semantic name.
Names that describe appearance (color/base/light-grey, typography/base/large-font) fail this test immediately. They work until the value changes, which is exactly when you need the name to remain stable.
Component tokens are scoped to a specific component and express decisions that are genuinely component-specific: decisions that can't be expressed through base semantics alone.
Name them with the component first, then the element, then the property, then the state:
color/input/text/label/default
color/input/text/label/disabled
color/input/text/content/default
color/input/text/content/placeholder
color/input/text/content/disabled
color/input/text/message/helper
color/input/text/message/error
color/input/border/default
color/input/border/active
color/input/border/disabled
color/input/background/default
color/input/background/disabled
This is verbose, but intentionally so. Every token answers two questions at once: where it's used and what it controls. That explicitness is what makes component tokens worth the overhead.
Keep the variable set only as large as it needs to be. As Stu Robson has noted, the number of design tokens in a system tends to reflect how well an organization communicates. A sprawling token set often signals fragmented decision-making as much as thoroughness. Audit which states and variants you actually implement before defining tokens for every conceivable scenario.
Figma lets you restrict which property contexts a variable appears in. A color variable scoped to "Fill" won't clutter the stroke color picker; a spacing variable scoped to "Gap" won't appear in the border width field.
Scoping improves the day-to-day experience of using variables in Figma significantly. Designers find the right variable faster because irrelevant options are filtered out. It also reduces misuse: a semantic spacing variable that shouldn't be used for border radius can be scoped to exclude that property.
Invest time in scoping when publishing semantic and component collections. The payoff compounds across everyone who uses the library.
Renaming variables in an existing Figma library is one of the most disruptive changes you can make. Every component that references a renamed variable will show a broken reference until it's re-linked. A few practices make migration less painful:
Rename in batch, not piecemeal. Partial renames leave your library in an inconsistent state for weeks. Scope the full rename, do it in one session, and republish the library so consuming files can update all at once.
Use Figma's variable renaming tool. When you rename a variable in the Variables panel rather than deleting and recreating it, Figma maintains the reference, and components update to the new name automatically rather than breaking. Never delete and recreate a variable as a renaming method.
Communicate before you publish. A library update that renames hundreds of variables is disruptive. Let consuming teams know what's changing and why before you publish, so they're not surprised by broken references in their files.
Prioritize semantic variables over primitives. If you can only clean up one tier, start with semantics. They're the variables designers actually use in components, so better naming there has the highest day-to-day impact. Primitive renames matter more for developer-facing outputs than for the design experience.
Article 16 — Figma variable modes in depth covers how to use Figma's modes system for theming, dark mode, and brand switching — building directly on the variable structure set up in this article and Article 14.
For the code-side naming conventions that these Figma names need to align with, Article 05 — Naming your design tokens covers the tool-agnostic naming principles in full.
