# Designtokenit: yksi lähde väreille ja typografialle

[Canonical HTML page](https://gradiently.design/fi/guide/design-tokens)

Neljässäkymmenessä tiedostossa oleva brändiväri alkaa eriytyä. Token on yhdessä paikassa, josta jokainen alusta lukee sen. Näin jäsennät ja nimeät kestävät designtokenit sekä viet ne koodiin ja suunnittelutyökaluihin.

## The short version

- Designtokenit ovat nimettyjä, alustariippumattomia arvoja suunnittelupäätöksille, kuten väreille, fonttiperheille, ko’oille, väleille, säteille, varjoille ja liikkeen ajoituksille.
- Useimmissa tokenjärjestelmissä on kolme tasoa: perustokenit sisältävät raaka-arvot, semanttiset kuvaavat tarkoituksen ja komponenttitokenit soveltavat tarkoituksia tiettyihin osiin.
- W3C Design Tokens Community Group -muoto tallentaa tokenit JSONina $value- ja $type-ominaisuuksilla ja viittaa muihin tokeneihin aaltosulkeilla.
- Style Dictionaryn kaltaiset työkalut muuntavat yhden tokenitiedoston CSS:n mukautetuiksi ominaisuuksiksi, JavaScriptiksi sekä iOS- ja Android-resursseiksi.
- Tumma tila ja useat brändit onnistuvat vaihtamalla semanttisten tokenien taustalla olevat arvot. Komponentit pysyvät ennallaan.

**Designtokenit** ovat nimettyjä arvoja kaikille brändin toistamille suunnittelupäätöksille: väreille, kirjasintyypeille, tekstiko’oille, väleille, kulmasäteille, varjoille ja animaatioajoituksille. Sen sijaan että kirjoittaisit `#5b21b6` tyylitiedostoon, Figma-tiedostoon ja iOS-sovellukseen, määrität `color.brand.700` kerran yhteen tiedostoon ja luot siitä alustojen muodot. Muuta tokenia, niin tuotteet päivittyvät yhdessä. Yksi yhteinen lähde on koko asian ydin.

## Miltä designtoken näyttää

Tokenilla on nimi, arvo ja tyyppi. [W3C Design Tokens Community Groupin](https://www.w3.org/community/design-tokens/) julkaisema muoto kirjoittaa ne JSONina. Ominaisuudet alkavat dollarimerkillä, jotta ne eivät sekoitu ryhmänimiin.

```json
{
  "color": {
    "violet": {
      "100": { "$type": "color", "$value": "#ede9fe" },
      "500": { "$type": "color", "$value": "#8b5cf6" },
      "700": { "$type": "color", "$value": "#6d28d9" },
      "900": { "$type": "color", "$value": "#4c1d95" }
    },
    "ink": { "$type": "color", "$value": "#14121f" },
    "paper": { "$type": "color", "$value": "#faf8ff" }
  },
  "font": {
    "heading": { "$type": "fontFamily", "$value": ["Fraunces", "Georgia", "serif"] },
    "body": { "$type": "fontFamily", "$value": ["Inter", "system-ui", "sans-serif"] }
  },
  "radius": {
    "control": { "$type": "dimension", "$value": { "value": 10, "unit": "px" } }
  },
  "duration": {
    "quick": { "$type": "duration", "$value": { "value": 160, "unit": "ms" } }
  }
}
```

Perustokenit yhteisöryhmän muodossa. Ryhmät voivat pesiytyä vapaasti. Polusta, kuten color.violet.700, tulee tokenin nimi.

- color.violet.100: #ede9fe
- color.violet.500: #8b5cf6
- color.violet.700: #6d28d9
- color.violet.900: #4c1d95
- color.ink: #14121f
- color.paper: #faf8ff

Yllä olevat väritokenit näytteinä. Ne ovat raaka-aineita: mikään ei vielä kerro, mikä kuuluu painikkeeseen tai otsikkoon.

## Perus-, semanttiset ja komponenttitokenit

Pelkkä värilista on paletti, ei järjestelmä. Vuosia kestävä rakenne koostuu kolmesta tasosta, joista kukin viittaa alempaan. Komponentit eivät koske raaka-arvoihin vaan pyytävät tarkoitusta.

| Taso | Esimerkkinimi | Arvo | Muuttuu kun |
| --- | --- | --- | --- |
| Perus | `color.violet.700` | `#6d28d9` | Paletti uudistetaan |
| Semanttinen | `color.action.primary` | `{color.violet.700}` | Rooli siirtyy toiseen väriin |
| Semanttinen | `color.text.default` | `{color.ink}` | Tumma tila tai uusi brändi |
| Komponentti | `button.primary.background` | `{color.action.primary}` | Yksi komponentti tarvitsee poikkeuksen |

Aaltosulkeissa olevat viittaukset ovat aliaksia. Muuta color.violet.700-arvoa, niin jokainen siihen osoittava token seuraa mukana.

```json
{
  "color": {
    "action": {
      "primary": { "$type": "color", "$value": "{color.violet.700}" },
      "primary-hover": { "$type": "color", "$value": "{color.violet.900}" }
    },
    "text": {
      "default": { "$type": "color", "$value": "{color.ink}" },
      "on-action": { "$type": "color", "$value": "{color.paper}" }
    },
    "surface": {
      "page": { "$type": "color", "$value": "{color.paper}" },
      "tint": { "$type": "color", "$value": "{color.violet.100}" }
    }
  }
}
```

Semanttiset tokenit kuvaavat värin tarkoituksen. Tällä tasolla suunnittelijoiden ja kehittäjien kannattaa keskustella.

Monet tiimit pysähtyvät kahteen tasoon, perus- ja semanttiseen, ja lisäävät komponenttitokeneita vain komponentin todella erotessa. Se pitää tiedoston tarpeeksi pienenä ymmärtää.

## Nimeä designtokenit kestämään

Nimet elävät arvoja pidempään. `color.purple` hajoaa brändin muuttuessa petrooliksi, mutta `color.action.primary` kestää sen. Nimeä semanttiset tokenit roolin mukaan ja perustokenit arvoa kuvaavasti.

### Huonosti vanhenevat nimet

- `color.purple` painikkeille
- `text.dark`, joka on tummassa tilassa vaalea
- `spacing.16` asettelusääntönä
- `blue2`, `blueNew`, `blueFinal`
- Henkilön mukaan nimetty `hero.gradient.lisa`

### Kestävät nimet

- `color.action.primary`
- `color.text.default`
- `space.section`, joka osoittaa arvoon `{space.16}`
- Numeroitu asteikko, kuten `blue.100`-arvosta `blue.900`-arvoon
- `gradient.hero`, jonka väripisteet ovat tokeneita

Valitse järjestys, esimerkiksi luokka, rooli, muunnelma ja tila, ja kirjaa se [brändin tyylioppaaseen](https://gradiently.design/fi/guide/brand-style-guide). Nimeämisen yhtenäisyys merkitsee valittua mallia enemmän.

## Tokenitiedostosta CSS:ään ja sovelluksiin

Tokenitiedostoa ei toimiteta sellaisenaan. Koontivaihe muuntaa sen alustojen tarvitsemaan muotoon. Style Dictionary on yleisimmin käytetty avoimen lähdekoodin työkalu tähän, ja muutkin lukevat samaa muotoa. Verkossa tulos on yleensä CSS:n mukautettuja ominaisuuksia.

```css
:root {
  --color-violet-100: #ede9fe;
  --color-violet-700: #6d28d9;
  --color-violet-900: #4c1d95;
  --color-ink: #14121f;
  --color-paper: #faf8ff;

  --color-action-primary: var(--color-violet-700);
  --color-text-default: var(--color-ink);
  --color-surface-page: var(--color-paper);

  --font-heading: Fraunces, Georgia, serif;
  --radius-control: 10px;
  --duration-quick: 160ms;
}

.button {
  background: var(--color-action-primary);
  color: var(--color-paper);
  border-radius: var(--radius-control);
  transition: background var(--duration-quick) ease;
}
```

Luotu tulos. Aliakset muuttuvat var()-viittauksiksi, joten semanttinen taso säilyy selaimessa. Katso [CSS-muuttujat teemoille](https://gradiently.design/fi/guide/css-custom-properties-theming).

Tailwind v4:n `@theme`-lohko on itsessään tokenitaso: jokainen `--color-*`-muuttuja luo apuluokkia. [Tailwind-värit](https://gradiently.design/fi/guide/tailwind-colors) näyttää väriskaalan kytkemisen siihen. Sama tiedosto voi tuottaa Swift-vakioita ja Android-resursseja. Monialustatiimissä tokenit maksavat silloin itsensä takaisin.

## Tumma tila ja useat brändit

Koska komponentit lukevat vain semanttisia tokeneita, teema on tälle tasolle annettu eri arvosarja. Tumma tila määrittelee uudelleen `color.text.default`- ja `color.surface.page`-arvot, toinen brändi `color.action.primary`-arvon. Komponenteissa mikään ei muutu.

```css
@media (prefers-color-scheme: dark) {
  :root {
    --color-text-default: #e9e5f5;
    --color-surface-page: #0b0a14;
    --color-action-primary: var(--color-violet-500);
  }
}

[data-brand="harbour"] {
  --color-action-primary: #0f766e;
}
```

Kaksi ylikirjoitusta ilman komponenttimuutoksia. Liukuväritkin ansaitsevat omat tummat arvot. [Tumman tilan liukuvärit](https://gradiently.design/fi/guide/dark-mode-gradients) kertoo niiden säätämisestä.

> **Tokenit suunnittelutyökaluissa** Figma Variables tukee kokoelmia ja tiloja, jotka vastaavat siististi perus- ja semanttisia tokeneita sekä vaaleaa ja tummaa teemaa. Pidä tokenitiedosto lähteenä ja synkronoi suunnittelutyökaluun, älä päinvastoin. Muuten ne eroavat kuukauden sisällä.

## Designtokenien käyttöönotto

1. **Kartoita nykyinen tilanne** Kerää kaikki käytetyt värit, fonttikoot ja välit. Varaudu yhden heksamerkin verran eroaviin kaksoiskappaleisiin.
2. **Määritä perustokenit** Tiivistä arvot selkeiksi asteikoiksi. OKLCH pitää väriskaalan askeleet tasaisina. Katso [OKLCH selitettynä](https://gradiently.design/fi/guide/oklch-explained).
3. **Lisää semanttinen taso** Nimeä roolit: teksti, pinta, reunus, toiminto ja palaute. Osoita jokainen perustokeniin.
4. **Automatisoi koonti** Luo CSS ja sovellusresurssit tiedostosta koontivaiheessa, älä käsin.
5. **Suojaa järjestelmä** Tarkista komponenttien raakaheksavärit lintillä, jotta uusi koodi käyttää tokeneita alusta asti.

Tokenit pitävät tuotteen yhtenäisenä, mutta brändit eriytyvät myös sen ulkopuolisissa julkaisuissa, dioissa ja bannereissa. Gradientlyn brändipaketti säilyttää samat päätökset: väripaletit, otsikko- ja leipätekstifontit, logot ja äänensävyn, jotta Studion suunnitelmat sopivat yhteen. Gradiently toimii ChatGPT:ssä, Claudessa ja muissa etä-MCP-palvelimia tukevissa avustajissa. Rajatulla API-avaimella avustaja voi luoda brändin mukaisia suunnitelmia samasta työtilasta. [Brändin yhtenäisyys](https://gradiently.design/fi/guide/brand-consistency) käsittelee laajempaa käytäntöä.

## FAQ

### Mitä ovat designtokenit?

Nimettyjä arvoja suunnittelupäätöksille, kuten väreille, fonteille, väleille, säteille ja liikkeelle. Ne tallennetaan yhteen alustariippumattomaan tiedostoon ja muunnetaan CSS:ksi, sovelluskoodiksi ja suunnittelutyökalun muuttujiksi.

### Mitä eroa on perus- ja semanttisilla tokeneilla?

Perustokenit sisältävät raaka-arvoja, kuten `color.violet.700`. Semanttiset tokenit kuvaavat tarkoituksen, kuten `color.action.primary`, ja osoittavat perustokeniin.

### Ovatko designtokenit sama asia kuin CSS-muuttujat?

Eivät. Tokenit ovat neutraaliin muotoon, kuten JSONiin, tallennettu lähde. CSS:n mukautetut ominaisuudet ovat yksi niistä luotu tulos muiden alustojen tulosten rinnalla.

### Onko designtokeneille vakiomuoto?

W3C Design Tokens Community Group julkaisee JSON-muotoa, joka käyttää $value- ja $type-ominaisuuksia sekä aaltosuljealiaksia. Style Dictionaryn kaltaiset työkalut lukevat sitä.

### Miten designtokenit hoitavat tumman tilan?

Komponentit lukevat semanttisia tokeneita, ja tumma teema antaa niille eri arvot. Komponentteja ei siis tarvitse muuttaa.