> ## Documentation Index
> Fetch the complete documentation index at: https://clementineds.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Figma Integration: Clementine DS Variable Collections

> Clementine DS mirrors its 3-tier token cascade as three Figma variable collections — Primitives, Semantic Light+Dark, and Components — all auto-synced.

Clementine DS lives in both code and Figma. The same 3-tier cascade that governs your React components is reflected as three Figma variable collections, so design decisions and engineering decisions always point at the same source of truth.

## The three collections

The [Tina-DS Figma file](https://www.figma.com/design/MBr4guR2Xtfa92JJXS6472/Tina-DS-file-ANT) contains three variable collections that map directly to the token tiers in `packages/tokens/src/`.

| Collection | Variables | What it holds |
| - | - | - |
| **Primitives** | 52 | Raw scales: `color.blue.6`, `radius.md`, `spacing.sm` |
| **Semantic** | 32 | Intent tokens with Light and Dark modes: `action.primary`, `surface.elevated`, `feedback.error` |
| **Components** | 102 | Per-component bindings: `button.bg.default`, `button.border.focus`, `badge.bg.success` |

## How the collections cross-reference

The collections are not independent — they are wired together using Figma's `VARIABLE_ALIAS` mechanism, which mirrors the `{reference}` syntax in your DTCG token files:

* **Semantic variables point to Primitive variables.** `action.primary` in the Semantic collection resolves to `color.blue.6` in the Primitives collection — the same reference written in `semantic-light.json`.
* **Component variables point to Semantic variables.** `button.bg.default` in the Components collection resolves to `action.primary` in the Semantic collection — the same reference written in `button.json`.

No collection ever skips a tier. The cascade rule is one-way in Figma exactly as it is in code.

## Switching modes

The Semantic collection has two modes: **Light** and **Dark**. Switch the collection's mode in a Figma frame and every paint on every component inside that frame reflows — because every component variable traces back through a semantic variable, and the semantic variable resolves differently in each mode.

You do not need to retheme individual components. Change the mode once at the frame level, and the entire screen updates.

## How component frames are bound

Every frame on the components board is bound to Component-tier variables. There are no hardcoded hex values anywhere in the file:

* Hover state on a Button → `button/bg/hover`
* Focus ring on a Button → `button/border/focus`
* Background on a filled Badge → `badge/bg/success` (for the success intent)

When you inspect a layer in Figma, you see the variable name, not a colour value. That name is the same token that appears in `specs/<component>/tokens.json`.

## The spec board

Alongside the components board, the Figma file contains a spec board. The actual YAML frontmatter from `specs/button/index.md` sits next to a live Button component, with the `agentic-spec validate` output showing all five gates green. This is how the contract works: open the spec board, glance left at the YAML, glance right at the rendered component, and you know immediately whether they match.

## Why this matters for drift detection

Figma and code use the same closed contract. Each Component-tier variable in Figma matches an entry in `specs/<component>/tokens.json`. Each Semantic variable matches an entry in `semantic-light.json` or `semantic-dark.json`. Each Primitive variable matches an entry in `primitives.json`.

Because the mapping is explicit and mechanical, drift between Figma and code is something you can lint — not something you discover in a design review six weeks later.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.