Design tokens: ghidul tehnic complet

Ce sunt de fapt design tokens

Acest articol face parte din ghidul nostru complet despre Design Systems. Începe de acolo pentru imaginea de ansamblu.

Conform raportului State of Design Systems 2024 realizat de Specify, 74% dintre design system-urile mature folosesc acum token-uri ca metodă principală de distribuire a deciziilor de design spre cod (Specify, 2024). Design tokens sunt variabile cu nume care stochează decizii de design. Culori, spațiere, tipografie, umbre, raze de border, mișcare. Înlocuiesc valorile hard-codate împrăștiate prin codebase cu un vocabular unic, centralizat.

Iată cel mai simplu mod de a gândi asta. În loc ca un dezvoltator să tasteze #2563EB în paisprezece fișiere, referențiază un token numit color-action-primary. Când culoarea brandului se schimbă, actualizezi o singură valoare într-un singur fișier. Fiecare ecran reflectă schimbarea imediat.

„Dar asta e doar CSS variables." Aud asta constant. CSS custom properties rezolvă problema variabilelor pentru web. Design tokens o rezolvă pentru tot: web, iOS, Android, template-uri de email, site-uri de documentație, chiar și materiale tipărite. Un token este agnostic de platformă prin definiție. Îl scrii o singură dată în JSON (sau YAML, sau un plugin Figma), iar tooling-ul îl transformă în ce are nevoie fiecare platformă.

Îmi amintesc proiectul care m-a convins. Aveam o aplicație web în React și o aplicație nativă iOS care împărțeau același brand. De fiecare dată când echipa de design actualiza o culoare, două echipe de inginerie separate făceau schimbarea independent. Una termina prima. Cealaltă rămânea în urmă cu un sprint sau două. Timp de săptămâni, aplicațiile arătau ca și cum ar fi aparținut unor companii diferite. Token-urile au eliminat problema complet. Un singur fișier sursă, două output-uri automatizate, zero derivă.

De ce există token-urile

Problema nu e că dezvoltatorii uită valorile. Problema e că deciziile de design trăiesc în prea multe locuri simultan. Un fișier Figma spune că butonul principal este #2563EB. Un fișier CSS spune că e var(--blue-500). Un fișier Swift spune că e UIColor(named: "brandBlue"). Trei reprezentări ale aceleiași decizii, menținute de trei persoane care s-ar putea să nu vorbească niciodată între ele.

Token-urile creează o singură sursă de adevăr pentru acea decizie. Token-ul este decizia. Orice altceva este un output derivat.

Cum funcționează arhitectura de token-uri pe trei niveluri?

W3C Design Tokens Community Group formalizează specificația de token-uri din 2019, iar aproape fiecare sistem matur care a adoptat-o folosește o formă de arhitectură pe niveluri (W3C DTCG, 2024). Trei niveluri este structura cea mai frecventă: primitiv, semantic și de componentă. Fiecare strat adaugă context peste cel de dedesubt.

Token-uri primitive

Acestea sunt valori brute. Fără sens, fără context. Doar valoarea în sine.

{
  "color": {
    "blue-500": { "value": "#2563EB" },
    "blue-600": { "value": "#1D4ED8" },
    "gray-100": { "value": "#F3F4F6" },
    "gray-900": { "value": "#111827" }
  },
  "space": {
    "4": { "value": "16px" },
    "8": { "value": "32px" }
  }
}

Gândește-te la primitive ca la paleta ta. blue-500 nu-ți spune pentru ce e. Îți spune cum arată.

Token-uri semantice

Aici intră intenția în scenă. Token-urile semantice mapează sens peste primitive.

{
  "color-action-primary": { "value": "{color.blue-500}" },
  "color-action-primary-hover": { "value": "{color.blue-600}" },
  "color-text-primary": { "value": "{color.gray-900}" },
  "color-bg-surface": { "value": "{color.gray-100}" },
  "spacing-component-gap": { "value": "{space.4}" }
}

Acum sistemul știe că color-action-primary este pentru elemente interactive. Nu-l interesează că valoarea de bază e albastru. Contează rolul.

Token-uri de componentă

Ultimul strat limitează deciziile la elemente UI specifice.

{
  "button-bg-primary": { "value": "{color-action-primary}" },
  "button-bg-primary-hover": { "value": "{color-action-primary-hover}" },
  "button-padding-x": { "value": "{space.4}" },
  "card-bg": { "value": "{color-bg-surface}" }
}

Token-urile de componentă fac fiecare componentă auto-documentată. Un dezvoltator care citește button-bg-primary știe imediat ce controlează token-ul și unde se aplică.

De ce contează cel mai mult nivelul semantic

Cele mai multe arhitecturi de token-uri eșuează la nivelul semantic, nu la cel primitiv sau de componentă. Echipele nimeresc primitivele pentru că sunt doar o listă de valori. Nimeresc token-urile de componentă pentru că se mapează direct pe cod. Dar token-urile semantice te obligă să articulezi de ce-ul din spatele fiecărei decizii. Asta e mai greu. Și când echipele sar peste, ajung cu token-uri de componentă care indică direct spre primitive. Rezultatul? Fiecare schimbare de temă atinge sute de token-uri în loc de câteva.

Am văzut echipe care au refăcut brandul unui produs de 200 de ecrane în mai puțin de o săptămână pentru că nivelul lor semantic era solid. Am văzut și echipe care au petrecut trei luni pe un rebranding pentru că l-au sărit. Nivelul semantic face diferența.

Ce convenții de denumire ar trebui să folosești pentru design tokens?

Un studiu din 2023 realizat de Knapsack a descoperit că echipele cu convenții consistente de denumire a token-urilor rezolvau problemele de predare design-cod cu 38% mai rapid decât cele fără standarde de denumire (Knapsack, 2023). Denumirea este partea cea mai subestimată a unui sistem de token-uri. Un nume prost creează ambiguitate. Ambiguitatea creează inconsistență. Iar inconsistența este exact problema pe care token-urile ar trebui s-o rezolve.

Modelul care funcționează

Cele mai multe sisteme mature folosesc kebab-case cu o structură category-property-variant. Iată câteva exemple:

• color-action-primary
• color-text-secondary
• spacing-component-gap
• font-size-heading-lg
• border-radius-sm
• shadow-elevation-low

Modelul se citește de la stânga la dreapta, de la general la specific. Un dezvoltator care parcurge o listă de token-uri poate grupa și filtra după categorie fără să citească documentația.

Nume care descriu scopul, nu aspectul

Aici greșesc echipele cel mai des. Denumirea unui token blue-button-bg te blochează într-o implementare vizuală. Ce se întâmplă când culoarea brandului se schimbă în verde? Redenumești token-ul și strici fiecare fișier care-l referențiază? Sau lași numele și confuzionezi pe toată lumea pentru că blue-button-bg rezolvă acum în verde?

Niciuna din opțiuni nu e bună. Denumește token-urile după scop. color-action-primary nu-l interesează ce culoare e. Descrie rolul. Valoarea se poate schimba; numele rămâne corect.

Denumire la scară

Când sistemul tău crește peste o sută de token-uri, disciplina în denumire previne haosul. Câteva reguli practice:

Fii previzibil. Dacă un token de culoare este color-text-primary, nu denumi altul text-color-secondary. Păstrează ordinea consistentă.

Folosește mărimi de tricou pentru valori relative. spacing-xs, spacing-sm, spacing-md, spacing-lg. Nu folosi numere precum spacing-1 decât dacă ești sigur că nu vei avea nevoie de ceva între spacing-1 și spacing-2.

Evită abrevierile care nu sunt universale. bg pentru background e în regulă. clr pentru color nu e. Când ai dubii, scrie forma completă.

Cum activează design tokens tematizarea și dark mode?

Conform documentației Material Design 3, Design System-ul Google folosește remaparea semantică a token-urilor pentru a suporta modul light, dark mode și teme cu culori dinamice fără a modifica logica componentelor (Material Design, 2024). Tematizarea este răsplata pentru o arhitectură corectă de token-uri. Dacă nivelul semantic funcționează, tematizarea devine o simplă schimbare de token-uri.

Cum funcționează schimbarea semantică

În modul light, token-urile semantice indică spre un set de primitive:

color-text-primary     -> gray-900
color-bg-surface       -> white
color-action-primary   -> blue-500

În dark mode, aceleași token-uri semantice indică spre primitive diferite:

color-text-primary     -> gray-100
color-bg-surface       -> gray-900
color-action-primary   -> blue-400

Componentele nu se schimbă niciodată. Un buton referențiază color-action-primary. Dacă aceasta rezolvă în blue-500 sau blue-400 depinde de tema activă. Componenta nu știe și nu-i pasă.

Tematizare multi-brand

Același principiu se extinde la scenarii multi-brand. Să zicem că construiești un produs SaaS white-label. Brandul A folosește albastru, Brandul B violet, Brandul C verde. Fiecare brand primește propriul set de token-uri primitive. Nivelul semantic rămâne identic. Componentele rămân identice. Livrezi un singur codebase cu mai multe seturi de token-uri.

Într-un proiect din 2024, am construit o platformă de produs care deservea patru branduri. Biblioteca de componente era 100% partajată. Identitatea fiecărui brand venea dintr-un singur fișier JSON conținând circa 60 de token-uri primitive. Adăugarea unui al cincilea brand a durat două ore, cea mai mare parte din timp fiind dedicată alegerii nuanțelor potrivite. Zero modificări de componente.

Dincolo de culoare: moduri de densitate și contrast

Tematizarea nu se limitează la culoare. Poți defini teme de spațiere pentru densitate compactă versus confortabilă. Modurile de accesibilitate cu contrast ridicat pot remapa atât token-urile de culoare, cât și cele de tipografie. Arhitectura e aceeași: schimbă nivelul semantic, păstrează restul intact.

Ce instrumente ai nevoie pentru design tokens?

Sondajul Design Tools Survey 2024 de la UXTools a raportat că 61% dintre echipele de design care folosesc token-uri se bazează fie pe Style Dictionary, fie pe Tokens Studio ca pipeline principal de transformare (UXTools, 2024). Tooling-ul este ce transformă fișierele de token-uri dintr-o idee bună într-un pipeline automatizat.

Style Dictionary

Construit de Amazon, Style Dictionary este cel mai consacrat instrument de transformare a token-urilor. Definești token-urile în JSON. Style Dictionary le transformă în output-uri specifice platformei: CSS custom properties, variabile Sass, cataloage de asset-uri Swift, resurse Android XML și altele.

Configurația e simplă. Specifici fișierele sursă, definești platformele de output și rulezi o comandă de build. Style Dictionary se ocupă de toate conversiile de format.

Figma → JSON → Style Dictionary → variabile CSS
                                 → constante iOS Swift
                                 → resurse Android XML

Adevărata forță a Style Dictionary este extensibilitatea. Poți scrie transformări personalizate pentru orice format de output. Ai nevoie de token-uri ca valori de configurare Tailwind? Scrie un formatter. Le vrei ca și constante Flutter? Aceeași abordare.

Tokens Studio

Tokens Studio (fost Figma Tokens) funcționează din direcția opusă. E un plugin Figma care permite designerilor să creeze și să gestioneze token-uri direct în Figma, apoi să le sincronizeze într-un repository Git ca JSON. Dezvoltatorii preiau JSON-ul și îl procesează prin Style Dictionary sau un instrument similar.

Acesta este cel mai aproape lucru de un workflow real bidirecțional între design și cod pe care l-a produs industria. Designerii lucrează în instrumentul lor. Dezvoltatorii în al lor. Token-urile sunt contractul partajat din mijloc.

Când să construiești tooling personalizat

Aproape niciodată, cel puțin nu la început. Style Dictionary acoperă 90% din cazuri out of the box. Tokens Studio acoperă pipeline-ul Figma-spre-cod. Construiește tooling personalizat doar când întâmpini limitări pe care instrumentele existente nu le pot rezolva prin configurație sau plugin-uri.

Excepția e validarea. Ai putea vrea un pas de linting personalizat în CI care verifică încălcări de denumire, token-uri semantice lipsă sau primitive orfane. Acest tip de tooling ușor se plătește rapid singur.

Cum circulă token-urile din Figma în producție?

Salesforce, care a inventat termenul „design tokens" în 2014, menține peste 3.000 de token-uri în Lightning Design System și automatizează distribuția lor printr-un pipeline CI/CD (Salesforce, 2024). Fluxul de lucru nu e complicat, dar necesită disciplină atât din partea designerilor, cât și a dezvoltatorilor.

Fluxul de lucru al designerului

În Figma, designerii aplică token-uri componentelor folosind Tokens Studio. Culoarea de fill a unui buton nu este #2563EB. Este color-action-primary. Fiecare element de design referențiază un token, nu o valoare brută.

Când un designer schimbă valoarea unui token, Tokens Studio împinge JSON-ul actualizat pe o ramură Git. Un pull request se deschide automat. Echipa de dezvoltare îl revizuiește, iar pipeline-ul CI rulează Style Dictionary pentru a genera output-urile actualizate de platformă.

Fluxul de lucru al dezvoltatorului

Dezvoltatorii consumă token-uri ca CSS custom properties, variabile Sass sau constante native de platformă. O componentă React ar putea arăta așa:

.button-primary {
  background-color: var(--button-bg-primary);
  padding: var(--spacing-component-gap);
  border-radius: var(--border-radius-sm);
}

Fără coduri hex. Fără numere magice. Dacă un token se schimbă upstream, componenta reflectă automat actualizarea după următorul build.

Ce se întâmplă când designul și codul se desincronizează

Se vor desincroniza. Cineva va pune o valoare hard-codată pentru că e grăbit. Un designer va aplica o culoare brută în Figma pentru că token-ul nu există încă. O suprascriere punctuală va intra pe un feature branch și nu va fi niciodată refactorizată.

Soluția e procesul, nu instrumentele. Rulează un audit de acoperire a token-urilor trimestrial. Verifică automat valorile hard-codate în CI. Include crearea de token-uri în checklist-ul de review al designului. Și acceptă că o anumită derivă e normală. Perfecțiunea nu e scopul. Menținerea derivei sub control — asta contează.

În fiecare echipă cu care am lucrat, conversația despre derivă apare pe la luna a treia. Sistemul e live, lumea îl folosește, și apoi cineva descoperă un ecran unde jumătate din valori sunt hard-codate. Nu intra în panică. Tratează-o ca datorie tehnică: loghează, prioritizează, remediază incremental. Sistemul nu trebuie să fie perfect din prima zi.

Care sunt cele mai frecvente greșeli cu design tokens?

O analiză din 2023 de la Supernova a descoperit că 42% dintre echipele de Design System au raportat „token bloat" drept principala provocare de mentenanță, cu un sistem enterprise mediu conținând peste 2.000 de token-uri (Supernova, 2023). Să știi ce să nu faci contează la fel de mult ca să cunoști procesul. Iată greșelile pe care le văd cel mai des.

Sărirea nivelului semantic

Am mai spus asta, dar merită repetat pentru că e cea mai frecventă și cea mai costisitoare greșeală. Fără token-uri semantice, pierzi capacitatea de a tematiza, de a face rebranding sau de a suporta dark mode fără să atingi fiecare componentă. Nu sări peste el.

Token bloat

Mai multe token-uri nu înseamnă mai bine. Fiecare token e o decizie pe care trebuie s-o menții, documentezi și comunici. Dacă sistemul tău are 4.000 de token-uri și jumătate nu sunt referențiate nicăieri, ai o povară de mentenanță fără niciun beneficiu.

Începe cu mai puține token-uri decât crezi că ai nevoie. Adaugă token-uri când un caz de utilizare concret cere unul. Șterge token-urile pe care nimeni nu le referențiază. Rulează audituri de token-uri moarte la fel cum ai rula analize de cod mort.

Denumirea token-urilor după aspect

red-error-text pare descriptiv până când brandul tău folosește portocaliu pentru erori. Denumește token-urile după rolul lor: color-feedback-error. Valoarea poate fi roșu, portocaliu sau magenta. Numele rămâne corect indiferent.

Neocumentarea intenției

Un token numit spacing-component-gap e clar. Dar care e utilizarea intenționată? Este spațiul dintre componente vecine într-un layout? Padding-ul intern al unei componente? Ambele? Documentează intenția alături de valoare. O descriere de o linie per token economisește ore de ghicit.

Suprascrieri punctuale

„Doar de data asta, o să pun padding-ul hard-codat." Celebrele ultime cuvinte. Suprascierile punctuale ocolesc sistemul și creează exact tipul de inconsistență pe care token-urile au fost construite să-l prevină. Dacă o componentă are nevoie de o valoare care nu există ca token, creează token-ul. Dacă valoarea e cu adevărat unică, pune sub semnul întrebării dacă designul în sine nu ar trebui ajustat.

Punând totul cap la cap

Design tokens nu sunt un trend. Sunt infrastructură. Rezolvă problema reală de a menține deciziile de design consistente între platforme, echipe și în timp.

Concluziile practice: structurează token-urile pe trei niveluri și investește cel mai mult efort în nivelul semantic. Folosește denumire bazată pe scop, nu pe aspect. Alege instrumente consacrate înainte de a construi unele personalizate. Automatizează pipeline-ul din Figma în producție. Și rulează audituri regulate pentru a prinde deriva înainte să se acumuleze.

Dacă construiești un Design System de la zero, începe cu token-urile. Sunt fundația pe care stă tot restul. Nimerește-le și componentele, temele și suportul multi-platformă vin natural. Greșește-le și vei simți durerea în fiecare proiect care urmează.

Pentru imaginea completă despre construirea și menținerea unui Design System, mergi la ghidul complet despre Design Systems. Pentru detalii pas cu pas de implementare, vezi Design System 101.

Ultima revizuire: 16 mar. 2026. Actualizăm articolele când standardele din industrie se schimbă sau când apar date noi.