# Tokens — Foundation + Semantic + Brand presets
> HSL math-based color system. Đổi 1 hue → cả palette shift theo tự động.
> v0.4 · 2026-05-20
---
## Architecture
```
foundation.css ← Primitive HSL variables (brand-primary-h/s/l, type scale, spacing)
↑
semantic.css ← Role-based colors composed from foundation
(--primary, --surface, --text, --shadow, mesh utilities)
↑
brand-{name}.css ← Per-brand override (only --brand-primary-h/s/l etc)
↑
tailwind.preset.js ← Tailwind v3 preset expose semantic class names
```
## Layer 1 — Foundation (foundation.css)
Primitive HSL values + scales. Override these per brand:
```css
--brand-primary-h: 12; /* hue */
--brand-primary-s: 50%;
--brand-primary-l: 60%;
```
## Layer 2 — Semantic (semantic.css)
Composes foundation into role-based tokens:
```css
--primary: hsl(var(--brand-primary-h) var(--brand-primary-s) var(--brand-primary-l));
--primary-deep: hsl(var(--brand-primary-h) var(--brand-primary-s) calc(var(--brand-primary-l) - 10%));
--primary-soft: hsl(var(--brand-primary-h) var(--brand-primary-s) calc(var(--brand-primary-l) + 25%));
```
Đổi `--brand-primary-h` → tất cả `--primary-*` variants shift theo.
**Aesthetic switch via body class:**
```html
...
...
```
Inside, `--bg`, `--surface`, `--text` tự re-map.
## Layer 3 — Brand preset (brand-{name}.css)
Mỗi brand chỉ cần 3-9 dòng override:
```css
/* brand-annhien.css */
:root {
--brand-primary-h: 28; /* nâu trầm hương */
--brand-primary-s: 40%;
--brand-primary-l: 38%;
}
```
## Layer 4 — Tailwind preset
Tailwind v3 expose semantic class:
```jsx
Card
```
`bg-primary` always points to current brand's primary, không cần đổi code khi đổi brand.
## Usage
### Next.js project
```bash
# 1. Copy tokens
cp -r 00-templates/ui-kit/tokens ./tokens
# 2. Import in app.css / globals.css
@import '../tokens/foundation.css';
@import '../tokens/semantic.css';
@import '../tokens/brand-default.css'; /* or brand-khi.css, brand-annhien.css */
# 3. Wire Tailwind preset
# tailwind.config.js:
module.exports = {
presets: [require('./tokens/tailwind.preset.js')],
content: ['./src/**/*.{js,ts,jsx,tsx}'],
};
# 4. Add aesthetic class to root
{/* or aesthetic-dark for dashboard */}
```
### Vanilla / WordPress
```html
```
## Brand preset shortcuts (suggested hues)
| Brand | Primary hue | Notes |
|-------|-------------|-------|
| An Nhien | 28 (nâu trầm) | s: 40%, l: 38% |
| KHI Wellness | 140 (sage chữa lành) | s: 25%, l: 38% |
| BetterBuy | 12 (coral DTC) | s: 50%, l: 60% (= default) |
| Xanh Marketing | 142 (xanh lá) | s: 45%, l: 45% |
| A-Kryphan | 220 (charcoal calm) | s: 15%, l: 30% |
| HaoGood NZL | 220 (deep navy) | s: 55%, l: 35% |
| AI Tools | 252 (violet tech) | s: 85%, l: 60% |
Em sẽ build brand presets sau khi pages refactor xong.