---
title: "Design tokens"
description: "How Figma-exported DTCG tokens become CSS variables, Tailwind utilities, component variants and TypeScript types."
requested_language: cs
language: en
translation_notice: "This page isn't translated yet"
url: https://docs.systhema.app/cs/concepts/design-tokens
version: unreleased (main)
docs_index: https://docs.systhema.app/cs/llms.txt
---
> This page isn't translated yet. Showing English.


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 is

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

```json title="src/tokens/colorSystem.default.tokens.json"
{
  "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.

| Collection              | Holds                                                                | Modes              |
| ----------------------- | -------------------------------------------------------------------- | ------------------ |
| `colorPrimitives`       | The raw palette (`base.900`, `theme.500`)                            | one                |
| `colorSystem`           | Semantic colors (`foundations.bg`, `typography.heading`, `button.*`) | one per theme      |
| `font`                  | Font families, weights and styles                                    | one                |
| `responsiveSizing`      | Grid, gaps, container, section padding, type sizes, component sizes  | one per breakpoint |
| `config`, `calc`        | Breakpoints, design widths and build-time math                       | one                |
| `tailwindcss`           | Values mapped onto Tailwind's theme                                  | one                |
| `easings`, `transition` | Optional motion curves and per-component transitions                 | one                |

The text, effect and grid **styles** sit beside the collections and become classes such as `.text-h1`. The full list is on [Token collections](https://docs.systhema.app/cs/design/token-collections.md).

## How tokens flow

```text
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](https://docs.systhema.app/cs/design/figma/export.md).
2. **Configure.** `systhema.config.ts` points at the manifest and can override or extend tokens with `customTokens` (see [Custom tokens](https://docs.systhema.app/cs/design/custom-tokens.md)) and decide how sizes become CSS with `spacing` (see [Responsive sizing](https://docs.systhema.app/cs/concepts/responsive-sizing.md)).
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](https://docs.systhema.app/cs/concepts/generated-artifacts.md).
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](https://docs.systhema.app/cs/concepts/client-and-server.md).

## From token path to CSS variable

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.

| Token path                                   | CSS variable                         |
| -------------------------------------------- | ------------------------------------ |
| `colorPrimitives.primitives.base.900`        | `--color-base-900`                   |
| `colorSystem.default.typography.heading`     | `--color-typography-heading`         |
| `colorSystem.dark.typography.heading`        | `--color-typography-heading`         |
| `font.default.heading.fontFamily`            | `--font-default-heading-font-family` |
| `responsiveSizing.lg.typography.h1.fontSize` | `--typography-h1-font-size`          |
| `responsiveSizing.sm.section.paddingY`       | `--section-padding-y`                |

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](https://docs.systhema.app/cs/reference/tokens/colors.md) list every variable with the default tokens.

## Using tokens in your code

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](https://docs.systhema.app/cs/styling/cascade-layers.md).

```tsx
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 tokens

- **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, `$value`s 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` provides

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](https://docs.systhema.app/cs/reference/generated-types.md), runtime helpers such as `getTokens` and `getResolvedValue` ([API](https://docs.systhema.app/cs/reference/core.md)), the client-safe entry [`@systhemaui/core/client`](https://docs.systhema.app/cs/concepts/client-and-server.md), the color helpers behind [palettes](https://docs.systhema.app/cs/design/palettes.md), the [design engine](https://docs.systhema.app/cs/reference/core-design.md) behind Systhema Design, and a [vanilla JS bundle](https://docs.systhema.app/cs/styling/vanilla-js.md) for HTML projects.

## Related

- [Token collections](https://docs.systhema.app/cs/design/token-collections.md)
- [Color tokens](https://docs.systhema.app/cs/design/color-tokens.md)
- [Custom tokens](https://docs.systhema.app/cs/design/custom-tokens.md)
- [Themes and backgrounds](https://docs.systhema.app/cs/concepts/themes.md)
- [Generated artifacts](https://docs.systhema.app/cs/concepts/generated-artifacts.md)