hệ thống thiết kế 1thay

1thay là một hệ thống thiết kế code-first dành cho bảng điều khiển SaaS và giao diện giàu dữ liệu. Nó phục vụ hai bề mặt công khai và một công cụ riêng tư:

1thay.com

Trang tài liệu Astro — foundations, patterns, guidelines. Được xây từ src/pages/.

design.1thay.com

Xưởng component Storybook — bản xem trước trực tiếp, tài liệu MDX và kiểm tra tương tác.

Figma

Tài liệu tham khảo trực quan — phản ánh token code để so sánh thiết kế. Không phải nguồn chân lý.

kiến trúc

Hệ thống tuân theo quy trình tuyến tính: storybook → tokens → astro → figma.

storybook

Mọi component được xây dựng và kiểm tra độc lập trong Storybook trước khi được sử dụng ở bất kỳ đâu khác. Story đóng vai trò vừa là tài liệu vừa là môi trường phát triển.

s@1thay/core/components/Name/
├── name.css
├── Name.tsx
├── Name.stories.tsx
├── name.docs.mdx
└── Name.test.tsx

tokens.css

Tất cả design token là thuộc tính tùy chỉnh CSS trong src/tokens/tokens.css. Đây là nguồn chân lý duy nhất cho màu sắc, khoảng cách, kiểu chữ, đổ bóng, bo góc và z-index. Cả Astro và Storybook đều import file này.

astro

Trang tài liệu được xây dựng với Astro 5. Trang nằm trong src/pages/ và sử dụng hai bố cục: BaseLayout (gốc với thanh điều hướng) và DocsLayout (với thanh bên điều hướng).

figma

Figma phản ánh token code để so sánh trực quan. Hướng đồng bộ là code → figma, không bao giờ ngược lại. Để biết về tương tác MCP, xem tích hợp figma.

phân loại component

component được tổ chức thành 4 nhóm kỹ thuật trong storybook:

Nhóm	Bản chất	Component
CORE	foundational primitives	Logo, LogoSocial, BrandSwitch, Icon, IconFill, Divider
DASHBOARD	app shell + data	Table, StatCard, Progress, Badge, Card, Avatar, Skeleton, Alert, EmptyState, Sidebar, TopNav, Tabs, Breadcrumbs, Modal, Toast, WipBanner
LANDING	form controls	Button, Input, Select, Checkbox, Switch, Radio, Textarea
PATTERNS	examples (khong co API)	Examples, Floorplans, Installation

hệ thống thương hiệu

4 chế độ thương hiệu — mỗi thương hiệu có bảng màu 10 sắc độ và font hiển thị riêng. Chuyển đổi qua thuộc tính data-brand hoặc component BrandSwitch.

Thương hiệu	Cơ bản	Font hiển thị	Tính cách
reputa-blue	`#064BAE`	Hanken Grotesk	chuyên nghiệp, tài chính
reputa-premier	`#A10B2E`	Hanken Grotesk	xa xỉ, thương mại
tramnghe	`#044f44`	Merriweather	tự nhiên, chăm sóc sức khỏe
1thay	`#FBC000`	Space Grotesk	năng động, sáng tạo

<!-- mặc định (reputa-blue) -->
<Button>save</Button>

<!-- chuyển thương hiệu -->
<div data-brand="reputa-premier">
  <Button>delete</Button>
</div>

quy ước đặt tên

file / thư mục: kebab-case (button-primary.astro)
component: PascalCase (Button, DocsLayout)
CSS token: --category-property-variant (--color-brand-600)
biến Figma: category/name (reputa-blue/600)
không viết tắt trừ khi là chuẩn ngành (ui, btn, sm/md/lg)

cấu trúc dự án

src/
├── tokens/           # tokens.css + tokens.js (nguồn chân lý duy nhất)
├── components/       # react components — storybook quan ly inventory
├── layouts/          # BaseLayout.astro, DocsLayout.astro
├── pages/            # trang astro (foundations, patterns, guidelines)
├── overview/         # story onboarding stories
├── floorplans/       # mẫu trang storybook
└── styles/           # global.css

lệnh chính

npm run storybook       # storybook dev (port 6006)
npm run dev             # astro dev (port 4321)
npm run build-storybook # storybook production build
npm run build           # astro production build
npm test                # vitest unit tests
npm run lint            # astro type check
npm run check-tokens    # xác minh snapshot token
npm run chromatic       # regression trực quan (chỉ PR)