@sdaia-ds/tokens

v2.0.1

Published

a month ago

SDAIA Design System tokens — generated from Figma Variables via Tokens Studio.

0High
0Medium
0Low

sdaia-dga

design-tokens sdaia figma

@sdaia/tokens

The SDAIA Design System tokens, generated from Figma Variables and consumed by every SDAIA-skinned product.

What this repo holds

sdaia-tokens/
├── tokens/
│   ├── tokens.json              ← Synced from Figma by Tokens Studio plugin
│   └── figma-codesyntax.json    ← Map of Figma var name → CSS var name
├── style-dictionary/
│   └── build.js                 ← Transforms tokens.json → CSS / JS / TS
├── dist/                        ← Built artifacts (committed by CI)
│   ├── tokens.css
│   ├── tokens.js
│   └── tokens.ts
├── scripts/
│   ├── validate.js              ← Sanity checks tokens before build
│   └── pull-codesyntax.md       ← How to refresh the codeSyntax map
└── .github/workflows/
    └── tokens.yml               ← CI: validate, build, publish

How the loop works

   ┌─────────────────────┐                    ┌──────────────────┐
   │  Designer in Figma  │                    │  Engineer in IDE │
   │  edits Variables    │                    │  uses tokens     │
   └──────────┬──────────┘                    └────────▲─────────┘
              │                                        │
              │  Native Figma Variables panel          │  npm install
              ▼                                        │  @sdaia/tokens
       ┌────────────────┐                       ┌──────┴───────────┐
       │ Figma Variables│ ◄── Tokens Studio ──► │ this repo (dist/)│
       │   (source of   │     plugin syncs      │   tokens.css     │
       │    truth)      │     in both           │   tokens.ts      │
       └────────────────┘     directions        └──────────────────┘
              ▲                                        ▲
              │                                        │
       Designers keep                              CI rebuilds
       editing in Figma's                          on every push
       native panel — Tokens                       to main
       Studio is just a courier

The sync rules

Source of truth is Figma Variables. Always.
Designers edit in Figma's native Variables panel. Not in Tokens Studio's UI.
Tokens Studio is the courier only. Its only job is to sync the JSON between Figma and this repo.
Engineers never edit tokens.json directly. It's a build input, not a source file.
CI rebuilds dist/ on every push. Engineers consume dist/tokens.css from npm.

Designer workflow

When you change a token in Figma:

Edit the variable in Figma's Variables panel (Local variables → edit value, mode, or alias).
Open the Tokens Studio for Figma plugin.
Click "Pull from Figma Variables" — imports your change into the plugin.
Click "Push to GitHub" — opens a PR (or commits directly to main, per your repo settings).
CI runs npm run validate then npm run tokens:build, commits rebuilt dist/ artifacts, and engineers can pull the update.

If a variable is renamed in Figma, you also need to refresh the codeSyntax map. See scripts/pull-codesyntax.md.

Engineer workflow

Adopting this package in a new product? Read ADOPTING.md first. It explains the four things you need to handle correctly (aliases, modes, dimension units, codeSyntax sidecar) and why you should never write a local transform over tokens.json.

npm install @sdaia/tokens

In your app's CSS entry:

@import '@sdaia/tokens/css';

Or in TypeScript:

import { tokens } from '@sdaia/tokens/ts'
const cardBg = tokens['color-bg-default']  // "var(--ds-color-bg-default)"

Modes are applied as classes on <html>:

| Class | Effect | |-------------------|---------------------| | .theme-dark | Dark theme | | .brand-private | Private brand (Indigo) | | .radius-square | Sharp corners | | .radius-rounded | Maximum rounded | | .density-reduced| Reduced motion | | .viewport-tablet| Tablet sizing | | .viewport-mobile| Mobile sizing |

Tailwind v4 utilities

tokens.css also ships a Tailwind v4 bridge — an @theme inline { … } block plus a handful of @utility text-text-* { … } rules — so the import above is all you need to use named utility classes like size-icon-lg, p-spacing-xl, rounded-radius-m, or text-text-md:

@import 'tailwindcss';
@import '@sdaia-ds/tokens/css';   /* ← bridge included automatically */

Every alias is a var(--ds-*) reference — no values are duplicated. Colour utilities don't need a bridge; use Tailwind's arbitrary-value syntax (bg-[var(--ds-color-bg-default)]).

Initial setup (one-time)

1. Tokens Studio plugin setup

Install "Tokens Studio for Figma" from the Figma community
In the plugin's Settings:
- Sync provider: GitHub
- Repo: your-org/sdaia-tokens
- Branch: main
- File path: tokens/tokens.json
- Access token: GitHub PAT with repo scope
Settings → "Tokens are stored in: Variables" ← CRITICAL. Without this, Tokens Studio creates a parallel set of Figma Styles and you'll have drift.

2. Initial pull

In Tokens Studio: "Pull from Figma Variables" → "Push to GitHub". This creates the initial tokens/tokens.json.

3. Refresh codeSyntax map

See scripts/pull-codesyntax.md. Paste a small JS snippet into the Desktop Bridge plugin once, copy the output to tokens/figma-codesyntax.json, commit.

4. Enable GitHub Actions

The .github/workflows/tokens.yml workflow runs automatically. To publish to npm, tag a release (git tag v0.1.0 && git push --tags).

Versioning

This is a shared design contract. Apply semver strictly:

Patch (0.0.x) — value changes only (a color got tweaked, padding shifted by 2px)
Minor (0.x.0) — additive (new tokens, new modes)
Major (x.0.0) — breaking (token renamed, removed, or alias direction reversed)

Engineers pin a major version in their package.json. Big rewrites get a major bump and a migration note in CHANGELOG.

Pitfalls

Don't enable Tokens Studio's "Styles" output. Pick Variables only.
DTCG export drops codeSyntax. That's why we keep the sidecar map. Don't delete it.
Aliases can break across modes. Validate (npm run validate) catches missing alias targets.
Mode names are case-sensitive and must match what's in Figma's collection mode config exactly: Light, Dark, SDAIA-Core, Blue, Standard, Square, Rounded, etc.

CLI cheat sheet

| Command | What it does | |--------------------------------|-----------------------------------------------| | npm run validate | Sanity check tokens.json and codeSyntax | | npm run tokens:build | Generate dist/tokens.css, dist/tokens.js, and dist/tokens.ts | | npm run tokens:refresh-codesyntax | Print instructions for the manual codeSyntax pull | | npm version patch && npm publish | Tag a release |

Questions

Ping #design-system in Slack, or open an issue.