Teza
Tokeny czynią deterministyczną warstwę UI (kolor, odstęp, typografia, promień) maszynowo egzekwowalną — agent wybiera z zamkniętego zbioru, a audyt w CI odrzuca odstępstwa. Warstwa osądu (architektura informacji, przepływy, dobór komponentu, intencja dostępności) pozostaje przy człowieku. Granica nie biegnie więc dokładnie między „UI" a „UX", lecz między tym, co deterministyczne, a tym, co wymaga osądu.
## Dlaczego tokeny
Token to nazwana wartość — `color.link = #A8482A` — której używają jednocześnie strona, komponenty i materiały marketingowe. Zmiana w jednym miejscu propaguje się wszędzie. To samo, co Infrastructure-as-Code zrobił z serwerami — zamienił ręcznie strojone, nigdy nie identyczne maszyny w odtwarzalną, audytowalną konfigurację — tokeny robią z decyzjami wizualnymi: przestają być „bo ktoś tak kiedyś kliknął w Figmie", a stają się reprodukowalnym faktem w repo.
Wartość tokenów rośnie wprost proporcjonalnie do liczby miejsc, w których ta sama decyzja musi być spójna: light/dark, wiele marek, web/iOS/Android, aplikacja i landing. Bez tokenów każde z tych miejsc dryfuje niezależnie. Z tokenami dryf jest wykrywalny i odwracalny.
## Anatomia: trzy warstwy tokenów
Dojrzały zbiór tokenów to nie płaska lista, lecz trzy warstwy pośrednictwa — i to właśnie pośrednictwo daje siłę.
1. **Prymitywy (primitive / global)** — surowa paleta faktów: `--ds-rust-600: #A8482A`, `--ds-space-2: 8px`. Bez znaczenia, sama wartość.
2. **Tokeny semantyczne (alias)** — nadają prymitywom rolę: `--color-link: var(--ds-rust-600)`, `--space-inset-sm: var(--ds-space-2)`. To tu mieszka intencja („to jest kolor linku"), nie konkretny hex.
3. **Tokeny komponentu** — opcjonalna warstwa najbliżej UI: `--button-bg: var(--color-link)`. Komponent nigdy nie sięga do prymitywu ani do surowej wartości.
```json
// W3C DTCG: prymitywy i alias ($value/$type, alias przez {ścieżka})
{
"ds": {
"rust": { "600": { "$value": "#A8482A", "$type": "color" } },
"space": { "2": { "$value": "8px", "$type": "dimension" } }
},
"color": {
"link": { "$value": "{ds.rust.600}", "$type": "color" }
},
"space": {
"inset-sm": { "$value": "{ds.space.2}", "$type": "dimension" }
}
}
```
```css
/* Ta sama hierarchia w CSS — trzy warstwy pośrednictwa */
:root {
--ds-rust-600: #A8482A; /* prymityw */
--color-link: var(--ds-rust-600); /* semantyka */
}
.button { color: var(--color-link); } /* komponent */
```
Pośrednictwo jest tym, co ratuje skórę: gdy marka zmienia odcień, podmieniasz **jeden** prymityw; gdy dochodzi dark mode czy druga marka, przepinasz **warstwę alias** — komponenty nie wiedzą o niczym. Płaska lista hexów takiej operacji nie przeżywa.
## Standard, nie dialekt: W3C DTCG
Do niedawna każde narzędzie miało własny format tokenów. To się zmieniło: [Design Tokens Format Module](https://www.designtokens.org/tr/) grupy [W3C Design Tokens Community Group](https://www.w3.org/community/design-tokens/) osiągnął [pierwszą stabilną wersję (2025.10)](https://www.w3.org/community/design-tokens/2025/10/28/design-tokens-specification-reaches-first-stable-version/) — wendor-neutralny JSON z polami `$value`/`$type`, aliasami, theming/multi-brand i nowoczesnymi przestrzeniami koloru (Display P3, Oklch, CSS Color 4). Trzymanie się standardu, zamiast formatu jednego dostawcy, to dokładnie ta sama zasada, którą stosujemy wobec [licencji i suwerenności](/blog/open-source-a-suwerennosc): unikasz zamknięcia.
Ekosystem narzędziowy zna już ten format. W praktyce sięga się po [Style Dictionary](/katalog/style-dictionary) (transpilacja jednego źródła do CSS/iOS/Android/Flutter), [Tokens Studio](/katalog/tokens-studio) (pomost Figma ↔ repo), a do dokumentacji i izolowanego rozwoju komponentów [Storybook](/katalog/storybook); całość projektowa może żyć w otwartym [Penpot](/katalog/penpot). Wspólny mianownik: **tokeny są źródłem, a kod i materiały są generowane** — nie odwrotnie.
## Tokeny jako guardrails dla agenta
Tu wchodzi platforma agentowa. Gdy interfejs pisze (lub współpisze) model, pojawia się problem, którego nie ma przy człowieku z dobrą pamięcią zespołową. Asystent kodujący nie *odpytuje* design systemu — on **generuje prawdopodobnie wyglądające wartości**. W jednej sesji potrafi podjąć 200–300 mikrodecyzji wizualnych (padding, odcień, promień), każda z osobna sensowna, a w sumie niespójna; a następna sesja nie pamięta poprzedniej i zgaduje od nowa ([opis problemu i metoda — Hardik Pandya](https://hvpandya.com/llm-design-systems)).
Trzy słabości modeli i ich tokenowe przeciwlekarstwa:
- **Fabrykuje wartości** → daj **zamkniętą warstwę tokenów**: agent wybiera z `var(--color-link)`, a nie wymyśla `#1D4ED8`. Nie ma „złego niebieskiego", bo jest tylko jeden.
- **Nie ma pamięci między sesjami** → daj **pliki spec w repo** (foundations + komponenty), które model czyta na starcie każdej sesji. Decyzję podjął człowiek raz; model ją *odczytuje*.
- **Nie czyta intencji ze źródła** → **audyt w CI**: skrypt skanuje CSS, a każda surowa wartość to błąd ze wskazaniem właściwego tokenu i `exit 1`. Czego nie da się scalić, tego nie ma.
```bash
# Bramka tokenowa w CI: zero surowych wartości w UI
$ npm run token-audit
src/components/Nav.css
✗ L42: zakodowany #1868DB → użyj var(--color-link)
✗ L78: surowy 12px w padding → użyj var(--space-inset-sm)
Errors: 2 # exit 1 → PR nie przechodzi
```
To jest dokładnie ten sam ruch, co [deterministyczny szkielet ADP](/blog/deterministyczny-szkielet-adp): nie ufamy modelowi „że będzie ładnie", tylko zamykamy go w polityce, która jest [policy-as-code](/blog/policy-as-code-dla-zespolow) i bramką w pipeline. Smak człowieka wchodzi raz — do tokenów i specyfikacji — a model stosuje go mechanicznie. Tokeny są więc dla UI tym, czym OPA dla wdrożeń: zamkniętym zbiorem dozwolonych decyzji.