Przejdź do treści
prfct.dev

Tokeny projektowe

Jak tokeny prfct są zbudowane, nazywane, generowane i eksportowane — jako zmienne CSS, klasy Tailwinda i JSON w formacie W3C Design Tokens.

Tokeny to umowa między designem a kodem. Tokeny prfct są zdefiniowane raz, jako dane, a wszystko inne — CSS, klasy Tailwinda, pliki dla narzędzi projektowych i ta dokumentacja — jest z nich generowane. Nic nie może się rozjechać, bo nic nie jest zapisane dwa razy.

Architektura

Tokeny mają trzy poziomy. Każdy poziom odwołuje się wyłącznie do poziomu pod nim.

PoziomPrzykładPrzeznaczenie
Prymitywne--brand-9, --gray-3, --radiusSurowe wartości. Wygenerowane skale, bazowy promień, czasy trwania.
Semantyczne--primary, --muted-foreground, --ring, --inputPrzeznaczenie. Wskazują na prymitywy — w każdym trybie inaczej.
KomponentoweKlasy wariantów w buttonVariants, popup-motionDecyzje, które pojedynczy komponent podejmuje na podstawie tokenów semantycznych.

Komponenty używają tokenów semantycznych wszędzie tam, gdzie istnieje odpowiednia rola, a stopni skali tam, gdzie komponent potrzebuje konkretnej roli (jak bg-brand-3 text-brand-11 w odznace). Nigdy nie używają surowych wartości.

Nazewnictwo

--{scale}-{step}        --brand-9, --gray-12, --red-3
--{scale}-contrast      --amber-contrast  (text on step 9)
--{role}                --background, --primary, --border, --ring
--{role}-foreground     --primary-foreground, --muted-foreground
--duration-{name}       --duration-fast, --duration-spring
--ease-{name}           --ease-enter, --ease-spring
--z-{layer}             --z-popover, --z-tooltip

W Tailwindzie każdy token jest klasą: bg-brand-3, text-muted-foreground, rounded-xl, shadow-floating, ease-spring, duration-fast, z-popover, text-heading-md.

Źródło prawdy

lib/color/oklch.ts        OKLCH ↔ sRGB, gamut mapping, WCAG and APCA contrast
lib/color/scale.ts        12-step scale generator with solved text steps
lib/tokens/palette.ts     hues and neutral presets
lib/tokens/semantic.ts    semantic roles → scale steps, per mode
lib/tokens/foundations.ts typography, radius, shadows, motion, layers
scripts/build-tokens.ts   → styles/tokens.css + public/tokens/*.json
pnpm tokens   # regenerate after changing any file in lib/tokens

Eksport

light.tokens.jsonWszystkie skale i role semantyczne dla trybu jasnego w formacie W3C Design Tokens (DTCG 2025.10).dark.tokens.jsonTa sama struktura dla trybu ciemnego — zaimportuj oba pliki jako tryby w Figma Variables albo Tokens Studio.prfct.tokens.jsonTypografia, zaokrąglenia, czasy trwania i krzywe przejścia.Motyw w rejestrzeKompletny motyw jako element rejestru shadcn, do zainstalowania jednym poleceniem.

Kolory są eksportowane w OKLCH z zapasową wartością hex w sRGB, więc narzędzia projektowe, które nie obsługują OKLCH, i tak dostają dokładne wartości:

public/tokens/light.tokens.json
{
  "color": {
    "brand": {
      "9": {
        "$type": "color",
        "$value": {
          "colorSpace": "oklch",
          "components": [0.515, 0.24, 267],
          "hex": "#2c4fee"
        }
      }
    }
  },
  "semantic": {
    "ring": { "$type": "color", "$value": "{color.brand.9}" }
  }
}

Dodawanie tokenu

  1. Dodaj go do odpowiedniego pliku w lib/tokens.
  2. Uruchom pnpm tokens.
  3. Jeśli wprowadza nową nazwę klasy (nową rolę typograficzną, cień albo czas trwania), zarejestruj ją w lib/utils.ts, żeby cn() poprawnie ją scalał — dopóki tego nie zrobisz, testy nie przejdą.
  4. Udokumentuj go: strony fundamentów renderują się bezpośrednio z lib/tokens, więc większość tabel zaktualizuje się sama.