Skip to content

Samsen Internal Framework

This is Samsen's internal framework content for Design Systems. It is read-only reference material.

Token Architecture — Figma Variables ↔ CSS Tokens Alignment

The Principle

For AI-assisted design to produce reliable output, the token system in Figma must be a 1:1 mirror of the token system in code. Every Figma variable should have a corresponding CSS custom property with a predictable naming relationship.

This alignment is what makes the bridge between design intent and code output trustworthy. Without it, AI guesses. With it, AI follows the system.

Token Layers

A well-structured token architecture has three layers:

1. Primitive Tokens (Global Values)

The raw values. These define the complete palette of options available to the system.

/* Primitives */
--color-blue-500: #2563eb;
--color-blue-600: #1d4ed8;
--spacing-4: 4px;
--spacing-8: 8px;
--spacing-16: 16px;
--font-size-14: 14px;
--font-size-16: 16px;

Figma equivalent: Variable collections at the primitive level. These are the raw values that the rest of the system references.

2. Semantic Tokens (Design Decisions)

These assign meaning to primitives. They express intent, not value.

/* Semantic */
--color-action-primary: var(--color-blue-500);
--color-action-primary-hover: var(--color-blue-600);
--spacing-component-padding: var(--spacing-16);
--spacing-component-gap: var(--spacing-8);
--font-size-body: var(--font-size-16);
--font-size-caption: var(--font-size-14);

Figma equivalent: Variable aliases. action/primary references blue/500. The semantic name stays stable even when the underlying value changes.

3. Component Tokens (Scoped Decisions)

Optional but powerful. These scope semantic tokens to specific components.

/* Component-scoped */
--button-padding-x: var(--spacing-component-padding);
--button-padding-y: var(--spacing-8);
--button-color-bg: var(--color-action-primary);
--button-color-bg-hover: var(--color-action-primary-hover);
--card-padding: var(--spacing-component-padding);
--card-gap: var(--spacing-component-gap);

Figma equivalent: Component-level variables that reference semantic tokens. When you change spacing-component-padding, all components using it update simultaneously.

Naming Convention Alignment

The naming convention must be consistent across Figma and code:

Figma Variable CSS Custom Property
color/action/primary --color-action-primary
spacing/component/padding --spacing-component-padding
font/size/body --font-size-body
elevation/card --elevation-card

The mapping should be mechanical: replace / with -, prepend --. No creative interpretation, no abbreviations that differ between systems.

Why This Matters for AI

When Claude Code generates a component and the token architecture is aligned:

  • It can reference var(--spacing-component-padding) with confidence that this token exists and means what it says.
  • It can read the Figma file via MCP and map Figma variables directly to CSS properties.
  • Changes to the design system propagate correctly: update the semantic token, everything downstream follows.
  • Visual QA is straightforward: the same tokens produce the same values in both environments.

When the architecture is misaligned:

  • AI has to guess which CSS value maps to which Figma variable.
  • Generated code uses hardcoded values or incorrect token names.
  • Design system updates don't propagate — you end up with drift.
  • Every component requires manual correction, defeating the purpose.

Multi-Theme and Multi-Brand Support

A properly layered token architecture supports theming natively:

/* Light theme */
[data-theme="light"] {
  --color-surface-primary: var(--color-white);
  --color-text-primary: var(--color-gray-900);
}

/* Dark theme */
[data-theme="dark"] {
  --color-surface-primary: var(--color-gray-900);
  --color-text-primary: var(--color-white);
}

In Figma, this maps to variable modes. Same variable name, different values per mode. The semantic layer abstracts the theme — components reference --color-surface-primary and never need to know which theme is active.

This is critical for organizations that maintain multiple brands or products on a shared design system. The primitive and component layers can vary per brand while the semantic layer remains consistent.

Common Anti-Patterns

  • No semantic layer — Jumping from primitives directly to components. Makes theming impossible and changes brittle.
  • Inconsistent naming — --blue-500 in code but brand/primary in Figma. AI can't bridge the gap.
  • Hardcoded values in components — margin: 16px instead of margin: var(--spacing-md). Breaks system-wide updates.
  • Token proliferation — Creating a new token for every unique value. Tokens should be a constrained set of options, not an infinite palette.
  • Figma-only tokens — Variables exist in Figma but have no code equivalent. The bridge only works if both sides are built.

Implementation Checklist

  • [ ] All Figma variables have a corresponding CSS custom property
  • [ ] Naming convention is documented and consistent between Figma and code
  • [ ] Three-layer architecture: primitives → semantic → component (component layer optional)
  • [ ] Semantic tokens express intent, not value
  • [ ] Theme/mode switching works via semantic token reassignment
  • [ ] Token values are the single source of truth (no hardcoded values in components)
  • [ ] AI context documents reference the token naming convention