The tokens workflow

tokens/*.json is the single source of truth for every colour, size and type value. The Panda preset is generated from those files, and the Figma variables in the Sulmu UI library are created from the same files.

The files

File	Holds
`tokens/color.primitives.json`	The raw colour ramps: brand, grey, secondary, system, whiteAlpha, page.
`tokens/color.semantic.json`	Purpose colours that point at primitives: `bg`, `fg`, `border`, `brand`, `status`, `tone`.
`tokens/typography.json`	Font families, weights, sizes, line heights and the text styles.
`tokens/size.json`	Spacing, radius, border widths, breakpoints and the sizes of each component.
`tokens/effect.json`	Shadows, z-index, durations and easings.

The files use the W3C design-token format:

{
  "color": {
    "bg": {
      "surface": {
        "$value": "{color.grey.0}",
        "$description": "cards, dialogs, table, active tab"
      }
    },
    "grey": {
      "0": { "$value": "#FFFFFF", "$extensions": { "dark": "#23202C" } }
    }
  }
}

$value is the value, or a reference to another token in braces.
$extensions.dark is the dark-mode value. A ramp that has one is emitted as a semantic token in Panda, so it changes with data-theme="dark".
$description is shown on the Foundations pages of this site.

From a token to the screen

tokens/*.json
   │  pnpm tokens  (scripts/build-tokens.mjs)
   ▼
src/preset/tokens.gen.ts        generated, not committed
   │  imported by src/preset/index.ts  (sulmuPreset)
   ▼
panda codegen  →  styled-system/      typed recipes for the components
panda cssgen   →  dist/styles.css     --su-colors-bg-surface: var(--su-colors-grey-0)

The same JSON files are published in the package as @beyul/sulmu-ui/tokens/*.

Changing or adding a token

Agree the value in Figma. The designer’s file decides what the value is.
Edit the JSON file. Add the token in the group it belongs to, with a $description that says where it is used. Prefer a semantic token that points at an existing primitive over a new raw value.
Regenerate.
Terminal window
```
pnpm gen
```
This runs pnpm tokens, pnpm icons and panda codegen. pnpm dev and pnpm build do it for you.
Use it in a recipe by its path: bg: 'bg.surface', gap: '4', borderRadius: 'xl'.
Update the Figma variable in the Sulmu UI library file so that it has the same name and value. The variable name is the token path with slashes (color/bg/surface), and its web code syntax is the CSS variable (var(--su-colors-bg-surface)). Record any new collection or count in figma/library.json.
Check both themes in Storybook (the theme switch in the toolbar) and on this site.
Add a changeset. Changing a value is a patch if it is a correction and a minor if it changes how things look. Removing or renaming a token is a breaking change.

Names

One path gives every name:

Where	Name
Token file	`color.bg.surface`
Panda (recipes, the preset)	`colors.bg.surface`, written as `bg.surface` for a colour property
CSS	`--su-colors-bg-surface`
Figma variable	`color/bg/surface`

Component sizes are tokens too

Heights, paddings and widths of components are in tokens/size.json (control.height.md, avatar.lg, dialog.md), not in the recipes. A recipe refers to them as sizes tokens, for example height: 'control.md'. Changing a component’s size is therefore a token change.