Mở đầu — vì sao bài này quan trọng
Hãy hình dung bạn vừa hoàn thành một bảng màu tuyệt đẹp trong Figma: 12 sắc độ xanh dương, 12 sắc độ xám, các token semantic như color.primary, color.surface, color.text.muted... Bạn tự hào giao cho đội kỹ thuật. Ba tuần sau, marketing yêu cầu đổi màu chủ đạo từ xanh dương sang xanh lá. Bạn sửa trong Figma trong 5 phút. Nhưng phía code, một bạn lập trình viên phải ngồi dò tay từng file CSS, đổi mã hex ở 47 chỗ, và vẫn bỏ sót 3 chỗ. Kết quả: nút "Đăng ký" trên trang thanh toán vẫn màu xanh dương cũ, lệch hẳn với phần còn lại của sản phẩm.
Đây chính là "vực ngăn cách" (the gap) giữa thiết kế và code mà cả ngành đang cố lấp. Ở Bài 14 bạn đã học Design Tokens là gì (foundation layer), Bài 15 học Figma Variables để tạo modes và theming ngay trong Figma. Nhưng có một sự thật phũ phàng: Figma Variables, tính đến thời điểm hiện tại, vẫn chưa hỗ trợ tốt việc đồng bộ hai chiều (sync) với codebase. Bạn không thể trỏ thẳng Variables của Figma vào file CSS/JSON trong Git một cách tự nhiên qua công cụ native.
Đó là lý do Tokens Studio (tên cũ: Figma Tokens) ra đời — một plugin đóng vai trò cây cầu nối giữa thế giới thiết kế và thế giới code. Bài học này dạy bạn cách dùng cây cầu đó để token của bạn chỉ cần định nghĩa một lần, tồn tại như một nguồn sự thật duy nhất (single source of truth), và tự động chảy sang cả Figma lẫn code. Đây là kỹ năng phân biệt một UI Designer "vẽ đẹp" với một Design Systems Engineer thực thụ.
Khái niệm cốt lõi
Vấn đề gốc rễ: hai nguồn sự thật
Trong quy trình truyền thống, token màu/spacing/typography tồn tại ở hai nơi riêng biệt và không biết đến sự tồn tại của nhau:
- Trong Figma: dưới dạng Styles hoặc Variables — designer chỉnh sửa.
- Trong code: dưới dạng biến CSS, file
tokens.json, hoặc Tailwind config — developer chỉnh sửa.
Tokens Studio làm gì
Tokens Studio là plugin cho Figma, cho phép bạn:
- Tạo và quản lý token phong phú hơn Figma Variables native rất nhiều — bao gồm cả các loại token mà Variables chưa hỗ trợ tốt như typography tổng hợp (font family + size + line height + letter spacing trong một token), box-shadow, border, và composition token.
- Token tham chiếu (aliasing/references): một token có thể trỏ vào token khác. Ví dụ
color.button.primary.bg = {color.brand.500}. Đây là nền tảng của kiến trúc token 3 lớp (primitive → semantic → component). - Áp dụng token lên layer trong Figma bằng plugin, thay vì gán Style thủ công.
- Xuất token ra file JSON theo chuẩn W3C Design Tokens Format (DTCG) — định dạng mà giới developer và các công cụ khác đều đọc được.
- Đồng bộ với Git (GitHub, GitLab, Azure DevOps, Bitbucket) — đây là tính năng "vàng": token của bạn được lưu thẳng vào repo dưới dạng file JSON, tạo Pull Request, và developer pull về.
Kiến trúc Token Sets và Themes
Đây là điểm khiến Tokens Studio mạnh hơn Figma Variables. Trong Tokens Studio bạn tổ chức token thành các Token Set — nghĩ như các "lớp" có thể bật/tắt độc lập:
core(hoặcglobal): các primitive token — bảng màu thô, thang spacing, thang font size. Ít khi đổi.semantic: token có ý nghĩa —color.text.primary,color.surface.raised, tham chiếu vàocore.components: token cấp component —button.padding,card.radius, tham chiếu vàosemantic.- Các set riêng cho theme:
light,dark,brand-a,brand-b...
core + semantic-light + components; Theme "Dark" = core + semantic-dark + components. Chỉ lớp semantic thay đổi giữa light/dark, còn primitive và component giữ nguyên. Đây chính là cách triển khai dark mode có kỷ luật mà Bài 30 nhắc tới, nhưng ở tầng token.Chuẩn định dạng: DTCG (W3C Design Tokens)
Token xuất ra trông như thế này:
{
"color": {
"brand": {
"500": { "$value": "#2563EB", "$type": "color" }
},
"button": {
"primary": {
"bg": { "$value": "{color.brand.500}", "$type": "color" }
}
}
}
}
Dấu ngoặc nhọn {color.brand.500} chính là reference. Khi bạn đổi brand.500 từ xanh dương sang xanh lá, mọi token trỏ vào nó tự động cập nhật. Đây là "phép màu" khiến câu chuyện đổi màu ở đầu bài trở thành thao tác 5 phút cho cả Figma lẫn code.
Style Dictionary — mảnh ghép cuối
File JSON tự nó chưa dùng được trong code. Bạn cần công cụ transform nó thành CSS variables, SCSS, Tailwind config, iOS Swift, Android XML... Công cụ phổ biến nhất là Style Dictionary (của Amazon). Luồng đầy đủ: Tokens Studio → JSON trong Git → Style Dictionary chạy trong CI → sinh ra file platform-specific → developer dùng.
Tình huống thực tế
Ví dụ 1: Tiki và bài toán nhất quán màu qua nhiều team
Giả định một sàn TMĐT như Tiki có 6 team frontend làm 6 mảng khác nhau: trang chủ, tìm kiếm, chi tiết sản phẩm, giỏ hàng, thanh toán, TikiNOW. Trước khi có hệ thống token đồng bộ, mỗi team tự copy mã màu vào code của mình. Khi thương hiệu quyết định làm sáng màu xanh chủ đạo lên 8% để tăng độ tương phản (đạt chuẩn WCAG AA), việc rollout mất 3 tuần vì phải phối hợp 6 team, và trong lúc đó người dùng thấy hai sắc xanh khác nhau tùy trang họ đang ở.
Sau khi áp dụng Tokens Studio: designer đổi giá trị color.brand.primary trong một Token Set, tạo Pull Request vào repo design-tokens. CI chạy Style Dictionary sinh ra tokens.css mới, publish thành npm package @tiki/design-tokens@2.4.0. Cả 6 team chỉ cần bump version package. Thời gian rollout: 2 ngày, và tại mọi thời điểm mọi trang đều dùng cùng một màu.
Bài học: Giá trị lớn nhất của token sync không phải "đẹp hơn" mà là tốc độ và tính nhất quán khi thay đổi ở quy mô lớn. Càng nhiều team, giá trị càng cao.
Ví dụ 2: Startup fintech 8 người — chọn quy trình vừa sức
Một startup fintech ở TP.HCM, đội ngũ 8 người trong đó chỉ có 1 designer và 3 dev. Bạn designer này ban đầu định dựng luôn CI/CD tự động chạy Style Dictionary, webhook, versioning semantic... nghe rất "chuẩn ngành". Nhưng thực tế với quy mô đó, việc dựng pipeline mất cả tuần và không ai đủ thời gian bảo trì.
Giải pháp thực dụng: designer dùng Tokens Studio, nhưng thay vì sync Git tự động, mỗi sprint chỉ export JSON một lần và gửi cho dev qua một PR thủ công nhỏ. Dev dùng một script Style Dictionary tối giản chạy tay khi cần. Không webhook, không CI phức tạp.
Bài học: Đừng "over-engineer". Mức độ tự động hóa của quy trình token phải tương xứng với quy mô đội. Với đội nhỏ, "export tay mỗi sprint" đã lấp được 90% cái gap mà chỉ tốn 10% công sức. Bạn nâng cấp lên Git sync tự động khi nỗi đau copy tay đủ lớn.
Ví dụ 3: Agency làm white-label cho nhiều khách hàng
Một agency ở Singapore xây một sản phẩm SaaS bán cho nhiều ngân hàng, mỗi ngân hàng muốn thương hiệu riêng (màu, radius, font) nhưng dùng chung bộ component. Đây đúng là kịch bản Tokens Studio tỏa sáng: họ giữ nguyên các set core và components, và tạo một set semantic riêng cho mỗi khách hàng — brand-vcb, brand-acb, brand-tcb. Mỗi Theme trong Tokens Studio là một khách hàng.
Khi ký hợp đồng khách mới, họ nhân bản một set brand, đổi khoảng 20 giá trị semantic, export ra một file JSON riêng, và Style Dictionary sinh ra một theme CSS mới. Toàn bộ quá trình "thêm một thương hiệu" giảm từ 2 tuần xuống nửa ngày.
Bài học: Kiến trúc Token Set + Theme cho phép multi-brand/white-label mà không nhân bản component. Chỉ lớp semantic thay đổi giữa các brand; primitive và component dùng chung.
Hướng dẫn từng bước
Dưới đây là quy trình dựng token sync từ đầu với Tokens Studio.
Bước 1 — Cài plugin và lên kiến trúc set. Cài "Tokens Studio for Figma" từ Community. Trước khi gõ token đầu tiên, hãy vẽ ra giấy 3 lớp: core (primitive), semantic, components. Đừng nhét mọi thứ vào một set.
Bước 2 — Tạo primitive token ở set core. Nhập bảng màu thô (color.blue.50 → color.blue.900), thang spacing (space.1 = 4, space.2 = 8...), thang font size. Đây là các giá trị "cứng", chỉ chứa số/hex, không tham chiếu ai.
Bước 3 — Tạo semantic token tham chiếu vào core. Ví dụ color.text.primary có value {color.gray.900}, color.surface.default = {color.white}. Gõ dấu { trong ô value để Tokens Studio gợi ý autocomplete. Nếu làm dark mode, tạo set semantic-dark với cùng tên token nhưng trỏ vào giá trị tối.
Bước 4 — Tạo Theme. Vào tab Themes, tạo "Light" (bật core + semantic-light + components) và "Dark" (bật core + semantic-dark + components). Đặt các set là "Source" hay "Enabled" cho đúng — Source nghĩa là dùng để tham chiếu nhưng không xuất token trực tiếp.
Bước 5 — Áp token lên design. Chọn layer trong Figma, dùng panel Tokens Studio để gán token (ví dụ chọn một khung rồi click token color.surface.default). Từ giờ layer đó "sống" theo token.
Bước 6 — Kết nối Git. Vào Settings → Sync → chọn GitHub. Nhập Personal Access Token, tên repo, branch, và đường dẫn file (ví dụ tokens/). Push lần đầu để tạo file JSON trong repo.
Bước 7 — Dựng Style Dictionary phía code. Trong repo, cài style-dictionary, viết file config trỏ vào JSON vừa push, định nghĩa platform output (CSS variables chẳng hạn). Chạy build để sinh tokens.css.
Bước 8 — Đóng vòng lặp. Mỗi lần designer đổi token → push tạo PR → CI chạy Style Dictionary → dev review & merge. Từ đây thay đổi token là một quy trình có kiểm soát, có lịch sử Git, có review.
Lỗi thường gặp & mẹo
Lỗi 1 — Nhét tất cả vào một Token Set khổng lồ. Không phân lớp primitive/semantic/component khiến bạn không thể làm theming và reference rối như tơ vò. Mẹo: luôn dựng tối thiểu 2 lớp (primitive + semantic) ngay từ đầu, kể cả dự án nhỏ.
Lỗi 2 — Đặt tên token theo giá trị thay vì ý nghĩa. color.blue ở lớp semantic là sai — khi brand đổi sang xanh lá, token tên blue mà giá trị xanh lá sẽ gây bối rối. Mẹo: lớp semantic đặt tên theo vai trò (primary, surface, danger), không theo màu. (Bài 34 về naming conventions bàn kỹ hơn.)
Lỗi 3 — Hardcode giá trị ở lớp semantic thay vì reference. Nếu color.text.primary = #111111 (số cứng) thay vì {color.gray.900}, bạn mất toàn bộ lợi ích cascade. Mẹo: semantic và component luôn phải là reference, không bao giờ là giá trị thô.
Lỗi 4 — Quên rằng JSON chưa phải là code dùng được. Nhiều bạn tưởng push JSON lên Git là xong. Không — thiếu Style Dictionary (hoặc công cụ tương đương) thì dev vẫn không có biến CSS để dùng. Mẹo: thống nhất với dev về công cụ transform trước khi bắt đầu.
Lỗi 5 — Sync hai chiều gây conflict. Nếu cả designer (qua plugin) và dev (sửa tay JSON) cùng ghi vào một file, bạn sẽ gặp merge conflict khó chịu. Mẹo: quy ước rõ ràng — Figma/Tokens Studio là nguồn ghi duy nhất cho token; dev chỉ đọc, không sửa tay file token.
Mẹo bonus: Dùng tính năng "Token Set Order" và branch riêng cho mỗi thay đổi lớn. Và luôn bật DTCG format trong Settings để tương thích chuẩn W3C — tránh dùng định dạng legacy đã lỗi thời.
Bài tập thực hành
- Dựng kiến trúc 3 lớp. Cài Tokens Studio, tạo 3 set:
core,semantic,components. Ởcorenhập tối thiểu một bảng màu 9 sắc độ và một thang spacing 6 mức.
- Tạo reference. Ở
semantic, tạo 5 token (color.text.primary,color.surface.default,color.border.subtle,color.action.primary,color.action.danger), mỗi cái phải tham chiếu vào một token ởcore. Kiểm tra: đổi một giá trịcorevà xác nhận token semantic tự cập nhật.
- Làm dark mode bằng Theme. Tạo
semantic-darkvới cùng tên token nhưng giá trị tối. Tạo 2 Theme Light/Dark. Chuyển qua lại và quan sát design đổi theo.
- Export và đọc JSON. Export token ra JSON, mở file và tự giải thích: đâu là
$value, đâu là$type, đâu là reference{...}. Viết 3 câu mô tả điều gì xảy ra với JSON khi bạn đổi một primitive.
- (Nâng cao) Tạo một repo GitHub cá nhân, kết nối Git sync trong Tokens Studio, push token, rồi cài Style Dictionary sinh ra file
tokens.css. Mở file CSS xem các biến--color-...đã ra đúng chưa.
Tóm tắt
- Figma Variables native chưa sync tốt với code — Tokens Studio là cây cầu nối lấp cái gap đó, biến token thành một nguồn sự thật duy nhất.
- Kiến trúc Token Set 3 lớp (primitive → semantic → component) cộng với reference (
{...}) là nền tảng giúp một thay đổi cascade tự động khắp hệ thống. - Theme trong Tokens Studio giải quyết dark mode và multi-brand một cách có kỷ luật: chỉ lớp semantic thay đổi, primitive và component dùng chung.
- Luồng đầy đủ: Tokens Studio → JSON chuẩn DTCG trong Git → Style Dictionary transform → file platform-specific → dev dùng. JSON tự nó chưa dùng được, phải có công cụ transform.
- Nguyên tắc vàng: semantic/component luôn là reference, không bao giờ hardcode; và Figma là nguồn ghi duy nhất, dev chỉ đọc.
- Mức độ tự động hóa phải tương xứng quy mô đội: đội nhỏ export tay mỗi sprint là đủ; đội lớn nhiều team mới cần CI/CD đầy đủ. Đừng over-engineer.