Unlock Seamless Design Handoffs: Mastering Spacing Tokens in CSS and Figma

Spacing tokens are a cornerstone of modern design systems, acting as the single source of truth for defining whitespace—the margins, paddings, and gaps that structure your user interface. Implementing them effectively in both design tools like Figma and in front-end code like CSS is crucial for achieving visual consistency, improving user experience through clear hierarchy, and streamlining the collaboration between designers and developers. This guide provides a comprehensive approach to defining, applying, and managing spacing tokens across both platforms.

Essential Insights

Establish a Consistent Scale: Base your spacing tokens on a predictable scale, often multiples of a base unit (like 4px or 8px), to ensure harmony and rhythm in your layouts.
Leverage Platform Features: Utilize CSS custom properties (variables) for dynamic application in code and Figma's Variables feature or dedicated plugins (like Tokens Studio) for seamless integration in design mockups.
Synchronize for Consistency: Implement mechanisms to export tokens from Figma and import them into your CSS workflow, maintaining a single source of truth and reducing discrepancies between design and development.

Decoding Spacing Tokens: The Foundation of Consistent Layouts

Spacing tokens are essentially named variables that store specific spacing values (e.g., '8px', '1rem'). Instead of hardcoding pixel values throughout your designs and stylesheets, you reference these tokens. This approach brings several advantages:

Consistency: Ensures uniform spacing across all components and layouts.
Maintainability: Allows global updates to spacing by changing the token value in one central place.
Scalability: Makes it easier to manage spacing rules as the application or design system grows.
Collaboration: Creates a shared language for spacing between designers and developers.
Visual Hierarchy: Helps establish clear relationships between elements through deliberate use of whitespace.

Typically, a design system defines a spacing scale based on a core unit, commonly 4px or 8px. This scale provides a range of predefined steps (e.g., 4px, 8px, 12px, 16px, 24px, 32px) used for all spatial properties like margin, padding, and gap.

Illustration showing how spacing tokens create consistent vertical rhythm between stacked elements

Example illustrating the application of spacing tokens for consistent vertical stacking (Source: Carbon Design System).

Implementing Spacing Tokens in CSS

In CSS, spacing tokens are most effectively implemented using custom properties (variables). This allows for dynamic, reusable, and easily maintainable spacing rules.

Step 1: Defining Your Spacing Scale

Establish Base Units and Scale

Define your tokens within the :root pseudo-class to make them globally available. Choose a base unit (e.g., 8px) and create a scale based on multiples or a consistent progression. Using rem units is often recommended for accessibility and scalability, assuming a standard base font size (e.g., 16px).

:root {
  /* Base scale using 4px increments (relative to 16px root font size) */
  --space-100: 0.25rem;  /* 4px */
  --space-200: 0.5rem;   /* 8px */
  --space-300: 0.75rem;  /* 12px */
  --space-400: 1rem;     /* 16px */
  --space-500: 1.5rem;   /* 24px */
  --space-600: 2rem;     /* 32px */
  --space-800: 3rem;     /* 48px */
  --space-1000: 4rem;    /* 64px */

  /* Optional Semantic Tokens (Aliases) */
  --space-inset-squish: var(--space-200) var(--space-400); /* 8px 16px (e.g., for buttons) */
  --space-stack-medium: var(--space-500); /* 24px (e.g., margin between sections) */
}

Primitive vs. Semantic Tokens

You can use primitive tokens (like --space-400) directly or create semantic tokens (like --space-stack-medium) that alias primitive values for specific use cases. Semantic tokens add context but can increase complexity if overused. Primitive tokens offer more flexibility.

Step 2: Applying Tokens in CSS

Use the defined CSS variables with the var() function to apply spacing values to elements.

.card {
  padding: var(--space-500); /* 24px padding on all sides */
  margin-bottom: var(--space-stack-medium); /* Uses the semantic token for bottom margin */
  background-color: #f0f0f0;
  border-radius: var(--space-200); /* Can also use space tokens for border-radius */
}

.button {
  padding: var(--space-inset-squish); /* Applies 8px top/bottom, 16px left/right */
  margin-right: var(--space-300); /* 12px right margin */
}

.icon-group {
  display: flex;
  gap: var(--space-200); /* 8px gap between flex items */
}

.grid-layout {
  display: grid;
  gap: var(--space-600); /* 32px gap between grid items */
}

Step 3: Handling Responsiveness

Adjust spacing for different screen sizes by redefining CSS variables within media queries.

/* Default spacing */
:root {
  --space-page-padding: var(--space-500); /* 24px */
}

/* Increase padding on larger screens */
@media (min-width: 768px) {
  :root {
    --space-page-padding: var(--space-800); /* 48px */
  }
}

.page-container {
  padding: var(--space-page-padding);
}

Step 4: Considering Logical Properties

For internationalization (supporting right-to-left languages), use logical properties (margin-inline-start, padding-block-end, etc.) with your spacing tokens. This ensures spacing adapts correctly based on writing mode.

.element {
  /* Instead of padding-left */
  padding-inline-start: var(--space-400); /* 16px padding at the start edge */

  /* Instead of margin-bottom */
  margin-block-end: var(--space-600); /* 32px margin at the end in the block direction */
}

Implementing Spacing Tokens in Figma

Figma offers robust ways to manage spacing tokens, primarily through its native Variables feature and powerful community plugins like Tokens Studio.

Method 1: Using Figma Variables (Native)

Creating Spacing Variables

Figma's Variables allow you to define reusable values, including numbers for spacing. You can create these in the "Local variables" panel:

Open the "Local variables" panel (Shift + L or via the right sidebar).
Create a new collection (e.g., "Primitives") or use an existing one.
Create a new variable, select "Number" as the type, and name it according to your token convention (e.g., spacing/400).
Assign the corresponding pixel value (e.g., 16).
Repeat for all tokens in your scale. Organize them into groups (e.g., spacing/primitive, spacing/semantic).

Applying Variables

Apply these number variables to relevant properties in Figma, especially within Auto Layout frames:

Padding: Select an Auto Layout frame. In the right sidebar under "Auto Layout", click the individual padding fields (top, right, bottom, left) and select the desired spacing variable from the library icon.
Gap: In the "Gap" field of an Auto Layout frame, click the input field and select the appropriate spacing variable.
Component Dimensions: You can also apply number variables to frame width/height or corner radius where appropriate.

Figma Variables also support modes, allowing you to define different spacing values for various contexts (e.g., compact vs. comfortable density, mobile vs. desktop).

Method 2: Using Plugins (e.g., Tokens Studio for Figma)

Plugins like Tokens Studio offer more advanced features for token management, including multi-value spacing support (mimicking CSS shorthand), better organization, theming, and direct export to code formats.

Defining Tokens in Tokens Studio

Install and open the Tokens Studio plugin.
Create a new token set (or use the global set).
Navigate to the 'Spacing' category.
Define tokens using CSS-like values (e.g., space.100 with value 4px or 0.25rem).
Tokens Studio directly supports multi-value strings like 8px 16px, which can be applied to padding.

Applying Tokens via the Plugin

Select a layer or Auto Layout frame in Figma:

In the Tokens Studio plugin panel, find the relevant property (e.g., spacing, paddingTop, gap).
Select the desired spacing token from your defined list to apply it. The plugin intelligently applies single or multiple values based on the token format and the Figma property.

This video demonstrates setting up spacing tokens using Figma variables and potentially plugins.

Visualizing the Spacing Token Workflow

This mindmap illustrates the key concepts and relationships involved in implementing spacing tokens across CSS and Figma.

mindmap root["Spacing Tokens Implementation"] id1["Core Concepts"] id1a["Definition
(Named Variables for Space)"] id1b["Purpose
(Consistency, Maintainability,
Scalability, Hierarchy)"] id1c["Spacing Scale
(Base Unit: 4px/8px,
Modular Progression)"] id1d["Token Types
(Primitive vs. Semantic)"] id2["CSS Implementation"] id2a["Defining Tokens
(CSS Custom Properties :root)"] id2b["Applying Tokens
(var() for margin, padding, gap)"] id2c["Responsiveness
(Media Queries)"] id2d["Logical Properties
(margin-inline-start, etc.)"] id2e["Tooling
(Preprocessors, CSS-in-JS)"] id3["Figma Implementation"] id3a["Figma Variables (Native)"] id3a1["Creating Number Variables"] id3a2["Applying to Auto Layout (Padding, Gap)"] id3a3["Using Modes (Contexts)"] id3b["Plugins (e.g., Tokens Studio)"] id3b1["Advanced Token Definition (Multi-value)"] id3b2["Applying via Plugin UI"] id3b3["Exporting Tokens"] id4["Bridging Figma & CSS"] id4a["Single Source of Truth"] id4b["Exporting/Syncing Tokens
(JSON, CSS Variables)"] id4c["Designer-Developer Collaboration"] id5["Best Practices"] id5a["Consistency"] id5b["Scalability"] id5c["Documentation"] id5d["Testing"]

Comparing Implementation Approaches

While both CSS and Figma enable spacing token implementation, their approaches and strengths differ. This chart provides a comparative overview based on common criteria:

This radar chart compares CSS Custom Properties, Figma's native Variables, and Figma Plugins like Tokens Studio across several implementation aspects. Higher scores indicate better performance or ease of use in that specific category. For instance, CSS excels in responsiveness handling and direct code output, while plugins offer strong multi-value support and collaboration features.

Bridging the Gap: Figma to CSS Workflow

The ultimate goal is consistency between design and code. Establishing a workflow to sync tokens is key:

Define Tokens Centrally: Use Figma (Variables or a plugin) as the primary place to define and manage your spacing tokens.
Export Tokens: Utilize plugin features (like Tokens Studio's 'Sync' or 'Export' options) or potential future native Figma export capabilities to generate a token file (commonly JSON).
Integrate into Build Process: Use tools like Style Dictionary or framework-specific integrations (e.g., for Panda CSS, Tailwind CSS) to transform the exported token JSON into CSS custom properties, Sass variables, or JavaScript objects consumable by your front-end codebase.
Maintain Synchronization: Regularly sync changes from Figma to code to ensure the design system remains consistent.

This process establishes your design tool as the single source of truth for spacing values, minimizing discrepancies and manual effort.

Example Spacing Scales from Design Systems

Different design systems adopt various scales and naming conventions. Here's a comparison of a few examples:

System	Example Token Name	Typical Value (px)	Typical Value (rem @ 16px root)	Base Unit Philosophy
USWDS	`--space-1` / `units-1`	8px	0.5rem	8px multiples
Shopify Polaris	`--p-space-100` / `space-100`	4px	0.25rem	4px multiples
Atlassian Design System	`space.100`	8px	0.5rem	~8px scale, with finer steps
Carbon Design System	`$spacing-03` / `--cds-spacing-03`	8px	0.5rem	8px multiples (steps based on Fibonacci sequence)
Tailwind CSS (Default)	`space-2` / `p-2`	8px	0.5rem	4px multiples (0.25rem)

This table shows that while the base unit (often 4px or 8px) and scale progression differ slightly, the core concept of using named tokens for predefined spacing values is consistent across major systems.

Frequently Asked Questions (FAQ)

What is the most common base unit for spacing tokens? ▼

While both 4px and 8px are common, an 8px base unit (or 0.5rem) is frequently adopted by many major design systems like USWDS, Carbon, and Atlassian. It provides a good balance between granularity and distinct steps, often leading to more harmonious vertical rhythm. However, a 4px base allows for finer control if needed.

How do multi-value spacing tokens work (e.g., for padding)? ▼

Multi-value tokens mimic CSS shorthand properties like `padding` or `margin`.

In CSS: You can define a variable holding multiple values (`--padding-squish: var(--space-200) var(--space-400);`) and apply it (`padding: var(--padding-squish);`). Alternatively, apply individual tokens: `padding: var(--space-200) var(--space-400);`.
In Figma (Tokens Studio): Define a token with a value like `"8px 16px"`. When applied to padding in the plugin, it maps to top/bottom (8px) and left/right (16px).
In Figma (Variables): Native variables currently only support single numbers. You need to apply separate variables to individual padding fields (top, right, bottom, left) or use a plugin for direct multi-value application.

Should I use Figma's native Variables or a plugin like Tokens Studio? ▼

It depends on your team's needs and complexity:

Figma Variables: Good for simpler systems, built-in, excellent integration with Figma features (like modes), and likely to improve over time. Limited in direct multi-value support for spacing and advanced token transformations.
Tokens Studio (or similar plugins): Offers more power and flexibility, including multi-value tokens, complex token types (math, composition), robust theming, and mature export/sync capabilities to various code formats. Has a steeper learning curve and relies on a third-party tool.

Many teams start with Variables for basic tokens and adopt plugins when they need more advanced features or tighter code integration.

Can spacing tokens be used for properties other than margin, padding, and gap? ▼

Yes, absolutely! While margin, padding, and gap are the primary use cases, spacing tokens can consistently define values for:

border-radius (using smaller spacing tokens for corner consistency)
outline-offset
text-indent
Minimum/maximum widths or heights (though dedicated size tokens might be better)
Positioning offsets (top, right, bottom, left)

Using them for these properties helps maintain the overall spatial rhythm of the design system.