# Design System — website-tuvi

**Mood:** Truyền thống cao cấp · Á Đông · Quiet luxury · Tiệm trà premium
**Stage:** 3 — ui-system
**Mode:** Dark-first (light mode tier-2)

---

## 1. Color Tokens

### Brand
| Token | Light | Dark | Role |
|---|---|---|---|
| `--brand-red` | `#8B1A1A` | `#A52A2A` | Đỏ đô — logo, primary accent |
| `--brand-red-deep` | `#5C0A0A` | `#6B1212` | Đỏ đô đậm — pressed state |
| `--brand-gold` | `#B8860B` | `#D4AF37` | Gold cổ điển — CTA, lá số sao |
| `--brand-gold-soft` | `#A88A3D` | `#C9A961` | Gold muted — link, highlight |
| `--brand-cream` | `#F5EDD8` | `#F5EDD8` | Cream warm — text trên dark |

### Surface (background layers)
| Token | Light | Dark | Role |
|---|---|---|---|
| `--bg-base` | `#FAF7F0` | `#0A0808` | Nền chính (warm off-white / near-black warm) |
| `--bg-elevated` | `#FFFFFF` | `#171010` | Card, panel layer 1 |
| `--bg-overlay` | `#F2EDE0` | `#211616` | Modal, popover, layer 2 |
| `--bg-inset` | `#EDE6D3` | `#0F0A0A` | Input, code block (lõm xuống) |

### Text
| Token | Light | Dark | Role |
|---|---|---|---|
| `--text-primary` | `#1A0F0F` | `#F5EDD8` | Body chính |
| `--text-secondary` | `#4A3838` | `#C4B896` | Body phụ |
| `--text-muted` | `#7A6868` | `#8A7860` | Caption, label |
| `--text-on-accent` | `#FAF7F0` | `#0A0808` | Text trên CTA gold |
| `--text-link` | `#8B1A1A` | `#D4AF37` | Link |

### Semantic
| Token | Light | Dark | Role |
|---|---|---|---|
| `--success` | `#2D5016` | `#7FA86A` | Hợp/Tốt (ngày tốt, sao tốt) |
| `--warning` | `#8B5A00` | `#D4A017` | Cảnh báo (ngày bình) |
| `--danger` | `#8B0000` | `#C73E3E` | Xấu (sao hung, ngày xấu) |
| `--info` | `#1A4D7A` | `#5B9BD5` | Info, neutral note |

### Border
| Token | Light | Dark |
|---|---|---|
| `--border-subtle` | `#E8DFC8` | `#2A1F1F` |
| `--border-default` | `#D4C7A8` | `#3D2D2D` |
| `--border-strong` | `#A88A3D` | `#6B5230` |

---

## 2. Typography

### Font families
```css
--font-display: 'Noto Serif Display', 'EB Garamond', Georgia, serif;
--font-body: 'Be Vietnam Pro', system-ui, -apple-system, sans-serif;
--font-numeral: 'Cormorant Garamond', 'Crimson Pro', Georgia, serif;
--font-mono: 'JetBrains Mono', ui-monospace, monospace;
```

**Google Fonts import:**
```html
<link href="https://fonts.googleapis.com/css2?family=Noto+Serif+Display:wght@400;500;600;700;800&family=Be+Vietnam+Pro:wght@300;400;500;600;700&family=Cormorant+Garamond:wght@400;500;600;700&display=swap" rel="stylesheet">
```

### Type scale (mobile-first, modular 1.25)
| Token | Mobile | Desktop | Usage |
|---|---|---|---|
| `--text-xs` | 12px / 16px | 12px / 16px | Caption, badge |
| `--text-sm` | 14px / 20px | 14px / 20px | Label, helper |
| `--text-base` | 16px / 26px | 16px / 26px | Body — Vietnamese 1.6 line-height |
| `--text-lg` | 18px / 28px | 18px / 28px | Lead paragraph |
| `--text-xl` | 20px / 30px | 22px / 32px | h4, card title |
| `--text-2xl` | 24px / 32px | 28px / 36px | h3 |
| `--text-3xl` | 28px / 36px | 36px / 44px | h2 |
| `--text-4xl` | 32px / 40px | 48px / 56px | h1 |
| `--text-5xl` | 40px / 48px | 64px / 72px | Hero display |
| `--text-6xl` | 48px / 56px | 80px / 88px | Editorial hero (rare) |

### Weight
- Display/heading: **600** (semi-bold serif looks right)
- Body: **400** regular, **500** for emphasis
- CTA buttons: **500** medium (avoid 700 — looks cheap on serif)

### Tracking
- Heading serif: `-0.01em` (slight tighten)
- Body: `0` default
- All-caps label: `+0.08em`

---

## 3. Spacing

8-point grid. No magic numbers.

```css
--space-0: 0;
--space-1: 4px;
--space-2: 8px;
--space-3: 12px;
--space-4: 16px;
--space-5: 24px;
--space-6: 32px;
--space-7: 48px;
--space-8: 64px;
--space-9: 96px;
--space-10: 128px;
--space-11: 160px;
```

### Section padding (responsive)
- Mobile: `--space-8` (64px) top/bottom
- Tablet: `--space-9` (96px)
- Desktop: `--space-10` (128px)

### Card padding
- Compact: `--space-4` (16px)
- Default: `--space-5` (24px)
- Spacious: `--space-6` (32px)

### Container
- Max-width: `1200px`
- Gutter mobile: `16px`
- Gutter desktop: `24px`

---

## 4. Radius

```css
--radius-sm: 4px;     /* badges, tags */
--radius-md: 8px;     /* buttons, inputs */
--radius-lg: 12px;    /* cards */
--radius-xl: 16px;    /* hero card, modal */
--radius-2xl: 24px;   /* feature cards */
--radius-full: 9999px;/* pills, avatars */
```

**Triết lý:** Á Đông cao cấp giữ corner vừa phải — không sharp brutal, không bubble cute.

---

## 5. Shadow

```css
/* Light mode — subtle warm shadows */
--shadow-sm: 0 1px 2px rgba(60, 30, 20, 0.06);
--shadow-md: 0 2px 8px rgba(60, 30, 20, 0.08), 0 1px 2px rgba(60, 30, 20, 0.04);
--shadow-lg: 0 8px 24px rgba(60, 30, 20, 0.10), 0 2px 6px rgba(60, 30, 20, 0.06);
--shadow-xl: 0 16px 48px rgba(60, 30, 20, 0.14), 0 4px 12px rgba(60, 30, 20, 0.08);

/* Dark mode — gold glow accents (subtle) */
--shadow-sm-dark: 0 1px 2px rgba(0, 0, 0, 0.4);
--shadow-md-dark: 0 4px 12px rgba(0, 0, 0, 0.5), 0 1px 3px rgba(0, 0, 0, 0.3);
--shadow-lg-dark: 0 12px 32px rgba(0, 0, 0, 0.6), 0 4px 8px rgba(0, 0, 0, 0.4);
--shadow-glow-gold: 0 0 24px rgba(212, 175, 55, 0.15);
--shadow-glow-red: 0 0 24px rgba(165, 42, 42, 0.20);
```

**Triết lý:** không quá nhiều shadow stack (kiểu material design lụi tàn) — đơn giản, tinh tế.

---

## 6. Motion

```css
--duration-fast: 120ms;
--duration-base: 200ms;
--duration-slow: 320ms;
--duration-slower: 500ms;

--ease-default: cubic-bezier(0.4, 0, 0.2, 1);
--ease-out: cubic-bezier(0.0, 0, 0.2, 1);
--ease-in: cubic-bezier(0.4, 0, 1, 1);
--ease-spring: cubic-bezier(0.34, 1.56, 0.64, 1);
```

**Patterns:**
- Hover transitions: `--duration-fast` ease-out
- Modal/popover open: `--duration-base` ease-out
- Page transition: `--duration-slow` ease-default
- Lá số reveal animation: `--duration-slower` ease-spring (impressive but not loud)

**Reduced motion:** mọi animation phải fallback `transform: none` khi `prefers-reduced-motion: reduce`.

---

## 7. Z-index scale

```css
--z-base: 0;
--z-dropdown: 100;
--z-sticky: 200;
--z-fixed: 300;
--z-overlay: 400;
--z-modal: 500;
--z-popover: 600;
--z-toast: 700;
--z-tooltip: 800;
```

---

## 8. Anti-patterns (≥3 — required for gate)

1. **❌ Emoji as icons** — luôn dùng SVG (Lucide cho generic, custom SVG cho lá số/bát quái/can chi). Emoji phá tone luxury và inconsistent giữa OS.
2. **❌ Hardcoded hex** trong components — mọi màu phải từ token. Vi phạm = fail review.
3. **❌ Material Design heavy shadows** — site mình quiet luxury, không elevation theatrics. Max shadow-lg.
4. **❌ Vibrant rainbow palette** — chỉ dùng đỏ đô + gold + neutral. Thêm màu khác = phá brand.
5. **❌ Sans-serif heading** — heading PHẢI serif (Noto Serif Display). Sans heading làm site trông như SaaS template.
6. **❌ Generic stock photo** — ưu tiên custom illustration / SVG bát quái, can chi, lá số. Không dùng ảnh "happy person staring at laptop".
7. **❌ Animation kiểu sci-fi** — không particles, không glow neon di động, không parallax loud. Motion phải subtle.
8. **❌ All-caps body text** — chỉ all-caps cho label nhỏ (badge, tag). All-caps body phá readability tiếng Việt có dấu.

---

## 9. Component primitives (kèm spec để Stage 5 build)

### Button
- Primary (gold): `bg: --brand-gold, text: --text-on-accent, border: none, padding: 12px 24px, radius: --radius-md`
- Secondary (red): `bg: transparent, text: --brand-red, border: 1px --brand-red`
- Ghost: `bg: transparent, text: --text-primary, hover: --bg-elevated`
- Hover: brightness +5%, slight lift `translateY(-1px)`
- Active: `translateY(0)`, brightness -5%
- Disabled: `opacity: 0.4, cursor: not-allowed`
- Focus: `outline: 2px --brand-gold, outline-offset: 2px`

### Input
- Border: `1px --border-default`
- Focus: `border-color: --brand-gold, ring: 3px rgba(212,175,55,0.2)`
- Error: `border-color: --danger`
- Placeholder: `--text-muted`
- Date picker (cho lá số): custom 3 dropdown ngày/tháng/năm + AM/DL toggle

### Card
- Default: `bg: --bg-elevated, border: 1px --border-subtle, radius: --radius-lg, padding: --space-5`
- Hover: `border-color: --brand-gold-soft, shadow: --shadow-md, translateY(-2px)`
- Tool card: thêm icon-led top + title + 1 line desc

### Badge
- Tốt: `bg: success/15, text: success, border: success/30`
- Xấu: `bg: danger/15, text: danger, border: danger/30`
- Neutral: `bg: --bg-overlay, text: --text-secondary`

---

## 10. Responsive breakpoints

```css
--bp-sm: 640px;    /* large phones landscape */
--bp-md: 768px;    /* tablets */
--bp-lg: 1024px;   /* small desktops */
--bp-xl: 1280px;   /* desktops */
--bp-2xl: 1440px;  /* large desktops */
```

**Mobile-first:** mọi component default 375px, scale up bằng min-width queries.

---

## 11. Iconography

- **Generic icons:** Lucide React (`lucide-react` lib) — clean line icons, weight matches Be Vietnam Pro
- **Mystical icons (custom SVG):**
  - Bát quái 8 hướng
  - Ngũ hành 5 yếu tố (Kim/Mộc/Thủy/Hỏa/Thổ)
  - 12 con giáp
  - 12 cung hoàng đạo
  - 24 sao tử vi (custom set)
  - Can chi (10 thiên can + 12 địa chi)
- Stroke width: **1.5px** (Lucide default) cho consistency
- Size scale: `16, 20, 24, 32, 48` px

---

## 12. Accessibility (WCAG AA mandatory)

- **Contrast ratios** (đã verify pairs ở dark mode):
  - text-primary `#F5EDD8` trên bg-base `#0A0808` → 14.8:1 ✓ AAA
  - text-secondary `#C4B896` trên bg-base → 9.6:1 ✓ AAA
  - brand-gold `#D4AF37` trên bg-base → 9.1:1 ✓ AAA
  - text-on-accent `#0A0808` trên brand-gold `#D4AF37` → 9.1:1 ✓ AAA
- **Focus visible:** mọi interactive element có `outline 2px --brand-gold + 2px offset`
- **Motion:** `prefers-reduced-motion` fallback bắt buộc
- **Touch target:** ≥ 44×44px mobile (Apple HIG)
- **Vietnamese diacritics:** font phải hỗ trợ đầy đủ (Be Vietnam Pro + Noto Serif Display VN subset đều OK)

---

## 13. Tailwind config preview (cho Stage 5)

```js
// tailwind.config.ts (preview)
export default {
  darkMode: 'class',
  theme: {
    extend: {
      colors: {
        brand: {
          red: { DEFAULT: '#A52A2A', deep: '#6B1212' },
          gold: { DEFAULT: '#D4AF37', soft: '#C9A961', light: '#B8860B' },
          cream: '#F5EDD8',
        },
        bg: {
          base: 'var(--bg-base)',
          elevated: 'var(--bg-elevated)',
          overlay: 'var(--bg-overlay)',
          inset: 'var(--bg-inset)',
        },
      },
      fontFamily: {
        display: ['"Noto Serif Display"', 'serif'],
        body: ['"Be Vietnam Pro"', 'sans-serif'],
        numeral: ['"Cormorant Garamond"', 'serif'],
      },
    },
  },
};
```

---

## Gate — Stage 3 EXIT CRITERIA

- [x] Color tokens (light + dark)
- [x] Typography tokens
- [x] Spacing tokens
- [x] Radius tokens
- [x] Shadow tokens
- [x] Motion tokens
- [x] Dark mode tokens (mặc định dark)
- [x] ≥3 anti-patterns (có 8)

✅ **PASS** — Sẵn sàng vào Stage 4 (ui-wireframe)