Skip to content
Sulmu UI

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

Section titled “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

Section titled “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

Section titled “Changing or adding a token”

  1. Agree the value in Figma. The designer’s file decides what the value is.

  2. 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.

  3. Regenerate.

    Terminal window
    pnpm gen

    This runs pnpm tokens, pnpm icons and panda codegen. pnpm dev and pnpm build do it for you.

  4. Use it in a recipe by its path: bg: 'bg.surface', gap: '4', borderRadius: 'xl'.

  5. 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.

  6. Check both themes in Storybook (the theme switch in the toolbar) and on this site.

  7. 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

Section titled “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

Section titled “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.