# Cowork UI Kit — INDEX

> Atomic Design strict + HSL math color system + 2 aesthetics (warm/dark).
> Đổi 1 brand hue → toàn bộ palette shift theo tự động.
> v0.4 · 2026-05-20
>
> **🌐 Gallery live: https://ui.dang.pm/** (host VPS 5 krycloud, auto SSL)

---

## ⚡ Mới bắt đầu? → Đọc [`USAGE.html`](USAGE.html) trước (5 phút)

Decision tree chọn archetype + 3 scenario thực tế (Next.js / HTML / WordPress) + cheatsheet + rules QC.

---

## Architecture

```
foundation.css      ← HSL primitives (--brand-primary-h/s/l, type scale, spacing)
   ↓
semantic.css        ← Role-based tokens (--primary, --surface, --text)
   ↓
brand-{name}.css    ← Per-brand override (chỉ vài dòng HSL)
   ↓
tailwind.preset.js  ← Tailwind v3 preset expose semantic class names
   ↓
atoms / molecules / organisms / templates / pages   ← Atomic Design strict
```

---

## Folder structure

```
00-templates/ui-kit/
├── INDEX.md                       ← bạn đang đọc
├── USAGE.html                     ← 5-min guide thực tế
│
├── tokens/                        ← Foundation layer
│   ├── INDEX.md
│   ├── foundation.css             ← HSL primitive variables
│   ├── semantic.css               ← Role-based tokens + .aesthetic-warm/.aesthetic-dark + mesh
│   ├── brand-default.css          ← Default coral warm
│   └── tailwind.preset.js         ← Tailwind v3 preset
│
├── atoms/                         ← Atomic Design L1 — atoms
│   └── index.html                 ← 20 atoms × 2 aesthetics
│
├── molecules/                     ← Atomic Design L2 — molecules
│   └── index.html                 ← 10 molecules × 2 aesthetics
│
├── organisms/                     ← Atomic Design L3 — organisms
│   └── index.html                 ← 20 organisms (UI + nav + marketing + dataviz)
│
├── templates/                     ← Atomic Design L4 — layout skeletons (NEW tier)
│   └── index.html                 ← 6 layouts: Dashboard/Tool/Landing/Editorial/Deck/Mobile
│
├── pages/                         ← Atomic Design L5 — concrete pages
│   ├── page-A-dashboard.html
│   ├── page-B-tool.html
│   ├── page-C-landing.html
│   ├── page-D-editorial.html
│   ├── page-E-deck.html
│   └── page-F-pwa.html
│
├── starter/                       ← Copy-paste starter cho project mới
│   ├── README.md
│   ├── foundation.css
│   ├── semantic.css
│   ├── brand-default.css
│   ├── tailwind.preset.js
│   └── archetypes/                ← 6 archetype mockup ready to fork
│       ├── A-dashboard.html
│       ├── B-tool.html
│       ├── C-landing.html
│       ├── D-editorial.html
│       ├── E-deck.html
│       └── F-pwa.html
│
├── brands/                        ← Per-brand preset overrides (7 brand)
│   ├── _template.brand.css        ← skeleton clone khi add brand mới
│   ├── annhien.brand.css          ← h:28 (nâu trầm)
│   ├── khi.brand.css              ← h:140 (sage)
│   ├── betterbuy.brand.css        ← h:12 (coral)
│   ├── xanh.brand.css             ← h:142 (xanh lá)
│   ├── a-kryphan.brand.css        ← h:220 s:15% (charcoal)
│   ├── haogood.brand.css          ← h:220 s:55% (navy)
│   └── ai-tools.brand.css         ← h:252 (violet)
│
├── react/                         ← React component library (TypeScript)
│   ├── package.json
│   ├── tsconfig.json
│   ├── README.md
│   └── src/
│       ├── index.ts               ← barrel
│       ├── lib/cn.ts              ← clsx + tw-merge util
│       ├── atoms/                 ← 20 components + index.ts
│       ├── molecules/             ← 10 components + index.ts
│       └── organisms/             ← 10 components + index.ts
│
├── _previews/                     ← Gallery navigation (start here visually)
│   ├── index.html                 ← Gallery entry — open this in browser
│   ├── trend-05-dark-mesh-fusion.html
│   └── trend-06-warm-friendly.html
│
└── _showcase-v03-deprecated/      ← v0.3 archived (atomic tiers replaced these)
```

---

## Quick usage

### A. Via skill `/kry-ui` (recommended)

```
/kry-ui
```

Em sẽ detect brand + archetype từ CWD, propose HSL, scaffold tokens + archetype skeleton vào project.

### B. Manual — Next.js project

```bash
# 1. Copy starter
cp -r 00-templates/ui-kit/starter ./tokens

# 2. Wire Tailwind preset
# tailwind.config.ts
import coworkPreset from "./tokens/tailwind.preset.js";
export default { presets: [coworkPreset], content: [...] };

# 3. Import CSS in app entry
import "./tokens/foundation.css";
import "./tokens/semantic.css";
import "./tokens/brand-default.css";

# 4. Add aesthetic class to body
<body className="aesthetic-warm">  {/* or aesthetic-dark */}

# 5. Edit tokens/brand-default.css với HSL của brand
:root { --brand-primary-h: 28; --brand-primary-s: 40%; --brand-primary-l: 38%; }
```

### C. Manual — HTML standalone

```html
<link rel="stylesheet" href="tokens/foundation.css">
<link rel="stylesheet" href="tokens/semantic.css">
<link rel="stylesheet" href="tokens/brand-default.css">

<body class="aesthetic-warm">
  <button style="background: var(--primary); color: var(--primary-on); border-radius: var(--r-2xl); padding: var(--space-3) var(--space-6);">
    Click
  </button>
</body>
```

---

## 2 Aesthetic Systems

### Warm — for consumer / landing / editorial / mobile / wellness

- Cream base + coral primary + sage accent + amber highlight
- Instrument Serif italic display + Inter sans body
- KHÔNG mono, KHÔNG grid lines, KHÔNG terminal vibe

### Dark — for dashboard / SaaS tool / dev / analytics

- Near-black base + violet primary + cyan info + emerald success
- Inter tight display + IBM Plex Mono labels
- Mesh gradient (subtle ở dashboard, dreamy ở landing)

---

## 6 Page Archetypes

| Archetype | Aesthetic | Use case | File |
|-----------|-----------|----------|------|
| **A · Dashboard** | Dark | KPI + charts + table | `pages/page-A-dashboard.html` |
| **B · Tool** | Dark refined | Sidebar + list/detail CRUD | `pages/page-B-tool.html` |
| **C · Landing** | Warm | Hero + pricing + FAQ | `pages/page-C-landing.html` |
| **D · Editorial** | Warm (Fraunces) | Article + drop cap | `pages/page-D-editorial.html` |
| **E · Deck** | Warm maximalist | 5-slide deck | `pages/page-E-deck.html` |
| **F · PWA** | Warm | iPhone frame mobile | `pages/page-F-pwa.html` |

---

## Brand preset shortcuts (HSL)

| Brand | h | s | l | Vibe |
|-------|---|---|---|------|
| An Nhien | 28 | 40% | 38% | Nâu trầm hương earthy |
| KHI Wellness | 140 | 25% | 38% | Sage chữa lành |
| BetterBuy | 12 | 50% | 60% | Coral DTC warm |
| Xanh Marketing | 142 | 45% | 45% | Xanh lá tự nhiên |
| A-Kryphan | 220 | 15% | 30% | Charcoal calm |
| HaoGood NZL | 220 | 55% | 35% | Deep navy trust |
| AI Tools | 252 | 85% | 60% | Violet tech |

Mỗi brand chỉ cần 3-9 dòng override trong `brand-{name}.css`.

---

## QC

```
/kry-qc ui
```

Sẽ check:
- Token usage (không hardcode hex)
- Font min 12px
- Tap target ≥32px
- Contrast 4.5:1
- Aesthetic class trên body
- Brand preset wired

---

## Roadmap

### Done (2026-05-20 · v0.4)
- [x] HSL math relational color system
- [x] Semantic 2-layer (foundation + role)
- [x] Atomic Design strict 5-tier (atoms/molecules/organisms/templates/pages)
- [x] Templates tier (layout skeletons, NEW)
- [x] 6 pages refactored to semantic vars
- [x] Skill `/kry-ui` registered
- [x] Starter template `starter/`
- [x] **Brand presets `brands/{name}.brand.css` cho 7 brand** (2026-05-20)
- [x] **React component library `react/`** — 20 atoms + 10 molecules + 10 organisms (2026-05-20)
- [x] **Deploy gallery `ui.dang.pm`** — VPS 5 krycloud, auto SSL (2026-05-20)

### Pending
- [ ] Wire `/kry-init --with-ui` để invoke `/kry-ui` trong init workflow
- [ ] Storybook/Demo app showcase React lib (after first project consumes)