figma — 1thay single source of truth
file: OAinJNCk0DZ1p1R1xyPfvx · linked files: 1thay.md, design-tokens.md, astro.md, storybook.md, CLAUDE.md
overview
figma là single source of truth cho toàn bộ design tokens của 1thay. mọi thay đổi token bắt đầu từ figma, sau đó sync xuống code (src/tokens/tokens.css). components được thiết kế trong figma, build trong storybook, và document trong astro.
nguyên tắc: figma first — token thay đổi trong figma trước, code mirror theo sau.
file info
| property | value |
|---|---|
| name | 1thay |
| file key | OAinJNCk0DZ1p1R1xyPfvx |
| url | https://www.figma.com/design/OAinJNCk0DZ1p1R1xyPfvx/1thay |
| plan | tayquen (team) |
| editor type | design |
| role | single source of truth |
architecture
theo mô hình multi-file từ figma__sample.md:
[ 01. Foundations & Tokens ] ← file này (1thay)
│
▼
[ 02. Core Components ] ← xuất bản lên team library
│
▼
[ 03. Product Files ] ← file dự án thực tế (dashboard, landing page...)
file 1thay hiện tại là File 01: Foundations & Tokens — chứa variables, text styles, effect styles và component documentation. khi mở rộng sẽ tách File 02: Core Components riêng, nhận variables từ file này qua team library.
page structure
tổ chức theo chuẩn từ figma__sample.md:
--- 📌 START HERE ---
◆ Cover hero + brand swatches + publish instructions
📖 Readme / Documentation hướng dẫn sử dụng file (planned)
--- 📐 FOUNDATIONS ---
◆ Colors blue-reputa, red-premier, neutral-gray swatches
◆ Typography 4 font families + 12 type scale specimens
◆ Spacing spacing bars, radius, shadows, opacity, z-index
◆ Iconography lucide + carbon icon reference
--- ⚡ COMPONENTS (grouped) ---
Feedback / Badge 5 variants (neutral, brand, success, warning, error)
Feedback / Toast 3 variants (success, error, info)
Feedback / Banner 4 variants (info, success, warning, error)
Navigation / Breadcrumbs hierarchy chain with separator
Navigation / Tab horizontal tab bar with active indicator
Data / Table header + rows with border
Data / Chart chart container with title + bar chart
Layout / Divider horizontal, vertical, dashed
Content / Tag default, brand, removable
--- 🏗️ UTILITIES ---
🧪 Playground / Sandbox thử nghiệm component mới trước khi publish (planned)
🗑️ Archive component cũ đã deprecated (planned)
page naming convention
theo chuẩn từ sample:
| prefix | mục đích | ví dụ |
|---|---|---|
◆ |
trang documentation/foundations | ◆ Cover, ◆ Colors |
📖 |
hướng dẫn sử dụng | 📖 Readme |
🧪 |
thử nghiệm | 🧪 Playground |
🗑️ |
lưu trữ component cũ | 🗑️ Archive |
Group / Name |
component page (grouped) | Feedback / Badge |
component naming
theo chuẩn Sentence case từ sample:
Group / Subgroup / Component Name
Feedback / Alert / Toast
Form / Input / Text Field
component phụ không publish dùng prefix _ hoặc .:
_Row-item
.Master-picker
variable collections
| # | collection | modes | count | scope |
|---|---|---|---|---|
| 1 | Primitives | Value | 22 | FRAME_FILL, SHAPE_FILL, TEXT_FILL, STROKE_COLOR |
| 2 | Color | Light, Dark | 16 | varies by semantic |
| 3 | Spacing | Value | 7 | GAP |
| 4 | Radius | Value | 6 | CORNER_RADIUS |
| 5 | Size | Value | 10 | WIDTH_HEIGHT |
| 6 | Opacity | Value | 4 | OPACITY |
| 7 | Z-Index | Value | 7 | (none) |
| 8 | Typography | Value | 4 | FONT_FAMILY |
total: 76 variables
Primitives (22 color variables)
blue-reputa/900 #031f4a red-premier/900 #4a0412 neutral/0 #ffffff
blue-reputa/800 #042e6e red-premier/800 #6e081d neutral/50 #f8fafc
blue-reputa/700 #053c92 red-premier/700 #920b28 neutral/100 #f1f5f9
blue-reputa/600 #064BAE red-premier/600 #A10B2E neutral/200 #e2e8f0
blue-reputa/400 #5798e8 red-premier/400 #e8576e neutral/300 #cbd5e1
neutral/400 #94a3b8
neutral/500 #64748b
neutral/600 #475569
neutral/700 #334155
neutral/800 #1e293b
neutral/900 #0f172a
neutral/1000 #020617
Color (16 semantic — aliased to Primitives)
| variable | Light mode → | Dark mode → | scope |
|---|---|---|---|
color/surface-bg |
neutral/0 | neutral/900 | FRAME_FILL, SHAPE_FILL |
color/surface-dim |
neutral/50 | neutral/800 | FRAME_FILL, SHAPE_FILL |
color/surface-raised |
neutral/0 | neutral/800 | FRAME_FILL, SHAPE_FILL |
color/surface-overlay |
neutral/800 | neutral/1000 | FRAME_FILL, SHAPE_FILL |
color/text-primary |
neutral/900 | neutral/0 | TEXT_FILL |
color/text-secondary |
neutral/500 | neutral/400 | TEXT_FILL |
color/text-muted |
neutral/400 | neutral/500 | TEXT_FILL |
color/text-inverse |
neutral/0 | neutral/900 | TEXT_FILL |
color/border-default |
neutral/200 | neutral/700 | STROKE_COLOR |
color/border-strong |
neutral/300 | neutral/600 | STROKE_COLOR |
color/brand-primary |
blue-reputa/600 | blue-reputa/400 | all |
color/brand-hover |
blue-reputa/700 | blue-reputa/400 | all |
color/success |
#16a34a | #22c55e | all |
color/warning |
#d97706 | #f59e0b | all |
color/error |
#dc2626 | #ef4444 | all |
color/info |
#2563eb | #3b82f6 | all |
Spacing (7)
spacing/xs = 4 spacing/sm = 8 spacing/md = 16 spacing/lg = 24
spacing/xl = 32 spacing/2xl = 48 spacing/3xl = 64
Radius (6)
radius/none = 2 radius/sm = 4 radius/md = 8
radius/lg = 12 radius/xl = 16 radius/full = 9999
Size (10)
size/icon-sm = 16 size/icon-md = 20 size/icon-lg = 24 size/icon-xl = 32
size/input-sm = 32 size/input-md = 40 size/input-lg = 48
size/btn-sm = 32 size/btn-md = 40 size/btn-lg = 48
Opacity (4)
opacity/disabled = 0.4 opacity/overlay = 0.5
opacity/hover = 0.8 opacity/pressed = 0.9
Z-Index (7)
z/base = 0 z/dropdown = 100 z/sticky = 200 z/overlay = 300
z/modal = 400 z/toast = 500 z/tooltip = 600
Typography (4 STRING variables)
typography/family-display = "Hanken Grotesk"
typography/family-text = "Inter"
typography/family-content = "Merriweather"
typography/family-number = "Space Grotesk"
text styles (12)
| style name | family | weight | size | line-height |
|---|---|---|---|---|
text/hero |
Hanken Grotesk | 700 | 64 | 70 |
text/h1 |
Hanken Grotesk | 700 | 48 | 58 |
text/h2 |
Hanken Grotesk | 700 | 36 | 45 |
text/h3 |
Hanken Grotesk | 700 | 28 | 36 |
text/body-lg |
Inter | 400 | 18 | 29 |
text/body |
Inter | 400 | 16 | 26 |
text/body-sm |
Inter | 400 | 14 | 21 |
text/ui |
Inter | 500 | 14 | 20 |
text/ui-sm |
Inter | 500 | 12 | 16 |
text/content |
Merriweather | 400 | 17 | 29 |
text/number-lg |
Space Grotesk | 700 | 36 | 43 |
text/number |
Space Grotesk | 500 | 24 | 31 |
effect styles (4)
| style name | type | offset-y | radius | spread | opacity |
|---|---|---|---|---|---|
shadow/sm |
DROP_SHADOW | 1 | 2 | 0 | 5% |
shadow/md |
DROP_SHADOW | 4 | 6 | -1 | 10% |
shadow/lg |
DROP_SHADOW | 10 | 15 | -3 | 10% |
shadow/xl |
DROP_SHADOW | 20 | 25 | -5 | 15% |
variable creation conventions
naming
category/name # colors, primitives
category/sub/name # semantic, grouped
category/name-state # with variant
- slash-separated —
blue-reputa/600,color/surface-bg - lowercase — consistent with 1thay writing style
- no abbreviations —
spacingnotsp,radiusnotrad
code syntax (WEB)
every variable has code syntax set for Dev Mode:
var(--color-blue-reputa-600)
var(--space-md)
var(--radius-lg)
scopes
never use ALL_SCOPES. always assign specific scopes:
| variable type | scope |
|---|---|
| color fills | FRAME_FILL, SHAPE_FILL |
| text colors | TEXT_FILL |
| border colors | STROKE_COLOR |
| spacing/gap | GAP |
| corner radius | CORNER_RADIUS |
| sizes | WIDTH_HEIGHT |
| opacity | OPACITY |
| font family | FONT_FAMILY |
| z-index | (empty — no scope) |
governance workflow
theo chuẩn từ figma__sample.md:
- request — đề xuất component mới hoặc chỉnh sửa qua issue trên github
- sandbox — thiết kế trong
🧪 Playground, kiểm tra auto layout, states, responsive - review — đánh giá thiết kế + tính khả thi khi code, cập nhật CLAUDE.md nếu cần
- publish — di chuyển component vào trang chính thức, chuẩn hóa tên, ghi project-logs.md, publish library
- broadcast — cập nhật astro.md và storybook.md, deploy
component properties convention
theo chuẩn từ sample (Sentence case):
| property type | naming | ví dụ |
|---|---|---|
| variant | Variant |
neutral, brand, success |
| size | Size |
sm, md, lg |
| boolean | dạng câu hỏi/khẳng định | Show icon, Is loading, Disabled |
| text | Label, Helper text |
— |
| instance swap | Icon, Leading |
— |
performance tips
từ figma__sample.md:
- hạn chế deep nesting — không lồng quá nhiều auto layout không cần thiết
- dùng instance, không detach — nếu component thiếu tính năng, cập nhật hệ thống
- theo dõi memory — Figma menu → View → Resource Monitor, giữ dưới 60%
workflow: change a token
- figma: edit variable value in the appropriate collection
- publish: assets panel → publish library (update variables)
- code: update
src/tokens/tokens.csswith new value - code: update
src/tokens/tokens.jsif applicable - verify:
npm run build && npm run build-storybook - log: update
project-logs.mdchangelog
workflow: add a new token
- figma: create variable in correct collection, set scopes + code syntax
- figma: if semantic, alias to primitive (never duplicate raw values)
- publish: update library
- code: add to
src/tokens/tokens.css - code: add to
src/tokens/tokens.js - docs: update
design-tokens.mdwith new token - log: update
project-logs.md
workflow: add a documentation page
- create page with
◆ Nameconvention - add visual documentation (swatches, specimens, bars)
- publish library (if new styles were added)
- update this file's page structure section
publishing
first-time publish
- mở assets panel (
Alt+2hoặc⌥2) - click biểu tượng sách (team library)
- chọn Publish library
- tick: ✓ Variables ✓ Text styles ✓ Effect styles
- nhấn Publish
update publish
sau mỗi thay đổi variable hoặc style:
- assets panel → sách → Publish changes
- review danh sách thay đổi
- nhấn Publish
using in other files
- mở file figma khác
- assets panel → libraries (sách)
- tìm 1thay trong danh sách
- bật toggle
figma ↔ code sync map
| figma | code (tokens.css) |
code (tokens.js) |
|---|---|---|
Primitives / blue-reputa/600 |
--color-brand-600: #064BAE |
colors['blue-reputa'][600] |
Color / color/surface-bg |
--surface-bg: var(--color-neutral-0) |
(component tokens) |
Spacing / spacing/md |
--space-md: 16px |
spacing.md: 16 |
Radius / radius/lg |
--radius-lg: 12px |
radius.lg: '12px' |
Size / size/btn-md |
--size-btn-md: 40px |
sizes.btn.md: 40 |
Opacity / opacity/disabled |
--opacity-disabled: 0.4 |
opacity.disabled: 0.4 |
Z-Index / z/modal |
--z-modal: 400 |
zIndex.modal: 400 |
Typography / family-display |
--font-display: 'Hanken Grotesk' |
typography.fonts.display |
text/hero (style) |
--text-hero: 700 64px/1.1 var(--font-display) |
typography.scale.hero |
shadow/md (effect) |
--shadow-md: 0 4px 6px -1px rgba(...) |
shadows.md |
linked references
- 1thay.md — philosophy, naming conventions, decision-making
- design.md — google labs machine-readable design spec
- design-tokens.md — complete token definitions with usage
- astro.md — astro documentation site setup
- storybook.md — storybook component workshop setup
- project-logs.md — decision log, changelog, roadmap
- CLAUDE.md — claude code agent configuration