@tenancy.nz/tokens

Design tokens for TPS UI. Figma Token Studio is the source of truth — designers push/pull the single raw export in raw/tokens.json. A prebuild step fans that out into the Token Studio "pro" multi-file layout under src/, then Style Dictionary compiles one theme at a time into the artifacts the component packages consume.

Folder structure

packages/tokens/
├── raw/tokens.json           ← Token Studio sync target (single-file export)
├── scripts/split-tokens.mjs  ← prebuild: raw/tokens.json → src/ (pro layout)
├── src/                      ← generated, gitignored — one folder per theme
│   ├── $metadata.json        ← Token Studio: token-set order
│   ├── $themes.json          ← Token Studio: theme definitions
│   ├── light/{primitive,semantic,component}.json
│   └── dark/{primitive,semantic,component}.json
├── style-dictionary.config.js  ← themeConfig() factory (one instance per theme)
├── build.mjs                 ← `pnpm build` entry point
└── dist/                     ← generated, gitignored, rebuilt in CI
    ├── css/tokens.css        ← :root (light) + [data-theme="dark"] (+ light.css/dark.css)
    ├── esm/index.js          ← ESM: { light, dark } value trees
    ├── cjs/index.cjs         ← CommonJS
    └── types/index.d.ts      ← TypeScript declarations

raw/tokens.json is the only hand-off point. Everything under src/ and dist/ is machine-owned — the prebuild wipes and regenerates src/ on every build, so edit tokens in Figma Token Studio and push, not by hand.

Each theme is compiled by its own Style Dictionary instance so the identical primitive/semantic/component groups across themes don't collide. Token references ({primitive.colors.blue.Blue500}) are theme-agnostic and resolve within whichever theme is being built.

Connecting Figma Token Studio

In the Token Studio plugin → Settings → Sync add a Git provider (GitLab, to match this repo) with:

• Branch: a dedicated branch, e.g. design-tokens, so designer pushes arrive as merge requests rather than landing on main.
• File path: packages/tokens/raw/tokens.json
• Token format: DTCG ($value / $type).

Push from the plugin to write the JSON here; a merge to a release branch triggers the build below.

Build

pnpm --filter @tenancy.nz/tokens build

prebuild runs scripts/split-tokens.mjs first (also available standalone as pnpm --filter @tenancy.nz/tokens split).

Consuming

Tokens are exported as clean, resolved value trees — one per theme — keyed by their Token Studio paths, ready to map into a Material UI theme:

import tokens, {light, dark} from '@tenancy.nz/tokens';

tokens.light.primitive.colors.turquoise.Turquoise500;   // "#0cc1a3"
light.semantic.text['--color--text-accent'];            // "#0cc1a3"

// MUI: feed both schemes (or map the tokens into your palette shape)
import {createTheme} from '@mui/material/styles';
const theme = createTheme({
  colorSchemes: {
    light: {palette: {primary: {main: light.semantic.text['--color--text-accent']}}},
    dark: {palette: {primary: {main: dark.semantic.text['--color--text-accent']}}},
  },
});

Or use the CSS custom properties (light under :root, dark under [data-theme="dark"]):

import '@tenancy.nz/tokens/css';