code-first workflow

1thay theo code-first workflow: components được xây dựng trong Storybook trước khi tồn tại trong Figma. design tokens là cầu nối giữa code và design tools.

workflow

storybook

xây dựng component trong React + TypeScript với đầy đủ Storybook stories, bao gồm tất cả states, edge cases, và yêu cầu accessibility.

tokens.css

định nghĩa hoặc tham chiếu design tokens — colors, spacing, typography — trong src/tokens/tokens.css. tokens là hợp đồng giữa code và design.

/* tokens.css */
:root {
  --color-brand-600: #064BAE;
  --space-md: 16px;
  --font-display: 'Hanken Grotesk', sans-serif;
}

astro docs

ghi lại component và tokens của nó trong Astro. docs site dùng trực tiếp tokens.css, vì vậy colors và spacing luôn đồng bộ.

/* Trong Astro pages, tokens có sẵn toàn cục */
<div style="background: var(--color-brand-600);">
  same token, same colour
</div>

figma

cập nhật Figma để phản ánh component đã xây dựng. variables và styles trong Figma mirror token names trong tokens.css. đây là tài liệu tham khảo, không phải source of truth.

hướng dẫn từng bước

1. định nghĩa tokens trước

trước khi viết component, kiểm tra xem bạn có cần tokens mới không. thêm chúng vào tokens.css và export từ tokens.js.

// tokens.js
export const colors = {
  brand: { 600: '#064BAE' },
};

2. xây dựng trong storybook

tạo component trong s@1thay/core/components/ với các file .tsx, .css, và .stories.tsx. tham chiếu tokens qua var().

/* component.css */
.my-component {
  background: var(--surface-bg);
  border: var(--border-width) solid var(--border-color);
  border-radius: var(--radius-md);
  padding: var(--space-md);
}

3. ghi lại trong astro

thêm documentation pages trong Astro hiển thị component và tokens của nó. dùng DocsLayout hoặc GuidelineLayout tùy trường hợp.

4. cập nhật figma

phản ánh thiết kế cuối cùng trong Figma. variables nên có cùng tên với css tokens để dễ dàng tra cứu.

anti-patterns

đừng thiết kế trong figma trước

thiết kế trong Figma trước tạo ra sự ngắt kết nối giữa thiết kế và những gì có thể xây dựng. các ràng buộc thực sự nằm trong code — browser rendering, accessibility, responsive behaviour. bắt đầu trong Storybook nơi bạn có thể test ngay lập tức.

đừng hardcode tokens

hardcode giá trị như #064BAE hoặc 16px trực tiếp trong components phá vỡ mục đích của design system. nếu bạn cần giá trị chưa có dưới dạng token, hãy thêm token mới — đừng inline một-off.

đừng bỏ qua accessibility

mỗi component phải có stories bao gồm keyboard navigation, screen reader output, và high contrast mode. accessibility không phải bước riêng — nó là một phần của quá trình xây dựng.