` singular noun.
```
ui-kit/
├── tokens/ # plural — collection of token files
├── atoms/ # plural — layer (Atomic Design)
├── molecules/ # plural — layer
├── organisms/ # plural — layer
├── templates/ # plural — layer
├── pages/ # plural — collection of demo pages
├── brands/ # plural — collection of brand presets
├── blocks/ # plural with sub-folders per archetype
│ ├── A-dashboard/
│ ├── B-tool/
│ ├── C-landing/
│ ├── D-editorial/
│ ├── E-deck/
│ └── F-pwa/
├── mobile/ # collection — special layer for mobile-specific
│ ├── patterns/
│ └── starters/
├── react/ # implementation — singular
│ └── src/
│ ├── atoms/
│ ├── molecules/
│ ├── organisms/
│ └── tokens/
├── icons/ # plural — collection
└── starter/ # singular — scaffolding kit
```
### Rule
- KHÔNG mix CamelCase / kebab-case trong cùng level (`Atoms/` + `molecules/` ❌)
- KHÔNG snake_case cho folder (`my_folder/` ❌ → `my-folder/`)
- Plural cho **collection** (`atoms/`, `tokens/`, `brands/`)
- Singular cho **concept hoặc implementation root** (`react/`, `starter/`)
- Underscore prefix `_` cho folder đặc biệt (`_previews/`, `_showcase-v03-deprecated/`) — báo hiệu "skip in normal scan"
---
## 6. Variant naming
**Pattern:** semantic intent, NOT visual description.
| ✅ Good | ❌ Bad | Why |
|---|---|---|
| `variant="primary"` | `variant="blue"` | Color thay đổi per brand, intent không |
| `variant="danger"` | `variant="red"` | Same reason — KHI danger có thể là magenta |
| `variant="ghost"` | `variant="transparent"` | Ghost = pattern (transparent bg + colored text + hover bg), transparent = chỉ property |
| `variant="outline"` | `variant="bordered"` | Outline = convention chuẩn shadcn/HeroUI |
| `size="md"` | `size="medium"` | Convention short (md/lg/xl phổ biến) |
| `size="2xl"` | `size="huge"` | Scale có boundaries rõ, "huge" không quantify được |
| `tone="soft"` | `tone="light"` | Soft = subtle tinted, light = chỉ về lightness |
### Standard variants per component type
- **Button**: `primary` / `secondary` / `ghost` / `outline` / `danger` / `link`
- **Badge**: `primary` / `success` / `warning` / `danger` / `info` / `neutral`
- **Card**: `default` / `elevated` / `outlined` / `interactive`
- **Input**: `default` / `error` / `success` (size: `sm` / `md` / `lg`)
- **Banner / Alert**: `info` / `success` / `warning` / `danger`
- **Avatar**: shape `circle` / `square` / `rounded` (size: `xs` / `sm` / `md` / `lg` / `xl`)
- **Tooltip**: side `top` / `right` / `bottom` / `left`
### Rule
- Variant prop tên chuẩn: `variant` (KHÔNG `type`, `kind`, `style`, `appearance`)
- Size prop tên chuẩn: `size` (KHÔNG `scale`, `dimension`)
- Boolean flag: positive name (`disabled`, `loading`, `selected`) — KHÔNG `notActive`
- Compound state: dùng `state` prop (`state="loading"`) nếu nhiều state mutex
---
## 7. Anti-patterns tổng
```
❌ button-blue-large.tsx → ✅ Button.tsx với variant + size props
❌ FinalButton.tsx, ButtonNew.tsx → ✅ versioning sống trong git, không filename
❌ --color-primary-500 → ✅ --primary (semantic, brand-agnostic)
❌ .CardHeader { } (CSS PascalCase) → ✅ .card__header { }
❌ space-22 hardcoded → ✅ add vào scale hoặc dùng --space-5/6
❌ font-family: Arial trực tiếp → ✅ font-family: var(--font-sans)
❌ #FF5733 in component CSS → ✅ var(--primary)
❌ → ✅ hoặc class semantic
❌ ButtonComponent / ButtonWrapper → ✅ Button (KHÔNG suffix wrapper)
❌ my-button.tsx (kebab cho component) → ✅ Button.tsx (PascalCase cho TSX)
❌ folder Atoms/ + molecules/ → ✅ thống nhất lowercase: atoms/ + molecules/
❌ var(--clr-pri) abbreviation → ✅ var(--primary)
❌ size="medium-large" → ✅ size="lg" (scale chuẩn)
```
---
## 8. AI generation rules
Khi AI generate code dùng Cowork UI Kit, BẮT BUỘC tuân thủ:
1. **Token-first** — ưu tiên `var(--*)` hoặc Tailwind class wrap token (vd `bg-[var(--primary)]`). KHÔNG hardcode hex / rgb / px arbitrary.
2. **Variant > custom** — dùng variant prop có sẵn (`