Design tokens

Every visual decision in a Systhema project, from a brand color to the gap between two cards, is a design token. Designers keep the tokens in Figma; Systhema turns them into the CSS variables, Tailwind utilities, component variants and TypeScript types your code uses. This page explains that pipeline and how to use the result.

What a token isLink to this section

A token is a named value with a type, written in the W3C Design Tokens (DTCG) JSON format:

{
  "typography": {
    "heading": { "$type": "color", "$value": "{foundations.text}" }
  }
}

A value is either literal ("#171717", 16) or a reference to another token in braces. Tokens are grouped into collections, and a collection can have several modes: colorSystem has one mode per theme (default and dark with the default tokens), and responsiveSizing one per breakpoint (sm, md, lg). A manifest.json lists every collection, its modes and their files.

The text, effect and grid styles sit beside the collections and become classes such as .text-h1. The full list is on Token collections.

How tokens flowLink to this section

Figma variables and styles
        │  Systhema Figma plugin: export as DTCG JSON
        ▼
src/tokens/*.tokens.json + manifest.json        ← committed, never edited by hand
        │  systhema.config.ts: manifest, customTokens, spacing
        ▼
systhema-core sync
        ├─ .systhema/artifacts/      token copies, tokenMap, TypeScript types, safelist
        └─ .systhema/references/     TOON summaries for coding agents
        │
        ▼
@import '@systhemaui/core/tailwind'  (at build time)
        ├─ CSS variables      :root, [data-theme="dark"], @media (width >= 640px) …
        ├─ utilities          .text-h1, .bg-layout-main, .gap-md, .container …
        └─ component CSS      .button-primary, .card-highlighted, .section …
        │
        ▼
Components                 variant, theme and gap props typed from the tokens

1. Export. The designer exports the Figma file with the Systhema plugin. You commit the JSON and the manifest; see Exporting from Figma.
2. Configure. systhema.config.ts points at the manifest and can override or extend tokens with customTokens (see Custom tokens) and decide how sizes become CSS with spacing (see Responsive sizing).
3. Sync. systhema-core sync (your pnpm sync script) copies the tokens into .systhema/artifacts/, generates types and a safelist, and writes agent references. See Generated artifacts.
4. Build. The Tailwind plugin reads the tokens and emits the CSS variables, utilities and component CSS. Nothing token-related runs in the browser; see Client and server code.

From token path to CSS variableLink to this section

Each token becomes one CSS variable. The mode is dropped from the name and applied by context instead: a theme by data-theme, a breakpoint by a media query.

The rule: drop the mode (and the palette's primitives group), kebab-case every segment, and prefix colors with --color- and fonts with --font-. Sizing tokens take no prefix. A reference stays a reference, so --color-typography-heading is var(--color-foundations-text) and follows the theme.

The generated pages under Token reference list every variable with the default tokens.

Using tokens in your codeLink to this section

Pick the highest-level option that does the job:

1. A component prop: <Button.a variant="secondary">, <Section theme="dark" layoutBackground="alternative">, <Stack gap="md">. Variant names come from the tokens and are typed.
2. A Systhema utility class: text-h1 sets the whole type style (family, size, weight, line height, letter spacing), bg-layout-alternative, gap-md, container.
3. A Tailwind utility with a token variable: text-(--color-foundations-text-muted), border-(--color-separator-line). One property, still themed.
4. Your own CSS in @layer app, reading var(--…). See Cascade layers.

import { Paragraph, Section } from '@systhemaui/next'

export function Note() {
  return (
    <Section layoutBackground="alternative">
      <Paragraph className="text-(--color-foundations-text-muted)">Prices include VAT.</Paragraph>
    </Section>
  )
}

Avoid raw Tailwind values such as text-black, bg-white or text-2xl: they do not change with the theme or the type scale. Use a hard-coded value only for something that must never theme, such as a brand asset.

Changing tokensLink to this section

• A design change (a color, the type ramp, a new token): change it in Figma and re-export. Never edit the exported JSON by hand; keys, $values and $extensions round-trip back to Figma, and systhema upgrade applies token migrations to them.
• A project-side override (layout rhythm, the layout above lg, a missing slot): customTokens in systhema.config.ts. Color and type overrides there hide a disagreement with the design, so prefer a re-export.

After either change, run pnpm sync and restart the dev server so the Tailwind plugin reads the new values.

What @systhemaui/core providesLink to this section

The token pipeline lives in @systhemaui/core, which every other package depends on. Besides the Tailwind plugin and systhema-core sync, it exports the generated types, runtime helpers such as getTokens and getResolvedValue (API), the client-safe entry @systhemaui/core/client, the color helpers behind palettes, the design engine behind Systhema Design, and a vanilla JS bundle for HTML projects.

RelatedLink to this section

• Token collections
• Color tokens
• Custom tokens
• Themes and backgrounds
• Generated artifacts