Workflow

This page describes how design and engineering collaborate on the Releaf design system, and how design tokens flow between code and Figma to keep everything aligned.

Note

Our goal is a single source of truth for design tokens, with a predictable, repeatable workflow that avoids drift between design and implementation.

Single source of truth

Design tokens live in code, not in Figma.

• Tokens are defined as Design Tokens Community Group (DTCG) JSON in the design-system repository.
• These tokens are the canonical source of truth.
• Figma is a consumer of tokens, not the origin.

This allows us to:

• Version tokens.
• Review changes via pull requests.
• Generate multiple outputs (CSS variables, TypeScript metadata, Figma variables etc).
• Support themes (including light/dark modes).
• Reason about downstream impact safely.

Note

Designers should not manually create or permanently edit design tokens in Figma. All agreed token changes start in code.

Token structure

Tokens are authored as primitive and semantic tokens.

Primitive tokens

• Raw, context-free values.
• Examples:
  • Colour scales (e.g. color/mono/100, color/red/500)
  • Spacing steps
  • Font sizes, line heights, and letter spacings
  • Radii
  • Opacities

Semantic tokens

• Map contextual meaning to primitive values.
• Examples:
  • color/text/primary -> color/mono/900
  • color/surface/primary -> color/teal/500

Semantic tokens allow us to:

• Adapt themes without changing components.
• Keep component APIs stable.
• Support multiple modes (light/dark).
• Evolve visual design with lower risk.

Repository ownership

Design system repository

• DTCG JSON token definitions.
• Token validation and transformation.
• Generated outputs.
• Design system documentation.

Figma

• Variables imported from generated JSON.
• Figma components built using those variables.
• Used for exploration, validation, and communication.

Token build pipeline

The token build pipeline runs in the design-system repository.

1. Tokens are authored or updated Designers and engineers collaborate on token changes via pull requests.

2. Tokens are validated

• Schema and structure checks
• Naming conventions
• Required scales and references

3. Tokens are transformed DTCG JSON is converted into platform-specific formats, including:

• CSS variables
• TypeScript metadata
• Figma variables JSON

4. Figma variables JSON is generated The output matches the expected format for the Microsoft figma-variables-import plugin, including:

   • Variable collections
   • Modes (light/dark, alternative theme light/dark)
   • Names, paths, and resolved values

5. Artefacts are committed All generated outputs are versioned and reviewable.

Importing tokens into Figma

1. Locate the generated Figma variables JSON files as a build artefact of the design-system repository.
2. Open Figma and the Microsoft Figma Variables Import plugin.
3. Drag and drop all JSON files into the plugin.
4. Verify:

• Variables updated correctly
• Modes applied as expected
• No manual overrides remain

Tip

If variables fail to import cleanly, stop and fix the token source rather than patching Figma manually.

Designer experimentation in Figma

Designers are encouraged to explore and experiment in Figma.

What’s encouraged

• Trying alternative values in variables locally.
• Exploring visual direction, contrast, and spacing.
• Prototyping component variants and states.
• Using branches or duplicate files for exploration.

What’s not considered final

• Making shared token changes only in Figma.
• Treating Figma variables as the long-term source of truth.
• Updating shared libraries without a corresponding token change in code.

Note

Figma is the place to experiment. A change becomes real only once the token source in code is updated and re-imported info Figma.

Token change implications

Design token changes are not isolated design tweaks. They have downstream implications across the system:

• Design system components may change appearance or behaviour.
• Product UI across all apps may shift (sometimes subtly).
• Accessibility (contrast, focus, readability) may be affected.
• Visual regression and component tests may need to be re-run.
• Release notes and changelogs may be required.

Because of this, token changes follow a deliberate process.

Working on components

Figma

• Components must use imported variables only.
• No hard-coded colours, spacing, or typography.
• Variants should map cleanly to:
  • Component states
  • Semantic token usage
  • Accessibility requirements

Code

• Components consume semantic tokens, not primitives.
• Literal values in component styles are avoided.
• APIs are constrained and accessible by default.
• Behaviour and variants should align with Figma.

Design and code reconciliation

Parity between Figma components and code components is intentional work.

We expect:

• One conceptual component -> one Figma component.
• Matching variant axes (e.g. size, intent, state).
• Documented differences where parity is not possible.

When mismatches occur:

• Prefer adjusting token mappings.
• Avoid component-specific one-off values.
• Document exceptions clearly.

Change management

Making changes

• All token changes go through PR review.
• Significant changes require context and rationale.
• Breaking changes should be rare and deliberate.

Communicating changes

• Notable updates are recorded in the design system changelog.
• Impacted teams are notified early.
• Rollout and retesting are planned when needed.