1thay

trăm nghe không bằng một thấy

hệ thống thiết kế dành cho một người, được một người làm ra. phục vụ saas dashboards, infographics, và các giao diện giàu dữ liệu. đề cao trải nghiệm đọc, trực quan hóa thông tin, và cảm giác sử dụng.

tài liệu liên quan: design.md · design-tokens.md · figma.md · astro.md · storybook.md · project-logs.md · CLAUDE.md

tổ chức dự án & quy tắc đặt tên

cấu trúc thư mục

1thay-com/
├── 1thay.md              # triết lý & quy chuẩn (file này)
├── design.md             # machine-readable spec (chuẩn google design.md)
├── design-tokens.md      # token chi tiết & brand themes
├── project-logs.md       # nhật ký quyết định & tự cải tiến
├── src/
│   ├── tokens/           # css custom properties, tailwind config
│   ├── components/       # astro + storybook components
│   ├── layouts/          # page layouts
│   ├── pages/            # astro pages (landing, dashboard, docs, prototype)
│   └── styles/           # global styles
├── public/               # static assets
├── storybook/            # storybook config & stories
└── .github/              # ci/cd workflows

quy tắc đặt tên file

kebab-case cho mọi file và thư mục: button-primary.astro, brand-colors.css
số thứ tự dùng leading zero nếu cần: 01-overview.md, 02-colors.md
không viết tắt trừ khi đã là chuẩn ngành: btn → button, nhưng ui được chấp nhận

quy tắc đặt tên token

--<category>-<property>-<variant>-<state>

category	mô tả	ví dụ
`color`	màu sắc	`--color-blue-reputa-600`
`font`	typography	`--font-display`, `--font-text`
`space`	spacing	`--space-md`, `--space-lg`
`radius`	bo góc	`--radius-sm`, `--radius-md`
`shadow`	đổ bóng	`--shadow-sm`, `--shadow-lg`
`size`	kích thước	`--size-icon-md`, `--size-btn-h`
`z`	stacking	`--z-modal`, `--z-tooltip`
`opacity`	độ mờ	`--opacity-disabled`, `--opacity-overlay`
`border`	viền	`--border-width`, `--border-color`

quy tắc đặt tên component

tên component: PascalCase trong code, kebab-case trong file
variant: dùng data attribute data-variant="..." hoặc props
state: :hover, :focus-visible, [aria-disabled], [aria-invalid]

quy trình ra quyết định

nguyên tắc cơ bản

visual-first — mọi quyết định phải được kiểm chứng bằng mắt. không tranh luận trên figma hay code khi chưa thấy kết quả render
lowercase — toàn bộ văn bản giao diện viết thường, trừ tên riêng và nhãn hiệu
bento grid — layout dùng grid system lấy cảm hứng từ bento, ưu tiên module chữ nhật có bán kính bo góc đồng nhất
reading first — khoảng cách dòng, cỡ chữ, độ tương phản phải tối ưu cho đọc trước, sau đó mới đến thẩm mỹ
data clarity — số liệu, biểu đồ, bảng biểu phải rõ ràng, dễ so sánh, không che giấu thông tin sau hiệu ứng

tiêu chí đánh giá

tiêu chí	câu hỏi kiểm tra
nhất quán	có dùng đúng token không? có lặp lại giá trị hardcoded không?
đọc được	contrast ratio có đạt aa không? line-height có đủ không?
phản hồi	hover/focus/active có rõ ràng không? loading state có không?
đáp ứng	mobile có vỡ layout không? tablet có thiếu không gian không?

giải quyết xung đột

khi có 2 lựa chọn thiết kế mâu thuẫn:

render cả 2 ra màn hình
đặt cạnh nhau
chọn cái nhìn rõ hơn, dễ đọc hơn, ít gây phân tâm hơn
nếu vẫn không rõ → chọn cái đơn giản hơn

hệ thống design tokens

phân cấp

global       →  spacing, radius, shadow, opacity, z-index, size
  └─ brand   →  color palette, font families
     └─ semantic → success, warning, error, info, surface, text
        └─ component → button, card, input, table, chart, badge

quy tắc:

global tokens không phụ thuộc brand — dùng chung cho tất cả
brand tokens định nghĩa bảng màu và font cho từng brand
semantic tokens ánh xạ từ brand tokens sang mục đích sử dụng
component tokens chỉ dùng trong nội bộ component, không export ra ngoài

multi-brand

hệ thống hỗ trợ nhiều brand thông qua theme variables. mỗi brand định nghĩa một bộ màu riêng, cùng chia sẻ global tokens.

brand hiện có:

blue-reputa (mặc định) — phát triển từ #064BAE
red-premier — phát triển từ #A10B2E

cách thêm brand mới:

định nghĩa base color
tạo palette 5 mức (900, 800, 700, 600, 400)
ánh xạ semantic tokens
thêm vào design-tokens.md

kiểm thử & đánh giá

design qa checklist

token được dùng đúng tên, không hardcode giá trị
màu sắc nhất quán với brand palette
typography đúng font family và scale
spacing dùng đúng scale (4, 8, 16, 24, 32, 48, 64)
border radius đúng scale (2, 4, 8, 12, 16, full)
responsive: mobile (< 768px), tablet (768-1024px), desktop (> 1024px)

accessibility

color contrast đạt wcag aa (4.5:1 cho text thường, 3:1 cho text lớn)
focus indicator rõ ràng trên mọi interactive element
target size tối thiểu 24px cho touch
aria label đầy đủ cho component

visual regression

mỗi lần đổi token → chụp screenshot trước/sau
so sánh side-by-side
ghi nhận khác biệt vào project-logs.md

hệ sinh thái & quy trình làm việc

figma (thiết kế)
  ↕ sync tokens
storybook (design.1thay.com)
  ↕ phát triển & test component
astro (1thay.com)
  → landing page · dashboard · docs · prototype
github
  → cloudflare pages (deploy)

quy trình hàng ngày

thiết kế trên figma → token được export ra code
phát triển component trong storybook → test isolated
tích hợp vào astro page → test toàn diện
push lên github → cloudflare pages auto deploy
review kết quả → ghi nhận vào project-logs.md

tự động hóa

design lint — kiểm tra design.md hợp lệ
visual regression test — so sánh screenshot trước/sau
cloudflare pages — auto deploy từ github