Design token-lər və theming
Design token-lərin nə olduğu və necə qurulduğu: primitiv və semantik səviyyələrdən CSS custom property-lərə, yanıb-sönməyən tünd rejimə, token pipeline-larına, çoxbrendli theming-ə, kontrast yoxlamalarına və token-lərin idarə olunmasına qədər.
Oxu səviyyəsi
Seçilmiş səviyyəyə qədər olan bölmələr göstərilir.
Başlamazdan əvvəl
İlkin şərt yoxdur.
Bu mövzu Junior səviyyəsindən başlayır.
Design token nədir
Design token adı olan dizayn qərarıdır: color-text-default — #1f2328, space-4 — 16px, radius-control — 6px. Ad dəyərin nə üçün olduğunu deyir, dəyər isə onun bu gün necə göründüyünü. Dizaynerlər və developer-lər adla danışır, dəyəri isə yalnız token mənbəyi bilir.
Token olmayanda eyni qərar yüzlərlə yerə əl ilə köçürülür:
.button {
background: #0b5fff;
border-radius: 6px;
padding: 8px 16px;
}
.link {
color: #0b5fff;
}Brendin mavisi dəyişəndə kimsə bütün #0b5fff-ləri tapmalı və hər biri üçün qərar verməlidir: bu, "əsas əməliyyat rəngidir", yoxsa təsadüfən eyni mavidir? Token-lərlə komponentlər qərarın özünə istinad edir və dəyər bir yerdə dəyişir:
.button {
background: var(--color-action-bg);
border-radius: var(--radius-control);
padding: var(--space-2) var(--space-4);
}
.link {
color: var(--color-link);
}Nə token olur
- Rəng: fonlar, mətn, kənar xətləri, fokus halqaları, status rəngləri.
- Boşluq və ölçü: boşluq şkalası (4, 8, 12, 16, 24…), kontrolların hündürlüyü, ikon ölçüləri.
- Tipoqrafiya: şrift ailələri, ölçülər, qalınlıq, sətir hündürlüyü; çox vaxt
text-bodykimi stillərdə qruplaşdırılır. - Forma və dərinlik: radius, kənar qalınlığı, kölgələr,
z-indexqatları. - Hərəkət: animasiya müddətləri və easing əyriləri.
Hər rəqəmə token lazım deyil. Token o zaman özünü doğruldur ki, dəyər təkrarlanan və hər yerdə birdən dəyişməli olan qərardır.
Ortaq format
Token-lər adətən məlumat kimi saxlanılır və hər platforma üçün koda çevrilir. W3C Design Tokens Community Group bu məlumat üçün heç bir vendor-dan asılı olmayan format dərc edir: Design Tokens Format Module. Onun ilk stabil versiyası, 2025.10, 28 oktyabr 2025-ci ildə dərc olunub; bu, Community Group hesabatıdır, W3C standartı deyil. Token $value sahəsi olan obyektdir; $type bütün qrup üçün bir dəfə yazıla bilər, başqa token-ə istinad isə fiqurlu mötərizədə yazılır:
{
"color": {
"$type": "color",
"blue-600": {
"$value": { "colorSpace": "srgb", "components": [0.043, 0.373, 1], "hex": "#0b5fff" }
},
"action-bg": { "$value": "{color.blue-600}" }
}
}A design token is a named design decision: color-text-default is #1f2328, space-4 is 16px, radius-control is 6px. The name says what the value is for; the value says how it looks today. Designers and engineers talk about the name, and only the token source knows the value.
Without tokens the same decision is copied by hand into hundreds of places:
.button {
background: #0b5fff;
border-radius: 6px;
padding: 8px 16px;
}
.link {
color: #0b5fff;
}When the brand blue changes, someone has to find every #0b5fff and decide whether each one is "the action color" or just happens to be the same blue. With tokens, components refer to the decision and the value changes in one place:
.button {
background: var(--color-action-bg);
border-radius: var(--radius-control);
padding: var(--space-2) var(--space-4);
}
.link {
color: var(--color-link);
}What becomes a token
- Color: backgrounds, text, borders, focus rings, status colors.
- Spacing and sizing: a spacing scale (4, 8, 12, 16, 24…), control heights, icon sizes.
- Typography: font families, sizes, weights, line heights, often grouped into styles like
text-body. - Shape and depth: radius, border width, shadows,
z-indexlayers. - Motion: durations and easing curves.
Not every number needs a token. A token pays off when the value is a decision that repeats and should change everywhere at once.
A shared format
Tokens are usually kept as data and turned into code for each platform. The W3C Design Tokens Community Group publishes a vendor-neutral format for that data, the Design Tokens Format Module. Its first stable version, 2025.10, was published on 28 October 2025; it is a Community Group report, not a W3C Standard. A token is an object with a $value; $type can be set once on a group, and a reference to another token is written in curly braces:
{
"color": {
"$type": "color",
"blue-600": {
"$value": { "colorSpace": "srgb", "components": [0.043, 0.373, 1], "hex": "#0b5fff" }
},
"action-bg": { "$value": "{color.blue-600}" }
}
}Səviyyələr və adlandırma: primitiv, semantik, komponent
Token dəstlərinin çoxu üç səviyyədən ibarətdir və hər səviyyə yalnız özündən aşağıdakına istinad edir.
- Primitiv (baza) token-lər xam dəyərləri saxlayır: palitranı və şkalaları.
color-blue-600,color-gray-900,space-4. Onlar nə olduqlarına görə adlanır və hələ heç bir məna daşımır:blue-600harada işləndiyi barədə heç nə demir. - Semantik (alias) token-lər dəyərə məqsəd verir:
color-bg-surface,color-text-muted,color-border-focus,color-status-danger. Onların dəyəri primitivə istinaddır. Temalar əsasən bu səviyyədə qurulur: tünd temacolor-bg-surface-i ağa yox,gray-900-ə yönəldir. - Komponent token-ləri (məcburi deyil) bir komponentə aiddir:
button-primary-bg,input-border. Adətən semantik token-lərə istinad edir. Bir komponent bir brenddə fərqli görünməli olanda faydalıdır; hər komponentə heç kimin dəyişmədiyi onlarla token veriləndə isə baha başa gəlir.
:root {
--color-blue-600: #0b5fff;
--color-blue-700: #0047d6;
--color-gray-0: #ffffff;
--color-gray-900: #1f2328;
--color-bg-surface: var(--color-gray-0);
--color-text-default: var(--color-gray-900);
--color-action-bg: var(--color-blue-600);
--color-action-bg-hover: var(--color-blue-700);
--button-primary-bg: var(--color-action-bg);
}Komponentlər niyə semantik token-lərdən istifadə edir
--color-blue-600-ı oxuyan komponent qərarı koda bərkidib: "mənim fonum mavidir". Tünd rejimə və ya başqa brendə fərqli əməliyyat rəngi lazım olanda bu komponenti dəyişmək lazım gələcək. --color-action-bg-ni oxuyan komponent isə soruşur: "burada əməliyyat rəngi hansıdır?" — cavabı tema verir. Qayda belədir: komponentlər semantik və ya komponent token-lərini oxuyur, primitivləri yalnız tema faylları oxuyur. Komandalar bunu çox vaxt lint qaydası ilə qoruyur: komponent stillərində xam hex dəyərlərinə və primitiv adlara icazə verilmir.
Adlandırma
Yaxşı ad proqnozlaşdırıla bilən addır: onu axtarmadan təxmin edə bilirsən. Geniş yayılmış ardıcıllıq: kateqoriya, xassə, rol, sonra vəziyyət:
color-bg-surface
color-bg-surface-raised
color-text-muted
color-border-focus
color-action-bg-hover
font-size-bodySemantik token-ləri dəyərə görə yox, rola görə adlandır: color-red yox, color-text-danger. Brend xətaları narıncı göstərməyə başladığı gün "red" adı yalana çevrilir. Şkala adlarını neytral saxla (blue-600, space-4) ki, yeni pillə əlavə edəndə qalanların adını dəyişməyəsən.
Most token sets have three tiers, and each tier refers only to the tier below it.
- Primitive (base) tokens hold raw values: the palette and the scales.
color-blue-600,color-gray-900,space-4. They are named after what they are and carry no meaning yet:blue-600says nothing about where it is used. - Semantic (alias) tokens give a value a purpose:
color-bg-surface,color-text-muted,color-border-focus,color-status-danger. Their value is a reference to a primitive. Themes are mostly built in this tier: the dark theme pointscolor-bg-surfaceatgray-900instead of white. - Component tokens (optional) belong to one component:
button-primary-bg,input-border. They usually alias semantic tokens. They help when one component must look different in one brand; they cost a lot when every component gets dozens of tokens nobody ever overrides.
:root {
--color-blue-600: #0b5fff;
--color-blue-700: #0047d6;
--color-gray-0: #ffffff;
--color-gray-900: #1f2328;
--color-bg-surface: var(--color-gray-0);
--color-text-default: var(--color-gray-900);
--color-action-bg: var(--color-blue-600);
--color-action-bg-hover: var(--color-blue-700);
--button-primary-bg: var(--color-action-bg);
}Why components use semantic tokens
A component that reads --color-blue-600 has hard-coded a decision: "my background is blue". When dark mode or another brand needs a different action color, that component has to change. A component that reads --color-action-bg asks "what is the action color here?" and the theme answers. The rule: components read semantic or component tokens; only theme files read primitives. Teams often enforce it with a lint rule that rejects raw hex values and primitive names in component styles.
Naming
A good name is predictable: you can guess it without looking it up. A common order is category, property, role, then state:
color-bg-surface
color-bg-surface-raised
color-text-muted
color-border-focus
color-action-bg-hover
font-size-bodyName semantic tokens by role, never by value: color-text-danger, not color-red. "Red" stops being true the day a brand shows errors in orange. Keep scale names neutral (blue-600, space-4) so a step can be added without renaming the others.
CSS custom property-lərlə theming
Vebdə token-lər adətən CSS custom property-lərə çevrilir. Theming-i onların üç xüsusiyyəti işlək edir.
Miras alınırlar. -- ilə elan olunan custom property bütün nəsil elementlərə ötürülür, ta ki onlardan biri onu yenidən təyin edənə qədər. Ona görə də :root defolt dəyərləri saxlayır, tema isə sadəcə bəzi dəyərləri yenidən elan edən elementdir:
:root {
--color-bg-surface: #ffffff;
--color-text-default: #1f2328;
}
[data-theme="dark"] {
--color-bg-surface: #0d1117;
--color-text-default: #e6edf3;
}
.card {
background: var(--color-bg-surface);
color: var(--color-text-default);
}Bütün səhifə tünd olsun deyə data-theme="dark"-ı <html>-ə, açıq səhifənin içində bir tünd blok üçün isə bir <section>-a qoy. Eyni .card qaydası hər iki halda işləyir, çünki hər element var()-ı özünə miras çatan dəyərlərlə həll edir.
Gec həll olunurlar. Brauzer custom property-ni parse edəndə demək olar ki, istənilən dəyəri qəbul edir və onu var() işlənən yerdə, stilləri hesablayanda yerinə qoyur. Bunun iki nəticəsi var:
var(--name, fallback)fallback-i yalnız--name-in dəyəri olmayanda işlədir; adətən bu, onun ağacın yuxarısında heç yerdə təyin olunmaması deməkdir. Birinci vergüldən sonrakı hər şey fallback sayılır, ona görəvar(--a, red, blue)-nun fallback-ired, blueolur. Bir neçə fallback iç-içə yazılır:var(--a, var(--b, red)).- Yerinə qoyulan dəyər xassəyə uyğun gəlmirsə (
--size: 20px; color: var(--size)), elan invalid at computed-value time olur. Bu halda xassəunsetkimi davranır:colorkimi miras alınan xassələr valideynin dəyərini, qalanları isə ilkin dəyərini alır. Əvvəlkicolorelanları artıq atılıb, fallback da işləmir, çünki--sizetəyin olunub.
Tipli ola bilərlər. @property custom property-ni sintaksis, miras bayrağı və ilkin dəyərlə qeydiyyata alır. Baseline 2024-dür (iyul 2024-dən yeni əlçatandır); syntax və inherits məcburidir, initial-value isə sintaksis "*" olmayanda məcburidir.
@property --color-accent {
syntax: "<color>";
inherits: true;
initial-value: #0b5fff;
}Sintaksisə uyğun gəlməyən dəyər rədd edilir, ona görə element düzgün rəngdə qalır (miras alınan dəyər və ya initial-value). Brauzer qeydiyyatdan keçmiş <color>-u animasiya edə də bilir, inherits: false isə token-in nəsil elementlərə sızmasının qarşısını alır.
JavaScript-dən getComputedStyle(element).getPropertyValue("--color-bg-surface") elementin gördüyü dəyəri oxuyur, element.style.setProperty("--color-accent", value) isə dəyəri inline təyin edir.
On the web, tokens usually become CSS custom properties. Three of their properties make theming work.
They inherit. A custom property declared with -- is inherited by every descendant until one of them sets it again. So :root holds the defaults, and a theme is simply an element that redeclares some of them:
:root {
--color-bg-surface: #ffffff;
--color-text-default: #1f2328;
}
[data-theme="dark"] {
--color-bg-surface: #0d1117;
--color-text-default: #e6edf3;
}
.card {
background: var(--color-bg-surface);
color: var(--color-text-default);
}Put data-theme="dark" on <html> for a dark page, or on one <section> for a dark block inside a light page. The same .card rule works in both, because each element resolves var() with the values it inherits.
They are resolved late. The browser accepts almost any value when it parses a custom property and substitutes it where var() is used, when it computes styles. Two consequences:
var(--name, fallback)uses the fallback only when--namehas no value, typically because it is not defined anywhere up the tree. Everything after the first comma is the fallback, sovar(--a, red, blue)falls back tored, blue. Several fallbacks are nested:var(--a, var(--b, red)).- If the substituted value is wrong for the property (
--size: 20px; color: var(--size)), the declaration is invalid at computed-value time. The property then behaves asunset: inherited properties likecolortake the parent's value, others their initial value. The earliercolordeclarations are already discarded, and the fallback is not used, because--sizeis defined.
They can be typed. @property registers a custom property with a syntax, an inheritance flag and an initial value. It is Baseline 2024 (newly available since July 2024); syntax and inherits are required, and initial-value is required unless the syntax is "*".
@property --color-accent {
syntax: "<color>";
inherits: true;
initial-value: #0b5fff;
}A value that does not match the syntax is rejected, so the element keeps a valid color (the inherited value or initial-value). The browser can also animate a registered <color>, and inherits: false stops a token from leaking into descendants.
From JavaScript, getComputedStyle(element).getPropertyValue("--color-bg-surface") reads the value an element sees, and element.style.setProperty("--color-accent", value) sets one inline.
Tünd rejim: sistem seçimi, istifadəçi seçimi, yanıb-sönmə olmadan
Tam tünd rejimin üç hissəsi var: sistemə uy, istifadəçiyə onu dəyişməyə imkan ver və heç vaxt ilk kadrı səhv temada çəkmə.
Sistemə uy. prefers-color-scheme media xüsusiyyəti istifadəçinin seçimini bildirir (yanvar 2020-dən Baseline, geniş əlçatandır). color-scheme-i də elan et ki, brauzerin öz UI-ı da uyğunlaşsın: defolt fon, form kontrolları, scrollbar-lar (yanvar 2022-dən Baseline, geniş əlçatandır). light-dark() funksiyası istifadə olunan rəng sxemi açıq olanda birinci rəngi, tünd olanda ikincini seçir. Ona color-scheme: light dark lazımdır və o, Baseline 2024-dür (may 2024-dən yeni əlçatandır), ona görə dəstəklədiyin brauzerləri yoxla.
:root {
color-scheme: light dark;
--color-bg-surface: light-dark(#ffffff, #0d1117);
--color-text-default: light-dark(#1f2328, #e6edf3);
--color-link: light-dark(#0b5fff, #4c8dff);
}
:root[data-theme="light"] {
color-scheme: light;
}
:root[data-theme="dark"] {
color-scheme: dark;
}light-dark() olmadan eyni iş iki qayda tələb edir: tünd dəyərlər @media (prefers-color-scheme: dark) { :root:not([data-theme="light"]) { … } } içində və bir də :root[data-theme="dark"]-da yazılır.
İstifadəçiyə seçim ver. Üç variantlı seçimi saxla — system, light və ya dark — və onu <html>-də data-theme atributu kimi göstər; system atributun olmaması deməkdir. CSS əməliyyat sistemindəki dəyişikliyə özü uyğunlaşır; matchMedia("(prefers-color-scheme: dark)")-ya yalnız JS ilə çəkilən şeylər üçün qulaq as, məsələn canvas qrafiki üçün.
Səhv temanın yanıb-sönməsi olmasın. Saxlanmış seçim React effektində tətbiq olunursa, ilk kadr defolt temada çəkilir və sonra dəyişir. Seçimi ilk paint-dən əvvəl, <head>-dəki kiçik inline skriptlə tətbiq et. Inline klassik skript olduğu üçün body parse və render olunmazdan əvvəl işləyir:
<head>
<meta name="color-scheme" content="light dark" />
<script>
try {
const theme = localStorage.getItem("theme");
if (theme === "light" || theme === "dark") {
document.documentElement.dataset.theme = theme;
}
} catch {}
</script>
<link rel="stylesheet" href="/app.css" />
</head>Server render-də seçimi cookie-də də saxla ki, server dərhal <html data-theme="dark"> göndərə bilsin. Skript əvvəl <html>-in atributlarını dəyişəndə React uyğunsuzluq barədə xəbərdarlıq edir; <html>-dəki suppressHydrationWarning bunu yalnız həmin elementin atributları üçün susdurur.
A complete dark mode has three parts: follow the system, let the user override it, and never paint the wrong theme first.
Follow the system. The prefers-color-scheme media feature reports the user's preference (Baseline widely available since January 2020). Also declare color-scheme, so the browser's own UI follows: the default canvas, form controls, scrollbars (Baseline widely available since January 2022). The light-dark() function picks its first color when the used color scheme is light and the second when it is dark. It needs color-scheme: light dark and is Baseline 2024, newly available since May 2024, so check your browser targets.
:root {
color-scheme: light dark;
--color-bg-surface: light-dark(#ffffff, #0d1117);
--color-text-default: light-dark(#1f2328, #e6edf3);
--color-link: light-dark(#0b5fff, #4c8dff);
}
:root[data-theme="light"] {
color-scheme: light;
}
:root[data-theme="dark"] {
color-scheme: dark;
}Without light-dark(), the same thing takes two rules: the dark values inside @media (prefers-color-scheme: dark) { :root:not([data-theme="light"]) { … } } and again in :root[data-theme="dark"].
Let the user override it. Store a three-way choice, system, light or dark, and reflect it as data-theme on <html>; system means no attribute. CSS follows OS changes on its own; listen to matchMedia("(prefers-color-scheme: dark)") only for things drawn in JS, like a canvas chart.
No flash of the wrong theme. If the stored choice is applied in a React effect, the first frame is painted with the default theme and then flips. Apply it before the first paint with a small inline script in <head>. An inline classic script is , so it runs before the body is parsed and rendered:
<head>
<meta name="color-scheme" content="light dark" />
<script>
try {
const theme = localStorage.getItem("theme");
if (theme === "light" || theme === "dark") {
document.documentElement.dataset.theme = theme;
}
} catch {}
</script>
<link rel="stylesheet" href="/app.css" />
</head>With server rendering, keep the choice in a cookie too, so the server can send <html data-theme="dark"> straight away. When a script changes attributes of <html> before , React warns about the mismatch; suppressHydrationWarning on <html> silences it for that element's attributes only.
Temaları sındıran tələlər
Vaxtından əvvəl həll olunan alias. Bu, işlək brend dəyişdiricisinə oxşayır, amma qırmızı brenddə bütün düymələr mavi qalır:
:root {
--brand-primary: blue;
--button-bg: var(--brand-primary);
}
[data-brand="red"] {
--brand-primary: red;
}
button {
background: var(--button-bg);
}Custom property-nin içindəki var() onu elan edən elementdə, yəni burada :root-da yerinə qoyulur. Nəsil elementlər düsturu yox, nəticəni (blue) miras alır. Həll: alias-ları tema təyin edə bilən hər elementdə elan et, məsələn :root, [data-brand] { --button-bg: var(--brand-primary); }, və ya hər tema bloku öz semantik token-lərini birbaşa təyin etsin.
Koda bərkidilmiş dəyərlər. #fff, rgba(0, 0, 0, 0.1), inline SVG-lərin içindəki rənglər, ağ fonlu şəkillər, JavaScript-də yazılmış qrafik palitrası. Açıq temada düzgün görünür, tünd temada sınır. İkonlarda currentColor işlət, canvas-da çəkmək üçün token-ləri getComputedStyle ilə oxu, komponent stillərindən xam dəyərləri lint ilə təmizlə.
Primitiv işlədən komponentlər. Komponentdəki var(--color-blue-600) temalı görünür, amma tünd rejimə də, başqa brendlərə də məhəl qoymur.
Səssiz yazı səhvləri. var(--color-bg-surfce) heç nə log etmir: xassə unset olur və kart şəffaflaşır. Editorda avtomatik tamamlanma üçün token adlarının siyahısını generasiya et, naməlum adları lint ilə tut, hər temada vizual reqressiya testləri işlət.
Tünd tema tərsinə çevrilmiş açıq tema deyil. Tünd fonda kölgələr demək olar ki, görünmür, ona görə hündürlük adətən daha açıq fonlarla göstərilir. Brend rənglərinə çox vaxt daha açıq pillə lazım olur: #0b5fff ağ fonda 5.13:1 verir, #0d1117 üzərində mətn kimi isə cəmi 3.69:1, yəni adi mətn üçün tələb olunan 4.5:1-dən aşağı. Hər temanın öz kontrast yoxlaması olmalıdır.
color-scheme yoxdur. Onsuz tünd temanın içində native input-lar, scrollbar-lar və <select> popup-ları açıq qalır.
Tema paint-dən sonra tətbiq olunur. Temanı effektdə və ya fetch-dən sonra təyin etmək tünd rejim bölməsində təsvir olunan yanıb-sönməyə gətirir, üstəlik bütün səhifə iki dəfə stillənir.
Heç kimin tapa bilmədiyi token-lər. gray-light-2 kimi adları olan əlli bir-birinə oxşar boz rəng insanları yenidən hex kopyalamağa vadar edir. Kiçik və sənədləşdirilmiş dəst hər şeyi əhatə edən dəstdən yaxşıdır.
An alias resolved too early. This looks like a working brand switch, but every button in the red brand stays blue:
:root {
--brand-primary: blue;
--button-bg: var(--brand-primary);
}
[data-brand="red"] {
--brand-primary: red;
}
button {
background: var(--button-bg);
}var() inside a custom property is substituted on the element that declares it, here :root. Descendants inherit the result (blue), not the formula. Fix it by declaring the aliases on every element that can set a theme, for example :root, [data-brand] { --button-bg: var(--brand-primary); }, or by letting each theme block set its semantic tokens directly.
Hard-coded values. #fff, rgba(0, 0, 0, 0.1), colors inside inline SVGs, images with a white background, a chart palette in JavaScript. They look right in the light theme and break in the dark one. Use currentColor in icons, read tokens with getComputedStyle for canvas drawing, and lint raw values out of component styles.
Components that use primitives. var(--color-blue-600) in a component looks themed, but it ignores dark mode and every other brand.
Silent typos. var(--color-bg-surfce) logs nothing: the property becomes unset and the card turns transparent. Generate a list of token names for editor autocompletion and lint unknown names; run visual regression tests in every theme.
Dark is not inverted light. Shadows barely show on dark surfaces, so elevation is usually expressed with lighter surfaces. Brand colors often need a lighter step: #0b5fff reaches 5.13:1 against white but only 3.69:1 as text on #0d1117, below the 4.5:1 needed for body text. Every theme needs its own contrast check.
No color-scheme. Without it, native inputs, scrollbars and <select> popups stay light inside a dark theme.
Theme applied after paint. Setting the theme in an effect or after a fetch gives the flash described in the dark mode section, and the whole page is styled twice.
Tokens no one can find. Fifty near-identical grays with names like gray-light-2 make people copy hex values again. A small, documented set beats a complete one.
Bir mənbə, çox platforma: token pipeline-ı
Eyni məhsul veb, iOS və Android-də buraxılanda token-lərin bir həqiqət mənbəyi olmalıdır: pull request-lərdə redaktə olunan və ya dizayn alətindən ixrac edilən DTCG formatlı JSON faylları. Build addımı istinadları həll edir, token-lərin adlarını çevirir, vahidləri və rəngləri konvertasiya edir və hər platforma üçün kodu generasiya edir:
tokens/*.tokens.json (DTCG)
|
v
Style Dictionary
|
+--> web/tokens.css, web/tokens.js, web/tokens.d.ts
+--> ios/Tokens.swift
+--> android/colors.xml, android/Tokens.ktƏn geniş yayılmış build aləti Style Dictionary-dir. O, hər platforma üçün bir transform qrupu tətbiq edir (adları kebab və ya Pascal case-ə çevirir, ölçüləri rem-ə keçirir, rəngləri formatlayır) və faylları css/variables, javascript/es6, typescript/es6-declarations, ios-swift/class.swift, android/resources, compose/object kimi formatlarda yazır. 4-cü versiyadan DTCG formatını dəstəkləyir; sənədlərinə görə 2025.10-un tam dəstəyi hələ 5-ci versiyada üzərində işlənən məsələdir.
import StyleDictionary from "style-dictionary";
const sd = new StyleDictionary({
source: ["tokens/**/*.tokens.json"],
platforms: {
css: {
transformGroup: "css",
buildPath: "dist/web/",
files: [
{
destination: "tokens.css",
format: "css/variables",
options: { outputReferences: true },
},
],
},
js: {
transformGroup: "js",
buildPath: "dist/web/",
files: [{ destination: "tokens.js", format: "javascript/es6" }],
},
},
});
await sd.buildAllPlatforms();outputReferences: true CSS-də istinadları saxlayır (--color-action-bg: var(--color-blue-600)): nəticə oxunaqlı olur, səviyyələr DevTools-da görünür. Bu seçim olmadan hər token hazır dəyər kimi yazılır və temalar primitivləri iç-içə elementlərdə dəyişəndə "vaxtından əvvəl həll olunan alias" tələsi yaranmır.
Pipeline-ı sağlam saxlayan qaydalar
- Generasiya olunan fayllar build nəticəsidir. Heç kim
tokens.css-i əl ilə redaktə etmir; review JSON diff-i üzərində aparılır. - Tipli çıxış. Generasiya olunan TypeScript elanları avtomatik tamamlanma verir, silinmiş token isə səssiz
unsetyox, kompilyasiya xətası olur. - Paketə versiya ver. Token-ləri semver ilə versiyalanan paket kimi dərc et: token-in adını dəyişmək və ya onu silmək breaking change-dir. Dəyərin dəyişməsi API mənasında breaking deyil, amma pikselləri dəyişir, ona görə buraxılışdan əvvəl vizual reqressiya testlərini işlət.
- Həqiqətin bir istiqaməti. Figma kimi dizayn alətlərində mode-ları (light, dark, brend) olan variable-lar var. Mənbənin dizayn faylı, yoxsa repozitoriya olduğunu qərara al və sinxronizasiyanı bir istiqamətdə apar, yoxsa ikisi bir-birindən uzaqlaşacaq.
When the same product ships on the web, iOS and Android, tokens need one source of truth: JSON files in the DTCG format, edited in pull requests or exported from the design tool. A build step resolves references, renames tokens, converts units and colors, and generates code for each platform:
tokens/*.tokens.json (DTCG)
|
v
Style Dictionary
|
+--> web/tokens.css, web/tokens.js, web/tokens.d.ts
+--> ios/Tokens.swift
+--> android/colors.xml, android/Tokens.ktStyle Dictionary is the most common build tool. For each platform it applies a transform group (renaming to kebab or Pascal case, converting sizes to rem, formatting colors) and writes files in formats such as css/variables, javascript/es6, typescript/es6-declarations, ios-swift/class.swift, android/resources and compose/object. Since version 4 it supports the DTCG format; its docs say full support for 2025.10 is still in progress in version 5.
import StyleDictionary from "style-dictionary";
const sd = new StyleDictionary({
source: ["tokens/**/*.tokens.json"],
platforms: {
css: {
transformGroup: "css",
buildPath: "dist/web/",
files: [
{
destination: "tokens.css",
format: "css/variables",
options: { outputReferences: true },
},
],
},
js: {
transformGroup: "js",
buildPath: "dist/web/",
files: [{ destination: "tokens.js", format: "javascript/es6" }],
},
},
});
await sd.buildAllPlatforms();outputReferences: true keeps references in the CSS (--color-action-bg: var(--color-blue-600)), which makes the output readable and the tiers visible in DevTools. Without it every token is written as a literal value, which avoids the "alias resolved too early" trap when themes override primitives on nested elements.
Rules that keep a pipeline healthy
- Generated files are build output. Nobody edits
tokens.cssby hand; reviews happen on the JSON diff. - Typed access. Generated TypeScript declarations give autocompletion, and a removed token becomes a compile error instead of a silent
unset. - Version the package. Publish tokens as a versioned package with semver: renaming or removing a token is a breaking change. A changed value is not breaking in the API sense, but it changes pixels, so run visual regression tests before release.
- One direction of truth. Design tools such as Figma have variables with modes (light, dark, brand). Decide whether the design file or the repository is the source, and sync in one direction, or the two drift apart.
Çoxbrendli theming: runtime, yoxsa build vaxtı
Platformadakı multi-brand-design-system system design məsələsi bir kod bazası və bir komponent kitabxanası tələb edir ki, bir neçə mağaza brendinə xidmət etsin; hər brendin öz görünüşü, şriftləri, funksiyaları və bazarları var. Token-lər yalnız görünüşü həll edir və məqsəd də elə budur: komponentlər brenddən xəbərsiz qalır, brend isə token dəyərlərinin dəstidir.
[data-brand="north"] {
--font-family-brand: "Inter", system-ui, sans-serif;
--radius-control: 4px;
--color-action-bg: #0b5fff;
--color-action-fg: #ffffff;
}
[data-brand="south"] {
--font-family-brand: "Fraunces", Georgia, serif;
--radius-control: 999px;
--color-action-bg: #c2410c;
--color-action-fg: #ffffff;
}
[data-brand="south"][data-theme="dark"] {
--color-action-bg: #fb923c;
--color-action-fg: #0d1117;
}Temalar matris yaradır: brend × rejim (bəzən × sıxlıq və ya yüksək kontrast), və hər xana ayrıca palitradır. Son qaydaya diqqət et: #fb923c üzərində ağ mətn cəmi 2.26:1 verir, ona görə tünd tema mətn rəngini də dəyişir.
Funksiyalar və bazarlar token deyil. Feature flag-lər, dillər, valyutalar və ödəniş üsulları məlumatda saxlanan brend konfiqurasiyasına aiddir; onları token dəstinə qatmaq hər ikisini dəyişməyi çətinləşdirir. Şriftlər qismən token-dir (--font-family-brand), qismən isə yükləmə məsələsi: hər mağaza yalnız öz şrift fayllarını yükləməlidir, yoxsa hər ziyarətçi bütün brendlərin şriftlərini endirəcək.
Runtime, yoxsa build vaxtı
| Runtime: CSS custom property-lər | Build vaxtı: dəyərlər hər brend üçün kompilyasiya olunur | |
|---|---|---|
| Dəyişmə | Dərhal: atributu dəyiş (tünd rejim düyməsi, CMS-də brendə önbaxış) | Başqa bundle və səhifənin yenilənməsi lazımdır |
| Göndərilən CSS | Bütün temalar bir stylesheet-də (adətən bir neçə KB dəyişən) | Yalnız brendin dəyərləri |
| İç-içə tema | Temalı alt ağac bir atributdur | Çətindir |
| Məhdudiyyətlər | var() media query şərtlərində işləmir; dəyişmə bütün ağacı yenidən stilləyir | N build, test və deploy olunmalı N artefakt |
Geniş yayılmış hibrid: hər mağaza öz brendinin generasiya olunmuş tokens.css-ini yükləyir (build vaxtı), açıq/tünd rejim isə həmin brendin içində runtime atributu kimi qalır. JS tema obyektinin render zamanı stil yaratdığı runtime CSS-in-JS theming hər render-də JavaScript xərci yaradır və server komponentləri ilə pis uyuşur; CSS custom property-lər isə temanı JavaScript-dən tamamilə çıxarır.
The platform's system design problem multi-brand-design-system asks for one codebase and one component library that serve several store brands, each with its own look, fonts, features and markets. Tokens solve only the look, and that is the point: components stay brand-agnostic, and a brand is a set of token values.
[data-brand="north"] {
--font-family-brand: "Inter", system-ui, sans-serif;
--radius-control: 4px;
--color-action-bg: #0b5fff;
--color-action-fg: #ffffff;
}
[data-brand="south"] {
--font-family-brand: "Fraunces", Georgia, serif;
--radius-control: 999px;
--color-action-bg: #c2410c;
--color-action-fg: #ffffff;
}
[data-brand="south"][data-theme="dark"] {
--color-action-bg: #fb923c;
--color-action-fg: #0d1117;
}Themes form a matrix, brand × mode (sometimes × density or high contrast), and every cell is a palette of its own. Note the last rule: white text on #fb923c is only 2.26:1, so the dark theme changes the foreground too.
Features and markets are not tokens. Feature flags, locales, currencies and payment methods belong to a brand configuration in data; mixing them into the token set makes both harder to change. Fonts are partly a token (--font-family-brand) and partly loading: each store should load only its own font files, otherwise every visitor downloads every brand's fonts.
Runtime or build time
| Runtime: CSS custom properties | Build time: values compiled per brand | |
|---|---|---|
| Switching | Instant: change an attribute (dark mode toggle, brand preview in a CMS) | Needs a different bundle and a reload |
| Shipped CSS | All themes in one stylesheet (usually a few KB of variables) | Only the brand's values |
| Nesting | A themed subtree is one attribute | Hard |
| Limits | var() does not work in media query conditions; a switch restyles the whole tree | N builds, N artifacts to test and deploy |
A common hybrid: each store loads its brand's generated tokens.css (build time), and light/dark stays a runtime attribute inside that brand. Runtime CSS-in-JS theming, where a JS theme object generates styles during render, costs JavaScript on every render and fits poorly with server components; CSS custom properties keep the theme out of JavaScript.
Kontrast yoxlamaları və token-lərin idarə olunması
Hər tema üçün kontrast. WCAG 2.2-nin AA səviyyəsi mətn üçün ən azı 4.5:1 (1.4.3), iri mətn üçün (ən azı 18 punkt və ya qalın 14 punkt) 3:1 kontrast tələb edir. UI komponentləri və mənalı qrafika, o cümlədən fokus indikatorları qonşu rənglərə qarşı 3:1 tələb edir (1.4.11). Bu nisbətlər həddir və yuvarlaqlaşdırılmır: 4.49:1 keçmir. Token-lər məlumat olduğu üçün CI həqiqətən birlikdə işlənən cütləri hər brenddə və hər rejimdə yoxlaya bilər:
function luminance(hex) {
const [r, g, b] = [1, 3, 5].map((i) => {
const c = parseInt(hex.slice(i, i + 2), 16) / 255;
return c <= 0.04045 ? c / 12.92 : ((c + 0.055) / 1.055) ** 2.4;
});
return 0.2126 * r + 0.7152 * g + 0.0722 * b;
}
function contrast(a, b) {
const [hi, lo] = [luminance(a), luminance(b)].sort((x, y) => y - x);
return (hi + 0.05) / (lo + 0.05);
}
console.log(contrast("#ffffff", "#0b5fff").toFixed(2)); // "5.13"
console.log(contrast("#0b5fff", "#0d1117").toFixed(2)); // "3.69"Cütləri token-lərin yanında elan et (bg-surface üzərində text-default, action-bg üzərində action-fg, bg-surface üzərində border-focus) və brend × rejim matrisinin hər hansı xanası həddən aşağı düşəndə build-i dayandır.
İdarəetmə. Token-lər dizayn sisteminin public API-sidir, ona görə istənilən API kimi diqqət tələb edir:
- Əlavə etmək. Yeni semantik token-ə birdən çox yerdə işlənən real rol lazımdır. Yoxdursa, mövcud token-dən istifadə et və ya komponent token-i əlavə et.
- Köhnəlmiş elan etmək. Token-i işarələ (DTCG formatında
$deprecatedvar:truevə ya izahat sətri), ən azı bir major versiya boyunca onu əvəzedicisinin alias-ı kimi saxla, build-də və ya linter-də xəbərdarlıq ver, istifadə yerlərinin adını dəyişən codemod hazırla və növbəti major versiyada sil. - Məsuliyyət. Yeni token-ləri kimsə təsdiqləyir, changelog hər dəyişikliyi qeyd edir, token silinməzdən əvvəl repozitoriyalar üzrə axtarış onu hələ kimin işlətdiyini göstərir.
- Sənədləşmə. Hər token-in hər brend və rejimdəki dəyərini göstərən arayış səhifəsini generasiya et ki, heç kim JSON oxumağa məcbur qalmasın.
Contrast per theme. WCAG 2.2 level AA requires a contrast ratio of at least 4.5:1 for text (1.4.3) and 3:1 for large text (at least 18 point, or 14 point bold). UI components and meaningful graphics, including focus indicators, need 3:1 against adjacent colors (1.4.11). The ratios are thresholds and are not rounded: 4.49:1 fails. Because tokens are data, CI can check the pairs that are actually used together, in every brand and mode:
function luminance(hex) {
const [r, g, b] = [1, 3, 5].map((i) => {
const c = parseInt(hex.slice(i, i + 2), 16) / 255;
return c <= 0.04045 ? c / 12.92 : ((c + 0.055) / 1.055) ** 2.4;
});
return 0.2126 * r + 0.7152 * g + 0.0722 * b;
}
function contrast(a, b) {
const [hi, lo] = [luminance(a), luminance(b)].sort((x, y) => y - x);
return (hi + 0.05) / (lo + 0.05);
}
console.log(contrast("#ffffff", "#0b5fff").toFixed(2)); // "5.13"
console.log(contrast("#0b5fff", "#0d1117").toFixed(2)); // "3.69"Declare the pairs next to the tokens (text-default on bg-surface, action-fg on action-bg, border-focus on bg-surface) and fail the build when a cell of the brand × mode matrix drops below its threshold.
Governance. Tokens are the public API of a design system, so they need the same care as any API:
- Adding. A new semantic token needs a real role used in more than one place. Otherwise reuse an existing token or add a component token.
- Deprecating. Mark the token (the DTCG format has
$deprecated:trueor an explanation string), keep it as an alias of its replacement for at least one major version, warn in the build or the linter, ship a codemod that renames usages, and remove it in the next major. - Ownership. Someone approves new tokens, a changelog lists every change, and a search across repositories shows who still uses a token before it is removed.
- Documentation. Generate a reference page that shows each token's value in every brand and mode, so nobody has to read the JSON.
Müsahibə üçün məsləhətlər
30 saniyəlik tərif. "Design token adı olan dizayn qərarıdır: rəng, boşluq pilləsi və ya şrift ölçüsü. O, məlumat kimi saxlanılır və hər platforma üçün koda generasiya olunur. Primitiv token-lər xam palitranı saxlayır, semantik token-lər dəyərlərə rol verir, komponentlər isə yalnız semantik token-ləri oxuyur. Beləliklə tema və ya brend komponentlərə toxunmadan dəyərləri dəyişir." Ardınca :root-dakı defoltları və [data-theme="dark"] üstələməsini yaz.
Gözlənilən suallar
- Tünd rejimi necə qurardın? Custom property kimi semantik token-lər, defolt seçim kimi
prefers-color-scheme,<html>-dədata-themekimi saxlanan istifadəçi seçimi, native UI üçüncolor-schemevə ilk paint düzgün olsun deyə<head>-də inline skript (SSR-da isə cookie). - Primitiv və semantik token fərqi? Dəyər və rol.
blue-600oxuyan komponentin tünd temanı niyə sındırdığını izah et. - Bir neçə brend üçün bir komponent kitabxanası? multi-brand-design-system məsələsinə istinad et: brenddən xəbərsiz komponentlər, brend × rejim token matrisi, funksiyalar və bazarlar üçün brend konfiqurasiyası, hər brend üçün ayrıca yüklənən şriftlər, runtime və ya build vaxtı seçimin və onun trade-off-ları.
- Token-lər iOS və Android-ə necə çatır? Bir DTCG mənbəyi, Style Dictionary kimi build addımı, generasiya olunan platforma faylları, versiyalanan paket.
--xsəhv dəyər saxlayandavar(--x, red)nə edir? Fallback işləmir; xassəunsetolur.
Bal itirdən səhvlər
- Token-ləri dəyərə görə adlandırmaq (rol kimi
color-blue) və ya komponentlərə primitiv işlətməyə icazə vermək. - Temanı
useEffect-də tətbiq edib yanıb-sönməni "kiçik qüsur" adlandırmaq. color-scheme-i unutmaq, nəticədə form kontrolları açıq qalır.- Kontrastı bir dəfə açıq tema üçün yoxlayıb bütün brend və rejimlərin keçdiyini fərz etmək.
- Feature flag-ləri və bazarları theming-in bir hissəsi saymaq.
Senior səviyyəni göstərən məqamlar
Token-lərin ətrafındakı sistemdən danış: pipeline və onun çıxışları, tipli çıxış, semver və codemod-larla köhnəltmə, CI-da matrisin hər xanası üçün kontrast yoxlaması, vizual reqressiya testləri və nəyin build vaxtı qərara alındığını, nəyin runtime-da dəyişə bildiyini aydın ifadə etmək.
A 30-second definition. "A design token is a named design decision, such as a color, spacing step or font size, stored as data and generated into code for each platform. Primitive tokens hold the raw palette, semantic tokens give values a role, and components read only semantic tokens, so a theme or brand changes values without touching components." Then sketch :root defaults and a [data-theme="dark"] override.
Questions you are likely to get
- How would you implement dark mode? Semantic tokens as custom properties,
prefers-color-schemeas the default, a stored user override asdata-themeon<html>,color-schemefor native UI, and an inline script in<head>(or a cookie with SSR) so the first paint is right. - Primitive vs semantic tokens? Value vs role. Explain why a component that reads
blue-600breaks the dark theme. - One component library for several brands? Point to the multi-brand-design-system problem: brand-agnostic components, a brand × mode token matrix, brand config for features and markets, fonts loaded per brand, and your runtime or build-time choice with its trade-offs.
- How do tokens reach iOS and Android? One DTCG source, a build step such as Style Dictionary, generated platform files, a versioned package.
- What happens with
var(--x, red)when--xholds an invalid value? The fallback is not used; the property becomesunset.
Mistakes that cost points
- Naming tokens by value (
color-blueas a role) or letting components use primitives. - Applying the theme in
useEffectand calling the flash "a small glitch". - Forgetting
color-scheme, so form controls stay light. - Checking contrast once for the light theme and assuming every brand and mode passes.
- Treating feature flags and markets as part of theming.
Senior signal
Talk about the system around the tokens: the pipeline and its outputs, typed access, semver and deprecation with codemods, contrast checks per matrix cell in CI, visual regression tests, and a clear statement of what is decided at build time and what stays switchable at runtime.
Design token-ləri və theming-i review edərkən nəyi yoxlamalı
Bu siyahını özün yazmadığın stil və tema kodunu review edəndə işlət: komanda yoldaşının, kitabxananın və ya AI assistentin kodunu. Token səhvləri səssizdir: açıq tema qaydasında görünür, başqa tema isə sınır.
- Komponent stilləri yalnız semantik token-ləri oxuyurmu? Diff-də xam dəyərləri (
#fff,rgba(…)) və--color-blue-600kimi primitivləri axtar: onların hər biri qalan temalara məhəl qoymur. Inline SVG-lərdəki rəngləri (currentColorişlət) və JavaScript-dəki qrafik rənglərini də yoxla. var()-ın içindəki hər ad mövcuddurmu?var(--color-bg-surfce)kimi yazı səhvi heç nə log etmir və xassəniunsetedir; fallback olanda isəvar(--color-bg-surfce, #fff)hər temada səssizcə ağ rəng çəkir.getComputedStyle(el).getPropertyValue("--name")təyin olunmamış token üçün""qaytarır.- Dəyişiklik hər temada, kontrastla birlikdə yoxlanıbmı?
data-theme-i dəyiş və dəyişən hər ekrana bax. Mətnə 4.5:1 lazımdır (iri mətnə və fokus halqalarına 3:1), rəng isə bir temada keçib başqasında keçməyə bilər:#0b5fffağ fonda 5.13:1,#0d1117üzərində isə cəmi 3.69:1 verir. - Alias yalnız
:root-da elan olunub, onun istinad etdiyi token-i isə iç-içə elementdəki tema dəyişirmi? Custom property-nin içindəkivar()elan olunduğu elementdə həll olunur, nəsil elementlər isə nəticəni miras alır. Ona görə:root-dakı--button-bg: var(--color-accent)elanı--color-accent-i dəyişən[data-theme]bölməsinə məhəl qoymur; alias-ı:root, [data-theme]üzərində elan et. - Tünd rejim
color-schemetəyin edirmi və saxlanmış seçimi ilk paint-dən əvvəl tətbiq edirmi?color-schemeolmadan form kontrolları və scrollbar-lar açıq qalır.useEffect-də tətbiq olunan seçim əvvəlcə defolt temanı göstərir, sonra dəyişir; onun yeri<head>-dəki inline skriptdir (server render-də isə cookie). Tünd seçim saxlanmış halda səhifəni yenilə və ilk kadra bax. - Yeni token-lər rola görə adlandırılıb və API kimi idarə olunurmu?
color-redyox,color-text-danger. Token-in adını dəyişmək və ya onu silmək breaking change-dir: köhnə adı növbəti major versiyaya qədər alias kimi saxla.tokens.csskimi generasiya olunan fayllar heç vaxt əl ilə redaktə olunmur.
Use this list for style and theme code you did not write: a teammate's, a library's or an AI assistant's. Token mistakes are silent: the light theme looks fine, and another theme breaks.
- Do component styles read only semantic tokens? Search the diff for raw values (
#fff,rgba(…)) and primitives such as--color-blue-600: each one ignores the other themes. Check inline SVG fills (usecurrentColor) and chart colors in JavaScript too. - Does every name inside
var()exist? A typo likevar(--color-bg-surfce)logs nothing and makes the propertyunset; with a fallback,var(--color-bg-surfce, #fff)silently paints white in every theme.getComputedStyle(el).getPropertyValue("--name")returns""for an undefined token. - Was the change checked in every theme, contrast included? Switch
data-themeand look at each changed screen. Text needs 4.5:1 (large text and focus rings 3:1), and a color can pass in one theme and fail in another:#0b5fffgives 5.13:1 on white but 3.69:1 on#0d1117. - Is an alias declared only on
:rootwhile a nested theme changes what it points to?var()inside a custom property resolves where it is declared; descendants inherit the result. So--button-bg: var(--color-accent)on:rootignores a[data-theme]section that changes--color-accent; declare the alias on:root, [data-theme]. - Does dark mode set
color-schemeand apply the saved choice before the first paint? Withoutcolor-scheme, form controls and scrollbars stay light. Applied inuseEffect, the choice flashes the default theme first; it belongs in an inline<head>script (or a cookie with server rendering). Reload with dark saved and watch the first frame. - Are new tokens named by role and treated as an API?
color-text-danger, notcolor-red. Renaming or removing a token is breaking: keep the old name as an alias until the next major version. Generated files such astokens.cssare never edited by hand.
Özünü yoxla
Təcrübədə sına
Bu mövzudan istifadə edən praktiki işlər.