# UU Design System (UU DS)

> Design system UU DS. Token 2 tầng (primitive → semantic), hai brand mode — Default (`:root`: interactive indigo, accent blue, trung tính slate) và UU (`data-theme="uu"`: cam + vàng nhận diện Ú Ù), density Touch / Compact, trục layout Expanded / Collapsed, hover/pressed qua state layer, 50 component đã chốt, bộ UU icon 100 tên công khai. Storybook này phục vụ người đọc; các file dưới đây là cùng nội dung ở dạng máy đọc.

Đọc theo thứ tự. Mọi file là nguyên bản, không tóm tắt.

## Bắt buộc đọc trước khi viết code

- [Spec đầy đủ](docs/design-system.md): mục 0 (luật), 1–3 (token, màu, typography), 4 (spacing/radius/elevation), 5 (danh sách component — ngoài danh sách là chưa chốt), 6.0 (state layer), 6.x (từng component).
- [tokens.css](docs/tokens.css): CSS custom properties, brand mode, recipe state layer `.uu-interactive .uu-on-dark .uu-on-light`, text style `.text-*`.

## DNA của sản phẩm: làm trước màn đầu tiên

UU DS là bộ xương, DNA là chất riêng của từng sản phẩm. Tìm `DNA.md` theo thứ tự: đường dẫn người dùng đưa, gốc project, `docs/DNA.md`. Không thấy thì hỏi một lần: có DNA hoặc style anchor không (ảnh, link Figma, website). Có style anchor thì trích thành `DNA.md`. Không có thì build Basic và báo một dòng khi bàn giao.

- [Product DNA](docs/product-dna.md): tìm file, phần khoá và phần được đổi, cách áp bằng `[data-theme]`, cách trích, kiểm trước khi giao.
- [Khuôn DNA](docs/dna-template.md): chép thành `DNA.md` khi trích.

## Khi cần

- [tokens.json](docs/tokens.json): DTCG-style, có `$resolved` — sinh sang iOS/Android/Style Dictionary.
- [tailwind.js](docs/tailwind.js): theme Tailwind trỏ về CSS var — chỉ khi project dùng Tailwind.
- [icons.md](docs/icons.md): luật UU icon (một component Icon(name, variant, size), SVG currentColor, fill = trạng thái bật, không có trong index → hỏi), cách thêm icon.
- [uu-icon-index.json](docs/uu-icon-index.json): 100 tên icon công khai → category và kiểu có sẵn (outline / fill).
- [ontology.json](docs/ontology.json): bản đồ hệ thống (ontology) — token, component, mode, vai trò màu, cây quyết định và quan hệ (usesToken, composedOf, confusedWith, chosenWhen…). Không có trong nodes = chưa chốt. Tóm tắt đọc nhanh: [ontology.md](docs/ontology.md).



## Sáu ràng buộc

1. Không hardcode màu; chỉ token semantic `--background-*` `--object-*` `--border-*`; cấm `--color-*` trong component.
2. Brand là một lớp token (21 token, spec 2.5), đổi bằng `data-theme` (`default` · `uu`, đặt trên `<html>` hoặc một vùng); component không biết brand; `accent` ≠ `interactive`.
3. Hover/Pressed = state layer `::after` tô bằng màu object của variant (CSS `currentColor`), opacity 5/10 nền sáng · 20/40 nền tối; không đổi nền/chữ/weight; Disabled và Loading không có.
4. Chỉ thang có sẵn: gap bước 4px, radius-*, 11 bậc font size, line-height tuyệt đối (web: rem, app: px), density Touch / Compact (`data-density="compact"`, spec §4.1), font hệ thống (không nhúng SF Pro).
5. Chỉ build component ở mục 5 của spec; thiếu → hỏi, làm tạm phải ghi rõ. Chưa chốt: hàng danh sách `ListItem`, state và vị trí của mục `BottomBar`, hàng rỗng / đang tải của bảng.
6. Icon chỉ UU icon qua Icon(name, variant, size); tên tra ở uu-icon-index.json.

## Code tham chiếu (repo)

- `src/components/*` React + CSS thuần, tên trùng spec: TextButtonAccent, TextButtonNeutral, TextButtonDanger, IconButtonAccent, IconButtonNeutral, ToggleButton, ButtonGroup, TextInput, TextArea, OTPInput, SearchInput, DateInput, Dropdown, Menu, Checkbox, CheckboxInput, Radio, RadioInput, RadioList, Switch, Chip, SegmentedControl, NavigationBar, BottomBar, Tab, TabBar, Pagination, Toast, Badge, StatusIndicator, NotificationBadge, Tooltip, CardSheet, BottomSheet, BaseDialog, Dialog, SideSheet, Popover, Table, TableRow, TableHeaderCell, TableCell, TablePagination, KPICard, Breadcrumb, SideNav, SideNavItem, SideNavSection, Spinner.
- `src/icons/Icon.tsx` + `src/icons/svg/<name>[-fill].svg` (100 tên công khai × outline/fill, viewBox 0 0 18 18, currentColor).
- Package npm `uu-ds` (exports: `.`, `./tokens.css`, `./base.css`, `./icons`, `./icons/svg/*`). Zalo Mini App (ZMP, React) dùng thẳng package này.
- Flutter: `packages/flutter/uu_ds_flutter` — `tokens.g.dart` sinh từ tokens.json, widget `UuTextButton`, `UuTextInput`, `UuIcon`… cùng prop với bản web.
- `AGENTS.md` ở gốc repo.