# DOL Design System — AI Entry (Vibe Code UI Pack)

Paste this file into your AI tool (Cursor, Claude, ChatGPT, v0,
Lovable, Figma Make, etc.) as system context. The AI will then
know DOL's color system, typography, spacing, radius, shadow
conventions, hard rules, and anti-patterns — and produce
DOL-compliant UI code on first try.

**Canonical URL:** https://dol-wiki.khoajak.design/ai/

**Pack contents (in order):**

1. `design-guideline/ai-entry/README.md` — AI Entry — orientation + hard rules
2. `design-guideline/ai-entry/CODE-UI.md` — CODE-UI — UI task router for AI agents
3. `docs/ai-color-context.md` — Color context — paste-ready system prompt
4. `design-guideline/ui-style-guide/CORE.md` — UI style guide CORE — code conventions
5. `design-guideline/anti-pattern-registry.md` — Anti-pattern registry — what NOT to do

---
<!-- ============ source: design-guideline/ai-entry/README.md ============ -->


# 🎯 AI Entry - Start Here

> **Bạn là AI agent đang work trên DOL Education?** Đây là entry duy nhất bạn cần đọc đầu tiên. Từ file này bạn sẽ biết: hard rules nào luôn apply, file detail nào load cho task của bạn, và cách self-verify trước khi declare done.

This single file gives you (a) hard rules that always apply, (b) a router from "what I'm doing" → "what file to read next", and (c) a self-check before shipping. Detail content lives in linked files — load on demand, not eagerly.

---

## 1. 30-second workspace orientation

DOL Edu = multi-repo education platform. Product pipeline:
**Spec (EduDoc) → Demo/validation (Playground) → Publish/runtime (Wiki)**.
All code surfaces consume one design-system source: **DS-Token**.

| Repo / surface | Role | Design-system consumption |
|------|------|------|
| `DOL-DS-token` | Token, UI guideline, Tailwind/runtime mapping authority | Owns `tokens/v4/`, color contract, shared Tailwind helpers, Studio |
| `DOL Education Documentation` (EduDoc) | Product spec, UX behavior, domain knowledge | Static prototype CSS subset in `assets/css/` |
| `dol-edu-playground` | Runtime demo/validation (React + Vite + TW v4 + TS) | `tailwind.config.cjs` imports DS-Token color/shadow helpers; `tokens:gen` emits subset |
| `DOL Wiki/site` | Publish/docs runtime (Next.js + TW v4 + TS) | `tailwind.config.ts` imports DS-Token color/shadow helpers; `tokens:gen` emits subset |
| `DOL-DS-token/studio` | DS-owned design-system browser, mounted under Wiki at `/design-system/` | `studio/tailwind.config.cjs` imports the same helpers; `studio:build` slims token CSS |

Token mapping chain:
`tokens/v4/ → tailwind-color-contract.json → tailwind-color-config.cjs + tailwind-shadow-scale.js → consumer tailwind.config.* → generated token CSS → Tailwind classes`.

Token changes propagate via `node scripts/tokens-propagate.mjs`. For the exact consumer contract and verification commands, read `../../docs/consumer-token-adapter.md`.

For workspace-wide context (skills, hooks, approval matrix) → workspace `CLAUDE.md` (auto-loaded by Claude Code).

---

## 2. Hard rules (non-negotiable — apply to EVERY task)

> [!warning]
> Non-negotiable. Violating any rule below = stop, ask, fix.

These are the safety net. Memorize, don't skip — even if you don't load any detail file, **never violate** these.

### 2.1 Color
- **Brand** = `bg-brand-*` (custom class, NOT `bg-red-*`). `bg-red-*` = danger/error only.
- **Canonical shade** = `-600` (NOT TW default `-500`).
- **Text on colored/inverse bg** = `text-on-inverse-primary` (`--white-w100`). `text-white` = `--neutral-n00`.
- **Neutral family** = `slate-*` only. Never `gray-*` / `zinc-*` / `neutral-*` / `stone-*`.
- No pure `text-black`. Use `text-slate-900` as darkest.
- Max **2 semantic accent colors** per view.
- If skill color and status color both apply, status is the feedback signal; skill color becomes context only.

### 2.2 Typography
- 2 fonts only: `Plus Jakarta Sans` (heading) + `Inter` (body). `Noto Serif` reserved for quote/editorial.
- Body baseline = **14px** (`text-sm`). Never <13px.
- Heading font-weight ≥ body by ≥1 level.

### 2.3 Surface
- White-on-white elements: `border-slate-200` mandatory. Shadow supplements, never replaces border.
- Tab/segmented container: `bg-slate-50` (NOT `bg-slate-100`).
- Light-first. Dark allowed only for: overlay/scrim, media frame, small floating utility UI.
- For toolbars, side rails, icon stacks, and micro-navigation: start with transparent composition or one minimal shared shell. Do not box every child by default.
- Background color should signal containment, status, interaction, or elevation. If it adds no clear meaning, remove it.

### 2.4 Tailwind convention
- **Static classes only**. No `bg-${color}-600` (tree-shaken by scanner).
- No `bg-(--token)` or `var(--token)` in class attributes.
- No hex in class names. `bg-[#D42525]` → `bg-brand-600`.

### 2.5 English-skill semantic colors
| Skill | Class |
|-------|-------|
| Reading | `bg-emerald-*` / `text-emerald-600` |
| Listening | `bg-blue-*` / `text-blue-600` |
| Writing | `bg-amber-*` / `text-amber-600` |
| Speaking | `bg-rose-*` / `text-rose-600` (NOT brand red) |
| Full/Online Test | `bg-purple-*` / `text-purple-600` |
| AI Features | `bg-sky-*` / `text-sky-600` |

For full hard-rule list with rationale → `CODE-UI.md` §2. For "why these rules exist" → `../ds-guideline/DIRECTION.md`.

---

## 3. Context defaults (assume unless user says otherwise)

- **Framework**: React 19 + Tailwind CSS v4 + TypeScript 6
- **Target repo**: `dol-edu-playground` (runtime) or `DOL Wiki/site` (publish) — pick by task; ask if unclear
- **UI copy language**: Vietnamese
- **Code comments**: English
- **Theme**: Light-first (dark only per §2.3 carve-outs)
- **Component reuse**: check `ui-registry/` (DS-Token) and target repo's `src/components/ui/` BEFORE creating new
- **Aesthetic baseline**: warm-professional · soft-large radius · generous whitespace · subtle shadow

---

## 4. Task router — pick your detail file

Match your task → load the listed file(s). Don't load more than needed.

### 4.1 Building / modifying UI code (Tailwind + React)

→ **Primary**: [`CODE-UI.md`](https://dol-wiki.khoajak.design/ai/raw/ai-entry-code-ui.md) (this folder) — comprehensive code-UI router with hard rules, context defaults, full task table mapping to specific `CORE.md` sections, self-check (Q1-Q8 quantified gates), and anti-pattern scope scan.

For very fast lookup of one-off questions:

| Sub-task | Read |
|----------|------|
| Pick a Tailwind color class | `../ui-style-guide/CORE.md` §2 Color |
| Color deep mapping (18 families, edge cases) | `../../docs/tailwind-color-guideline.md` |
| External AI paste mode (Cursor / v0 / Figma Make) | `../../docs/ai-color-context.md` (self-contained color context) |
| Bridge architecture / TW v4 setup / dark mode / FAQ | `../../docs/DS-Tailwind-Bridge-Guide.md` |
| Why a color decision was made (philosophy) | `../../docs/color-system-rules.md` (34 Phase-1 rules) |
| Pattern lookup (named UI patterns) | `../pattern-registry.md` |
| Anti-pattern lookup (151 rows × 26 scopes) | `../anti-pattern-registry.md` |
| Exercise Data Entry style only / external AI paste | `../data-entry-authoring/STYLE-LANGUAGE.md` |
| Exercise Data Entry product/list lifecycle | `../data-entry-authoring/PRODUCT-LIFECYCLE.md` + `../ui-style-guide/data-entry.md` |
| Exercise Data Entry authoring workspace | `../data-entry-authoring/STYLE-LANGUAGE.md` + `../data-entry-authoring/AI-CODE.md` + `CODE-UI.md` |

### 4.2 AI-assisted Figma design (components, variables, organizer)

→ **Primary**: [`FIGMA-AI.md`](FIGMA-AI.md) (this folder) — entry for design work in Figma file (DS V2 components, variable binding, canvas organizer).

| Sub-task | Read |
|----------|------|
| Variable binding to Figma node | workspace skill `figma-bind-variable` |
| Component instantiation in Figma | workspace skill `figma-instantiate-component` |
| Human designer builds Data Entry in Figma | `../data-entry-authoring/STYLE-LANGUAGE.md` + `../data-entry-authoring/FIGMA-DESIGNER.md` |
| AI-assisted Exercise Data Entry screen/module design | `../data-entry-authoring/STYLE-LANGUAGE.md` + `../data-entry-authoring/AI-FIGMA.md` + `FIGMA-AI.md` |
| Analyze a large Figma page for Data Entry frames | `../data-entry-authoring/PATTERN-LEARNING.md` + `../data-entry-authoring/AI-FIGMA.md` §2-§5 before deep-reading frames |
| Build Figma screen from code/description | Codex skill `figma-generate-design` |
| Build/extend DS library (tokens, styles) | Codex skill `figma-generate-library` |
| Figma → code (1:1 implementation) | workspace skill `figma-implement-design` |

### 4.3 Cross-repo or polyrepo operation

| Task | Read |
|------|------|
| Refactor touching 2+ repos (DS-Token, EduDoc, Playground, Wiki) | workspace skill `.claude/skills/cross-repo-refactor/SKILL.md` |
| Token value change → propagate downstream | workspace skill `.claude/skills/dol-token-propagation/SKILL.md` |
| Audit UI quality | workspace skill `.claude/skills/ui-quality-audit/SKILL.md` |
| Anti-entropy sweep / stale lessons | workspace skill `/janitor` |
| Approve learnings → persist to ai-memory | workspace skill `/reflect` |

For full skill registry → workspace `SKILLS_REGISTRY.md`.

### 4.4 Understand "why a rule exists"

| Topic | Read |
|-------|------|
| Design philosophy / aesthetic intent / AI slop fingerprints | `../ds-guideline/DIRECTION.md` |
| Specific topic philosophy (typography / color / spacing / radius / shadow / composition) | `../ds-guideline/{topic}.md` |
| KID domain overrides (children's product) | `../kid/Design System Guideline/KID_DS_Basic_Guideline.md` |
| Color decision framework (34 rules from Phase 1 work) | `../../docs/color-system-rules.md` |

### 4.5 Fallback (task unclear)

→ Read [`../ui-style-guide/CORE.md`](https://dol-wiki.khoajak.design/ai/raw/ui-style-guide-core.md) **in full**. It is the single canonical UI reference (13 sections covering platform identity, color, typography, spacing, radius, surface, shadow, borders, components, motion, anti-patterns, KID overrides). Reading CORE.md alone is enough to build code that matches DOL standards.

---

## 5. Self-check before declaring done

> [!important]
> Run this checklist before saying "done." Skipping it is the most common cause of regressions.

Run through this compact checklist. For full quantified gates (Q1-Q8) and anti-pattern scope scan, see [`CODE-UI.md`](https://dol-wiki.khoajak.design/ai/raw/ai-entry-code-ui.md) §5.

**Color**
- [ ] No `bg-red-*` for brand accent? Use `bg-brand-*`.
- [ ] No `text-white` on vivid bg (500-600)? Use `text-on-inverse-primary`.
- [ ] No `gray-*` / `zinc-*` / `neutral-*` / `stone-*`? Use `slate-*`.
- [ ] Canonical shade `-600` used? No hex in classes?
- [ ] ≤2 semantic accent colors in view?
- [ ] Skill color does not override status color when both apply?

**Typography**
- [ ] Body ≥14px (`text-sm`)? Only Plus Jakarta + Inter?

**Surface**
- [ ] White card has `border-slate-200`? Tab uses `bg-slate-50`?
- [ ] Toolbar / utility rail avoids decorative dark paneling or per-child boxing unless the shell has a clear role?

**Tailwind**
- [ ] Static classes only? No `bg-${...}-600`? No `var(--token)` in className?

**Interaction**
- [ ] Hover/focus state on interactive elements? Click target ≥36px (44px primary)?

**Skill UI** (if applicable)
- [ ] Reading=emerald · Listening=blue · Writing=amber · Speaking=rose · Test=purple · AI=sky?

**Automation gates** (run if touching guideline files)
```bash
bash ../ui-style-guide/audit.sh <dir>          # 19-pattern grep check
python3 ../ui-style-guide/contrast-check.py    # WCAG AA validate
```
Audit clean ≠ design-correct. Q1-Q8 + anti-pattern scope still required ([`CODE-UI.md`](https://dol-wiki.khoajak.design/ai/raw/ai-entry-code-ui.md) §5.1-5.2).

---

## 6. File-tree map (where lives what)

### ✅ Always-relevant (load on demand based on task)

| File | Purpose |
|------|---------|
| `CODE-UI.md` (this folder) | Code-UI entry router — DETAILED |
| `FIGMA-AI.md` (this folder) | Figma-AI entry router — DETAILED |
| `../data-entry-authoring/README.md` | Exercise Data Entry authoring model and pattern inventory |
| `../data-entry-authoring/PRODUCT-LIFECYCLE.md` | Exercise list, create/edit/review/delete, assign/publish, record status |
| `../data-entry-authoring/PATTERN-LEARNING.md` | Evidence-first Figma page discovery, batch ledger, promotion rules |
| `../data-entry-authoring/STYLE-LANGUAGE.md` | Tool-neutral Data Entry style and spirit; safe for external AI/designer prompts |
| `../data-entry-authoring/FIGMA-DESIGNER.md` | Human-designer Figma assembly guide for Data Entry |
| `../data-entry-authoring/AI-CODE.md` | AI code guide for Data Entry data model, bindings, and reusable components |
| `../data-entry-authoring/AI-FIGMA.md` | AI Figma discovery/filtering/design workflow for Data Entry |
| `../ui-style-guide/CORE.md` | **Single canonical UI reference** (13 sections, fallback if uncertain) |
| `../ui-style-guide/{landing,practice,data-entry}.md` | Product-specific patterns extending CORE |
| `../../docs/DS-Tailwind-Bridge-Guide.md` | Narrative entry: TL;DR + architecture + setup + FAQ |
| `../../docs/tailwind-color-guideline.md` | Full 18-family color reference |
| `../../docs/ai-color-context.md` | Paste-into-AI-prompt color context (self-contained) |
| `../../docs/color-system-rules.md` | 34 color decision rules (Phase 1) |
| `../pattern-registry.md` | Named UI patterns index |
| `../anti-pattern-registry.md` | 151 anti-pattern rows (auto-generated) |

### 🔧 Tools (run, don't read)

```bash
bash ../ui-style-guide/audit.sh <dir>                      # grep violations
python3 ../ui-style-guide/contrast-check.py                # WCAG AA
python3 ../ui-style-guide/extract-anti-patterns.py         # regen registry
python3 figma-ai/tools/lookup.py <subcommand>              # Figma metadata CLI (TIER 0)
```

### 📚 Read for "why" only (philosophy / Figma intent)

| File | When |
|------|------|
| `../overview.md` | Human-facing design system orientation |
| `../ds-guideline/DIRECTION.md` | Design philosophy + AI slop fingerprints |
| `../ds-guideline/{typography,color,spacing,radius,shadow}.md` | Topic-specific Figma intent |
| `../kid/**` | KID domain UI |

### ❌ Don't read for normal UI tasks

`../../design-system-report/**` (historical reports), `../operations/**` (Figma MCP runbooks), `../../docs/alpha-decomposition-spec.md` (token math).

---

## 7. If you remember NOTHING else

1. **Hard rules § 2** — never break them. They're the safety floor.
2. **CORE.md** is the single canonical UI reference. When unsure, read it in full.
3. **Match task → router § 4** — load only what you need.
4. **Self-check § 5** before saying done.
5. **Cite anti-pattern by ID** when refusing/rewriting (e.g., `slop-02`, `core-11-color`).

---

## Boundary

- **In this folder**: orientation + routers + safety-net for AI agents
- **Not in this folder**: actual guideline content → `../ui-style-guide/` / `../ds-guideline/` / `../../docs/`
- **Human-facing overview**: `../overview.md`

## Scale-ready

When adding a new task domain (e.g., `DOC-EDIT.md`, `CONTENT-AUDIT.md`):
1. Create new entry file in this folder
2. Add a row to §4 task router
3. Keep each entry focused — don't merge domains

Pattern validated R6 (2026-04-23). Decision lesson: `ai-memory/lessons/ai-entry-pattern-vs-split-decision.md`.

---

<!-- ============ source: design-guideline/ai-entry/CODE-UI.md ============ -->


> 📌 **Authority**: This file is a **derived entry router**. The normative source for ALL executable UI rules is [`../ui-style-guide/CORE.md`](https://dol-wiki.khoajak.design/ai/raw/ui-style-guide-core.md). If any hard rule in §2 here disagrees with CORE.md, **CORE.md wins** - flag + fix CODE-UI.md to match. This file should only ROUTE + quick-reference, never diverge.

# DOL UI Guide - AI Code Entry

You are an AI agent building or modifying UI code for DOL Education platform. This is your entry point.

## 1. How to use this file

1. Read §2 Hard rules - non-negotiable for EVERY task
2. Read §3 Context defaults - assume these unless user says otherwise
3. Match your task in §4 Router → READ the listed CORE.md sections before coding
4. After coding, run §5 Self-check
5. For "why" questions, see §6 OUT-OF-SCOPE files

**If at any point you're unsure** → default to reading `../ui-style-guide/CORE.md` in full (single canonical reference).

### Match-and-refuse (meta-cognition)

If you catch yourself about to write ANY of the AI slop patterns (`../ds-guideline/DIRECTION.md` §10 "AI Slop fingerprints" table: `slop-01` side-stripe border, `slop-02` gradient text, `slop-03` nested cards, `slop-04` monotonous spacing, `slop-05` everything-centered, `slop-06` icon-tile-above, `slop-07` dark-glow, `slop-08` bounce-easing, `slop-09` layout-animation, `slop-10` body-typography-loud) - **STOP**, delete that line, and rewrite the element with a different structure entirely. Don't just swap values or tweak the same shape. Compliance with hard rules (§2) is necessary but NOT sufficient - passing §2 + hitting a slop pattern = still AI slop.

## 2. Hard rules (non-negotiable, safety net)

> [!warning]
> Non-negotiable. Violating any rule below = stop, ask, fix.

<dol_rules_color>
- Brand = `bg-brand-*` (custom class, NOT `bg-red-*`). `bg-red-*` = danger/error only.
- Canonical shade = `-600` (NOT Tailwind's default `-500`).
- Text on colored/inverse bg = `text-on-inverse-primary` (`--white-w100`). `text-white` = `--neutral-n00`.
- Neutral family = `slate-*` only. Never `gray-*` / `zinc-*` / `neutral-*` / `stone-*`.
- No pure `text-black` - use `text-slate-900` as darkest.
- Max 2 semantic accent colors per view.
- If skill color and status color both apply, status is the feedback signal; skill color becomes context only.
</dol_rules_color>

<dol_rules_typography>
- 2 fonts only: `Plus Jakarta Sans` (heading/display) + `Inter` (body/label). `Noto Serif` reserved for quote/editorial.
- Body baseline = 14px (`text-sm`). Never <13px.
- No font-weight drift: heading heavier than body by ≥1 level.
</dol_rules_typography>

<dol_rules_surface>
- **White-on-white elements: `border-slate-200` mandatory** (per `CORE.md` §8 + frontmatter - canonical source of truth). Shadow supplements, never replaces border.
- Tab/segmented container: `bg-slate-50` (NOT `bg-slate-100`).
- Light-first. Dark allowed ONLY for: overlay/scrim, media frame, utility floating UI.
</dol_rules_surface>

<dol_rules_tailwind>
- **Static classes only**. Never `bg-${color}-600` (tree-shaken by scanner).
- Never `bg-(--token)` or `var(--token)` in class attributes.
- No hex in class names (`bg-[#D42525]` → use `bg-brand-600`).
</dol_rules_tailwind>

### English skill semantic colors (when UI relates to language skill)
| Skill | Family | Class |
|-------|--------|-------|
| Reading | emerald | `bg-emerald-*` / `text-emerald-600` |
| Listening | blue | `bg-blue-*` / `text-blue-600` |
| Writing | amber | `bg-amber-*` / `text-amber-600` |
| Speaking | rose | `bg-rose-*` / `text-rose-600` (NOT brand red) |
| Full/Online Test | purple | `bg-purple-*` / `text-purple-600` |
| AI Features | sky | `bg-sky-*` / `text-sky-600` |

## 3. Context defaults (assume unless user says otherwise)

- **Framework**: React 19 + Tailwind CSS v4 + TypeScript
- **Target repo**: `dol-edu-playground` (runtime demo) or `DOL Wiki/site` (publish layer)
- **UI copy language**: Vietnamese
- **Code comments language**: English
- **Theme**: Light-first (dark only per §2 Surface rule)
- **Component reuse**: check existing components in target repo before creating new
- **Static classes**: always prefer over runtime string building
- **Aesthetic baseline**: warm-professional · soft-large radius · generous whitespace · subtle shadow. Khi task involves aesthetic choice (landing hero, new composition, user phản hồi "feels off") - READ `../ds-guideline/DIRECTION.md` §1 Triết lý + relevant §6-§9 trước khi code. Routine compliance task chỉ cần §2 Hard rules + §4 Router.

## 4. Task router

Match your task → READ the listed file(s) before writing code. For long files, use `Read` tool with offset+limit to target specific sections.

| Task | Read in order |
|------|---------------|
| Build button / input / form control | `../ui-style-guide/CORE.md` §1 Platform Identity + §3 Typography + §5 Radius + §9 Component Recipes |
| Build card / panel / surface | `../ui-style-guide/CORE.md` §6 Surface + §7 Shadow + §8 Borders |
| Build icon tile / badge / pill | `../ui-style-guide/CORE.md` §2 Color + §5 Radius (pill rule) + §9 |
| Build form / data entry surface | `../ui-style-guide/CORE.md` (full) + `../ui-style-guide/data-entry.md` |
| Build Exercise Data Entry list / product management | `../ui-style-guide/CORE.md` (full) + `../ui-style-guide/data-entry.md` + `../data-entry-authoring/PRODUCT-LIFECYCLE.md` |
| Build exercise Data Entry authoring workspace | `../ui-style-guide/CORE.md` (full) + `../ui-style-guide/data-entry.md` + `../data-entry-authoring/STYLE-LANGUAGE.md` + `../data-entry-authoring/AI-CODE.md` + `../data-entry-authoring/README.md` |
| Build landing / marketing page | `../ui-style-guide/CORE.md` (full) + `../ui-style-guide/landing.md` |
| Build practice / exercise / AI / test UI | `../ui-style-guide/CORE.md` (full) + `../ui-style-guide/practice.md` |
| Design score/result/leaderboard/attempt history | `../ui-style-guide/practice.md` §7 + product/spec confirmation for score bands, ranking metric, and counted attempts |
| Build catalog / listing section / ecosystem block / cross-product composition (≥4 items same shape) | `../pattern-registry.md` (named patterns index) → load detail recipe in linked file |
| Build navigation / header / menu | `../ui-style-guide/CORE.md` §1 + §6 + §9 |
| Pick colors (Tailwind class selection) | `../ui-style-guide/CORE.md` §2 Color |
| Deep color lookup (18-family mapping, edge families) | `../../docs/tailwind-color-guideline.md` |
| Typography detail (scale, line-height, by-context) | `../ui-style-guide/CORE.md` §3 |
| Spacing hierarchy / grouping / wireframe | `../ui-style-guide/CORE.md` §4 |
| Radius mapping by element height | `../ui-style-guide/CORE.md` §5 |
| Shadow & elevation tiers | `../ui-style-guide/CORE.md` §7 |
| Motion / transition / animation | `../ui-style-guide/CORE.md` §10 |
| Anti-patterns (full detail) | `../ui-style-guide/CORE.md` §11 |
| KID domain UI (overrides from General DS) | `../ui-style-guide/CORE.md` §12 + `../kid/Design System Guideline/KID_DS_Basic_Guideline.md` |
| External AI paste mode (Cursor/v0/Figma Make) | `../../docs/ai-color-context.md` (self-contained color context) |
| User asks "why" (rationale) | `../ds-guideline/DIRECTION.md` + relevant `../ds-guideline/{topic}.md` |
| Task unclear / fallback | `../ui-style-guide/CORE.md` (full - single canonical) |

## 5. Self-check before declaring done

> [!important]
> Run this checklist before saying "done." Skipping it is the most common cause of regressions.

Run through this checklist before saying "complete":

**Color**
- [ ] No `bg-red-*` used for brand accent? → must use `bg-brand-*`
- [ ] No `text-white` on vivid colored bg (500-600)? → use `text-on-inverse-primary`
- [ ] No `gray-*` / `zinc-*` / `neutral-*` / `stone-*` anywhere? → use `slate-*`
- [ ] Canonical shade `-600` used (not `-500`)?
- [ ] No hex in class names (`bg-[#...]`)?
- [ ] Max 2 semantic accent colors in view?
- [ ] If skill color and status color both apply, did status win and skill remain contextual?

**Typography**
- [ ] Body text ≥14px (`text-sm`)?
- [ ] Only Plus Jakarta Sans + Inter fonts used?
- [ ] Heading font-weight heavier than body by ≥1 level?

**Surface**
- [ ] White card/panel has `border-slate-200`? (`border-slate-100` = divider/track only, NOT white-on-white surface border)
- [ ] Tab/segmented container uses `bg-slate-50` (not `bg-slate-100`)?
- [ ] No full-page dark theme (except 3 exceptions)?

**Tailwind convention**
- [ ] No dynamic class `bg-${color}-600`? → static strings only
- [ ] No `bg-(--token)` or `var(--token)` in class attributes?

**Interaction**
- [ ] Hover/focus state defined for interactive elements?
- [ ] Click target ≥36px height (44px for primary actions)?
- [ ] Transitions use ease-out 150-300ms (not instant)?

**Skill-specific UI**
- [ ] Reading/Listening/Writing/Speaking/Test/AI uses correct color family (§2 Skill colors)?

### 5.1 Quantified gates (per-view counting - AI must verify with numbers)

DEFEND each value mentally before shipping. Counting forces commitment vs hand-wavy "looks fine".

| # | Metric | Target | Catches | Source |
|---|--------|--------|---------|--------|
| Q1 | Distinct shade-tinted color classes per view | ≤ 5 | over-coloring, no focal | CORE §11 typography row 04 |
| Q2 | Distinct gap-N / space-y-N values per view | ≥ 2 | slop-04 monotonous-spacing | DIRECTION §10 slop-04 |
| Q3 | Consecutive sibling blocks with `text-center` | ≤ 1 | slop-05 everything-centered | DIRECTION §10 slop-05 |
| Q4 | Card-in-card nesting depth | ≤ 1 | slop-03 nested-cards | DIRECTION §10 slop-03 |
| Q5 | Distinct font sizes per single card | ≤ 3 | CORE §11 typography row 01 | CORE §11 typography |
| Q6 | Brand-primary buttons per landing page | ≤ 2 | tone-discipline (hero + 1 mid-page max) | `../../../ai-memory/lessons/landing-tone-discipline.md` (workspace-level lesson) |
| Q7 | Big icon-tile-above heading instances per feature list | ≤ 0 | slop-06 icon-tile-above | DIRECTION §10 slop-06 |
| Q8 | CSS `transition` / `transition-property` declarations that animate layout props (width/height/padding/margin) | ≤ 0 | slop-09 layout-animation - NOTE: Tailwind `transition-all` alone is OK when only transform/opacity/color/shadow change (common card hover) | DIRECTION §10 slop-09 |

**Procedure**: After authoring, re-read your code and answer each Q with an integer. If any fails → return to anti-pattern table for that scope and rewrite.

### 5.2 Anti-pattern scope scan (per-task)

Before shipping any UI surface, locate the relevant `<dol_anti_pattern scope="...">` block(s) in the guideline and verify NO row matches your output:

| Task | Required scope check |
|------|----------------------|
| Landing page | `landing-1.7-hero` · `landing-2.5-feature-grid` · `landing-3.4-showcase` · `landing-4.4-testimonials` · `landing-5.4-cta` |
| Practice / Exercise UI | `practice-2.6-answer-cards` · `practice-4.5-timer-progress` · `practice-6.5-audio-tts` |
| Form / Data entry | `data-entry-3.7-validation` · `data-entry-4.6-multistep-flow` · `data-entry-5.6-rich-content` · `data-entry-6.8-data-tables` |
| Any code surface | `core-11-layout` · `core-11-color` · `core-11-typography` · `core-11-spacing-depth` · `core-11-interaction` · `core-11-tailwind` + `direction-10-ai-slop-universal` |

Cite specific row when explaining a refusal: e.g., "Refused gradient hero per `direction-10-ai-slop-universal#slop-02`".

### 5.3 Automation

```bash
bash ../ui-style-guide/audit.sh <dir>                      # grep violations (19 patterns; clean = green light, NOT proof)
python3 ../ui-style-guide/contrast-check.py                # WCAG AA validation
python3 ../ui-style-guide/extract-anti-patterns.py         # regenerate DOL-DS-token/design-guideline/anti-pattern-registry.md
python3 ../ui-style-guide/extract-anti-patterns.py --check # CI gate - fails if registry out-of-sync với source
```

**Single-file lookup** for all 151 anti-pattern rows across 26 scopes:
→ `DOL-DS-token/design-guideline/anti-pattern-registry.md` (auto-generated)

`audit.sh` clean ≠ design-correct. Q1-Q8 + scope scan still required - audit catches static-grep-detectable patterns only.

## 6. File tree - scope map

### ✅ IN SCOPE (read these for code UI tasks)

| File | Purpose |
|------|---------|
| `../ui-style-guide/CORE.md` | **Primary canonical** - 13 sections, Tailwind recipes |
| `../ui-style-guide/landing.md` | Landing / marketing patterns |
| `../ui-style-guide/practice.md` | Exercise / AI / Test patterns |
| `../ui-style-guide/data-entry.md` | Form / input patterns |
| `../data-entry-authoring/PRODUCT-LIFECYCLE.md` | Exercise Data Entry list/product lifecycle model |
| `../data-entry-authoring/PATTERN-LEARNING.md` | Figma evidence ledger and promotion rules for DE pattern learning |
| `../data-entry-authoring/STYLE-LANGUAGE.md` | Tool-neutral Data Entry style and spirit |
| `../data-entry-authoring/AI-CODE.md` | AI code guide for Data Entry data model, answer binding, reusable component candidates |
| `../data-entry-authoring/README.md` | Shared Data Entry authoring model and pattern inventory |
| `../../docs/tailwind-color-guideline.md` | 18-family color deep reference |
| `../../docs/ai-color-context.md` | Rút gọn cho external AI paste |
| `../ui-style-guide/audit.sh` | Grep-based violation checker |
| `../ui-style-guide/contrast-check.py` | WCAG AA validator |
| `../ui-style-guide/spec.sh` | JSON export of tokens + hardRules |

### ❌ OUT OF SCOPE (do NOT read for code UI tasks)

| File | Why out | When to read |
|------|---------|--------------|
| `../ds-guideline/DIRECTION.md` | Design philosophy (Why layer) | User asks "why rule X exists" |
| `../ds-guideline/*.md` (topic files) | Figma semantic intent | User asks rationale for specific topic |
| `../../design-system-report/**` | Historical reports | Never for active work |
| `../../docs/color-system-rules.md` | Token math infrastructure (34 rules) | Never for code UI |
| `../../docs/alpha-decomposition-spec.md` | Alpha derivation spec | Never for code UI |
| `../operations/**` | Figma MCP bridge runbook | Never for code UI |
| `../kid/**` (except Design System Guideline) | KID-specific assets | KID domain task only |

## Related entries

- `README.md` - this folder's purpose + index
- (future) `FIGMA-AI.md` - entry for AI-assisted Figma design work
- (future) `DOC-EDIT.md` - entry for AI-assisted documentation editing

---

**TL;DR**: §2 Hard rules + §3 Context always apply. §4 Router maps your task → specific CORE.md sections. §5 Self-check before done. §6 out-of-scope = don't read unless user asks rationale.

---

<!-- ============ source: docs/ai-color-context.md ============ -->


# DOL Design System - AI Color Context

Paste this into any AI coding tool (Figma Make, Google AI Studio, v0, Cursor, etc.) as system prompt or context file so the AI uses DOL colors correctly.

---

## §1 Color System Rules

You are building UI for DOL Education platform using **Tailwind CSS v4**. All TW classes map to DS-Token CSS vars at build time - you write standard Tailwind, the build handles theming.

### Core convention

- **Numeric scale 50-950** for all colors (TW standard naming)
- **DOL canonical = `-600`** (NOT `-500` like TW default). DOL brand chuẩn = `bg-brand-600`.
- **Opacity modifiers** (`/80`, `/50`) work on all colors (TW v4 `color-mix()`)
- **Intent mapping:**
  - Brand = `bg-brand-*` (custom class - NOT `bg-red-*`)
  - Error/Danger = `bg-red-*`
  - Success = `bg-green-*`
  - Warning = `bg-amber-*`
  - Info = `bg-blue-*`
  - Special = `bg-purple-*`
  - **AI features / Smart actions = `bg-sky-*`** (per CORE §2.4 + playground code convention)
- **English skill semantic colors** (per CORE §2.4): Reading=`emerald-*`, Listening=`blue-*`, Writing=`amber-*`, Speaking=`rose-*`, Full Test=`purple-*`, AI=`sky-*`

---

## §2 Complete TW → DS-Token Mapping Table

Every Tailwind class below resolves to a DS-Token CSS var. Use these class prefixes instead of raw DS variable names in `className`.

### Shade scale mapping

| TW shade | DS shade | Role |
|----------|----------|------|
| `50` | `05` | Dimmest background |
| `100` | `10` | Soft background |
| `200` | `20` | Light accent / border |
| `300` | `40` | Medium-light |
| `400` | `60` | Medium |
| `500` | `80` | Medium-dark |
| **`600`** | **`100`** | **Canonical - brand/primary usage** |
| `700` | `120` | Hover / darker |
| `800` | `140` | Pressed / deep |
| `900` | `160` | Very dark |
| `950` | `180` | Darkest |

### Color families - ✅ SAFE to use

| TW class prefix | DS-Token family | Identity hex (-600) | Intent / khi nào dùng |
|----------------|-----------------|--------------------|-----------------------|
| **`brand-*`** | `primary-pr` | `#D42525` | DOL brand red - logo, CTA chính, accent |
| **`danger-*`** | `red-r` | `#E24B19` | Semantic alias for error/delete/alert |
| **`success-*`** | `green-g` | `#329546` | Semantic alias for correct/complete |
| **`warning-*`** | `yellow-y` | `#E0A011` | Semantic alias for caution/deadline |
| **`info-*`** | `blue-b` | `#2B52D4` | Semantic alias for link/active/info |
| **`special-*`** | `purple-p` | `#5B37D2` | Semantic alias for premium/gamification |
| `slate-*` | `neutral-n` | `#6C7885` | Text, borders, backgrounds - primary neutral |
| `red-*` | `red-r` | `#E24B19` | Danger/error. Brand is `brand-*`, not `red-*` |
| `orange-*` | `orange-or` | `#FB8D15` | True orange. Error is `red-*` / `danger-*` |
| `amber-*` | `yellow-y` | `#E0A011` | Warning, warm accent |
| `yellow-*` | `golden-gd` | `#DCB700` | Gold tones, award, achievement |
| `green-*` | `green-g` | `#329546` | Success, positive, nature |
| `blue-*` | `blue-b` | `#2B52D4` | Info, link, active state |
| `sky-*` | `deepsky-ds` | `#27A3CD` | **AI features / Smart actions** (per CORE §2.4) - primary class for AI UI |
| `cyan-*` | `wave-blue-wb` | `#00B3FF` | Bright cyan tech accent - alternative palette, prefer `sky-*` for AI features |
| `teal-*` | `teal-tl` | `#4DBAA9` | Teal accent |
| `purple-*` | `purple-p` | `#5B37D2` | Special, premium |
| `violet-*` | `purple-p` | `#5B37D2` | Alias of purple |
| `indigo-*` | `navy-blue-nb` | `#2FA5FF` | Navy/deep blue accent |
| `fuchsia-*` | `magenta-ma` | `#BF2598` | Magenta accent |
| `pink-*` | `pink-pi` | `#D94B67` | Pink, feminine accent |
| `rose-*` | `pink-pi` | `#D94B67` | Speaking skill / rose accent |
| `lime-*` | `lemon-le` | `#BBD015` | Lemon/lime accent, non-standard DS scale |
| `emerald-*` | `green-g` | `#329546` | Alias of green |
| `gray-*` | `neutral-n` | - | Alias of slate (prefer `slate-*`) |
| `zinc-*` | `neutral-n` | - | Alias of slate (prefer `slate-*`) |
| `stone-*` | `neutral-n` | - | Alias of slate (prefer `slate-*`) |
| `neutral-*` | `neutral-n` | - | Alias of slate (prefer `slate-*`) |

### DOL-specific first-class families

Use these when a DS color does not map cleanly to a standard Tailwind family.

| TW class prefix | DS-Token family | Identity hex (-600) | Intent / khi nào dùng |
|----------------|-----------------|--------------------|-----------------------|
| `cabaret-*` | `cabaret-ca` | `#D75F1E` | Cabaret / streak accent |
| `golden-*` | `golden-gd` | `#DCB700` | Golden highlight, awards |
| `deepsky-*` | `deepsky-ds` | `#27A3CD` | Explicit deepsky access |
| `wave-blue-*` | `wave-blue-wb` | `#00B3FF` | Wave blue / AI identity accent |
| `navy-blue-*` | `navy-blue-nb` | `#2FA5FF` | Navy/deep blue accent |
| `magenta-*` | `magenta-ma` | `#BF2598` | Magenta accent |
| `pink-pi-*` | `pink-pi` | `#D94B67` | Explicit DS pink access |
| `lemon-*` | `lemon-le` | `#BBD015` | Explicit lemon access |
| `paper-*` | `paper-pp` | `#DC934E` | Warm reading/paper accent |
| `dol-orange-*` | `orange-or` | `#FB8D15` | Legacy explicit true-orange alias |
| `bronze-*` | `bronze-bz` | `#EC983B` | Bronze / achievement tier |
| `plum-*` | `plum-pl` | `#CF91DA` | Plum accent |

### Special values

| TW class | DS-Token var | Behavior |
|----------|-------------|----------|
| `white` | `--neutral-n00` | Theme-aware: white in light, dark in dark mode |
| `black` | `--neutral-n200` | Theme-aware: dark in light, white in dark mode |
| `text-on-inverse-primary` | `--white-w100` | Always `#FFFFFF` - for text on colored bg |
| `text-on-inverse-secondary` | `--white-w70` | Always `rgba(255,255,255,0.7)` |
| `text-on-inverse-disabled` | `--white-w30` | Always `rgba(255,255,255,0.3)` |

### Raw DS token names are not Tailwind class prefixes

Do not write raw token names as classes (`bg-primary-pr100`, `bg-cabaret-ca100`, `text-red-r100`). Use the mapped Tailwind family instead (`bg-brand-600`, `bg-cabaret-600`, `text-red-600`).

Alpha families (`*-alpha-*`) are not exposed as Tailwind numeric families. Use opacity modifiers (`bg-brand-600/20`) first; use `var(--primary-alpha-pra50)` only in CSS when a semantic alpha token is explicitly required.

---

## §3 Standard Tailwind Usage

### Text hierarchy (neutral)

| Tailwind | Dùng cho |
|----------|----------|
| `text-slate-950` | Hero heading (emphasis only) |
| `text-slate-900` | Body text, card title, page title (default) |
| `text-slate-700` | Subtitle, secondary info, metadata |
| `text-slate-600` | Helper text, dim info, category label |
| `text-slate-500` | Placeholder, hint, disabled text |

### Surface hierarchy

| Tailwind | Dùng cho |
|----------|----------|
| `bg-white` | Card, modal, main content |
| `bg-slate-50` | Page background, subtle section, tab container |
| `bg-slate-100` | Skeleton, hover state, input background |
| `border-slate-200` | Default white surface border |
| `border-slate-100` | Subtle divider only |

### Text on colored backgrounds

CRITICAL: Use `text-on-inverse-primary` (always white) instead of `text-white` (swaps in dark mode).

```
text-on-inverse-primary    = always #FFFFFF (for text on brand/status bg)
text-on-inverse-secondary  = always rgba(255,255,255,0.7)
text-white                 = theme-aware white (becomes dark in dark mode!)
```

| Background | Text class | Reason |
|-----------|------------|--------|
| Vivid (500-600): `bg-brand-600`, `bg-blue-600` | `text-on-inverse-primary` | Fixed white, doesn't swap |
| Dark neutral (700+): `bg-slate-800` | `text-slate-50` or `text-white` | Theme token, swaps in dark |
| Light tint (50-200): `bg-blue-50` | `text-blue-700` or `text-slate-900` | Dark text on light bg |

### Focus & interaction

- Focus ring: `ring-blue-500` (NOT brand color)
- Shadow: `shadow-xs` (tiny), `shadow-sm` (small), `shadow-md` (medium), `shadow-lg` (large)

---

## §4 Common Patterns

```html
<!-- Card (flat, border-only) -->
<div class="bg-white border border-slate-200 rounded-xl">

<!-- Primary (brand) button -->
<button class="bg-brand-600 text-on-inverse-primary hover:bg-brand-700 rounded-lg px-4 py-2">

<!-- Secondary button -->
<button class="bg-white text-slate-900 border border-slate-200 hover:bg-slate-50 rounded-lg px-4 py-2">

<!-- Success badge -->
<span class="bg-green-50 text-green-600 px-2 py-1 rounded-full text-xs font-medium">

<!-- Error alert -->
<div class="bg-red-50 border border-red-100 text-red-700 p-3 rounded-lg">

<!-- Warning banner -->
<div class="bg-amber-50 border border-amber-100 text-amber-800 p-3 rounded-lg">

<!-- Header on brand bg -->
<header class="bg-brand-600 text-on-inverse-primary p-6">
  <h1 class="text-xl font-bold">Title</h1>
  <p class="text-on-inverse-secondary text-sm">Subtitle</p>
</header>

<!-- Input -->
<input class="border border-slate-200 bg-white text-slate-900 placeholder:text-slate-500
  focus:border-blue-600 focus:ring-2 focus:ring-blue-500 rounded-lg px-3 py-2">
```

---

## §5 DO NOT

- ❌ `bg-(--token)` or `var(--token)` in class attributes
- ❌ `bg-red-*` for brand color → use `bg-brand-*`
- ❌ `bg-orange-*` for error → use `bg-red-*` or `bg-danger-*`
- ❌ `text-white` for fixed-white on colored bg → use `text-on-inverse-primary`
- ❌ `gray-*`, `zinc-*`, `neutral-*` → use `slate-*`
- ❌ Hardcoded hex in class names (`bg-[#D42525]`)
- ❌ Semantic level names (`bg-brand-primary`) → use numeric (`bg-brand-600`)
- ❌ `-500` as canonical → DOL canonical is **`-600`**
- ❌ `shadow-sm` for tiny shadow → TW v4 renamed: use `shadow-xs` (tiny), `shadow-sm` (small)
- ❌ Raw DS token names as TW classes (`bg-cabaret-ca100`, `bg-primary-pr100`) → use mapped families (`bg-cabaret-600`, `bg-brand-600`)

---

## §6 Config Files Quick Reference

| What | Playground | Wiki | DS-Token (source) |
|------|-----------|------|-------------------|
| TW config | `tailwind.config.cjs` | `tailwind.config.ts` | - |
| Token CSS | `styles/tokens/tokens.generated.css` | `src/styles/tokens/tokens.generated.css` | `tokens/v4/color-base.css` |
| Remap CSS | `styles/tokens/palette-remap.generated.css` | - (inline in TW config) | `dist/css/dol-palette-remap.css` |
| Token regen | `npm run tokens:gen` | `npm run tokens:gen` | `npm run build` |
| Full color reference | - | - | `docs/tailwind-color-guideline.md` |
| Color system rules | - | - | `docs/color-system-rules.md` |
| UI style guide | - | - | `../ui-style-guide/CORE.md` (this repo) |

**Adding a new color family to a repo:**
1. Add mapping entry in the repo's `tailwind.config` (cjs/ts)
2. Run `npm run tokens:gen` - tree-shaker auto-includes referenced vars
3. Verify with build

---

<!-- ============ source: design-guideline/ui-style-guide/CORE.md ============ -->

<!-- AI_RULES:dol-core-style-guide:v1 -->

# DOL Design System - Core Style Guide

> **Scope**: Tất cả code surfaces - Playground, Wiki, HTML prototypes.
> **Consumer chính**: AI agents sinh code Tailwind CSS.
> File này là entry point duy nhất - đọc file này là đủ để build UI đúng chuẩn DOL.

Product-specific patterns (extends CORE):
- [`practice.md`](practice.md) - Exercise, Exercise AI, Online Test
- [`landing.md`](landing.md) - Trang giới thiệu, showcase
- [`data-entry.md`](data-entry.md) - Nhập liệu tạo bài tập

### Fallback Policy

Mỗi section trong product files có `status`:
- **done**: Pattern canonical - build đúng theo recipe.
- **draft**: Pattern hợp lý nhưng chưa final - dùng được, có thể thay đổi.
- **skeleton**: Chưa có pattern - compose từ CORE.md primitives (§4-§9). **KHÔNG invent pattern mới.**

Khi gặp section `skeleton` hoặc topic chưa được cover: dùng component recipes (§9) + spacing (§4) + radius (§5) + shadow (§7) để compose. Không tạo convention mới ngoài scope CORE.

---

## §1 Platform Identity

**Triết lý**: Sáng, rõ, premium vừa đủ.

| Nguyên tắc | Ý nghĩa |
|-------------|----------|
| Pure White Boundary-less | Nền trắng `bg-white`. Không chia lô section bằng dải xám luân phiên |
| Depth via border + shadow | White-on-white bắt buộc `border-slate-200`. Shadow bổ trợ (xem §7) |
| Light-first | Page chính nền sáng. Không dark theme (trừ §6.3 exceptions) |
| Simple first | Hierarchy từ spacing + typography, không từ hiệu ứng |
| One system, many accents | Cùng shape language, khác accent theo domain |
| Reuse before invent | Dùng pattern có sẵn trước khi tạo biến thể mới |

### 1.1 Font System

| Role | Font | Weight mặc định |
|------|------|------------------|
| Heading, Display | Plus Jakarta Sans | `font-bold` đến `font-black` |
| Body, UI, Label | Inter | `font-normal` đến `font-semibold` |
| Quote (editorial only) | Noto Serif | `font-normal` đến `font-semibold` |

**Hard rule**: Chỉ 2 font chính (Plus Jakarta Sans + Inter). Không thêm font thứ 3 trong bất kỳ surface nào.

### 1.2 Brand & Intent Colors

| Intent | Class prefix | Canonical (-600) | Dùng cho |
|--------|-------------|-------------------|----------|
| **Brand** | `bg-brand-*` | `#D42525` | Logo, CTA chính, brand accent |
| **Danger/Error** | `bg-red-*` | - | Error, delete, dangerous action |
| **Success** | `bg-green-*` | - | Correct, positive, complete |
| **Warning** | `bg-amber-*` | - | Approaching deadline, review needed |
| **Info** | `bg-blue-*` | - | Active state, progress, link |
| **Special** | `bg-purple-*` | - | Premium, gamification, special feature |

- Canonical shade = **`-600`** (NOT `-500` như TW default)
- `bg-brand-*` là custom class - **KHÔNG dùng `bg-red-*` cho brand**
- Brand Red ≠ Danger. Brand = CTA/accent. Danger = `bg-red-*` (error/delete)
- Semantic aliases: `bg-danger-*`, `bg-success-*`, `bg-warning-*`, `bg-info-*`, `bg-special-*`

### 1.3 UI Simplification Principles

- Giảm chrome trước khi thêm component: bỏ box/badge/divider/copy dư trước khi thêm hiệu ứng.
- 1 shell per function group. Tránh card trong card, box trong box.
- Utility UI mặc định boundary-light: ưu tiên spacing + alignment trước, surface sau.
- Toolbar, side rail, icon stack, mini-nav: không dựng dark/tinted panel hoặc box cho từng child nếu layout vẫn đọc rõ khi bỏ lớp đó.
- Quick actions: 1 hàng ngang. Overflow → affordance "xem thêm", không bung multi-row.
- Text chỉ truncate khi vượt viewport width, không cắt theo quota ký tự cố định.
- Surface rối → bỏ wrapper/copy lặp trước, không siết typography hay nhồi biến thể màu.

---

## §2 Color

### 2.1 Text Hierarchy (Neutral)

| Tailwind | Dùng cho |
|----------|----------|
| `text-slate-900` | Body paragraph, card title, page title (default cho mọi text chính) |
| `text-slate-700` | Subtitle, secondary info, metadata |
| `text-slate-600` | Helper text, dim info, category label |
| `text-slate-500` | Placeholder, hint, disabled text |

> Hero heading cần nhấn thêm → `text-slate-950`. Nhưng `text-slate-900` đủ cho hầu hết trường hợp.
> Không dùng pure `text-black`. `slate-900` là darkest cho body text.

### 2.2 Text on Inverse/Dark Surfaces

| Class | Giá trị | Khi nào |
|-------|---------|---------|
| `text-on-inverse-primary` | `--white-w100` | Fixed white text/icon trên colored/inverse bg |
| `text-on-inverse-secondary` | `--white-w70` | Fixed white secondary text trên colored/inverse bg |

**Khi nào dùng on-inverse vs text-white:**

| Nền background | Text | Lý do |
|---------------|------|-------|
| Colored/inverse bg cần fixed white: `bg-brand-600`, `bg-blue-600`, CTA colored surface... | `text-on-inverse-primary` | `--white-w100` |
| Theme-aware neutral pairing cần đổi theo theme: `bg-slate-900`, neutral solid, page chrome... | `text-white` | `--neutral-n00`; auto-flip theo palette-remap, không phải fixed white |
| Light neutral (50-200): `bg-slate-100`, `bg-slate-50`... | `text-slate-700` hoặc `text-slate-500` | Nền nhạt → text cần đậm hơn bg để đủ contrast |
| Light tint (50-400): `bg-blue-50`, `bg-brand-100`... | Dark text (`text-slate-*` hoặc `text-{color}-700`) | Nền sáng → text tối |

**Lưu ý contrast** (locked 2026-04-25, R23 a11y decision):

| Family shade | `on-inverse-primary` (white) contrast | Allowed scope |
|-------------|---------------------------------------|---------------|
| `brand-600`, `red-600`, `blue-600`, `purple-600`, `rose-600` | ✅ AA normal (≥ 4.5:1) | Unrestricted - body text, button labels, badges |
| `success-600` / `green-600` / `emerald-600` | ⚠️ AA **large text only** (≥ 3:1, < 4.5:1) | **Button labels ≥ 14px semibold ONLY**. For body/caption → `text-{color}-700` |
| `warning-600` / `amber-600` | ⚠️ AA **large text only** | **Button labels ≥ 14px semibold ONLY**. For body text use `text-amber-700` |
| `sky-600` | ⚠️ AA **large text only** | **Button labels ≥ 14px semibold ONLY**. Body → `text-sky-700` |
| `amber-500` / `yellow-500` | ❌ Fails even AA large on white | Never use with white text - use dark text on light amber bg instead |

**Rule of thumb**: if text-size < 14px OR font-weight < semibold → use shade `-700` for the 4 flagged families (success, amber, sky, emerald). If text-size ≥ 14px AND semibold (typical button label) → shade `-600` + `on-inverse-primary` OK.

**Why locked this way**: the 4 families' `-600` shades are visually part of DOL canonical palette; switching to `-700` universally would shift brand perception. Restricting to button-label-only context preserves visual identity while meeting WCAG 2.1 AA for reasonable text sizes.

### 2.3 Status Color Patterns

Mỗi status color có 3 usage levels:

| Level | Pattern | Success | Error | Warning | Info |
|-------|---------|---------|-------|---------|------|
| Dim bg | `bg-{color}-50` | `bg-green-50` | `bg-red-50` | `bg-amber-50` | `bg-blue-50` |
| Text | `text-{color}-600` | `text-green-600` | `text-red-600` | `text-amber-600` | `text-blue-600` |
| Strong bg | `bg-{color}-600` | `bg-green-600` | `bg-red-600` | `bg-amber-600` | `bg-blue-600` |
| Border | `border-{color}-100` | `border-green-100` | `border-red-100` | `border-amber-100` | `border-blue-100` |

### 2.4 English Skill Semantic Colors

Bảng màu cố định - apply cho tag, badge, icon, section tint liên quan skill:

| Skill | TW Family | Text | Bg Tint | Strong Bg |
|-------|-----------|------|---------|-----------|
| Reading | emerald | `text-emerald-600` | `bg-emerald-50` | `bg-emerald-600` |
| Listening | blue | `text-blue-600` | `bg-blue-50` | `bg-blue-600` |
| Writing | amber | `text-amber-600` | `bg-amber-50` | `bg-amber-600` |
| Speaking | rose | `text-rose-600` | `bg-rose-50` | `bg-rose-600` |
| Full/Online Test | purple | `text-purple-600` | `bg-purple-50` | `bg-purple-600` |
| AI Features | sky | `text-sky-600` | `bg-sky-50` | `bg-sky-600` |

> Speaking dùng **rose** (NOT brand red). Brand red chỉ cho CTA/logo.

### 2.5 Domain Accent

| Domain | Accent Color | CTA Class |
|--------|-------------|-----------|
| IELTS | Red (brand) | `bg-brand-600` |
| SAT | Cyan | `bg-cyan-600` |
| TOEIC | Blue/Navy | `bg-blue-700` |
| COMM | Orange | `bg-orange-600` |

Accent dùng cho CTA và nhấn owner - không biến cả section thành gradient.

### 2.6 Neutral Backgrounds & Borders

| Class | Dùng cho |
|-------|----------|
| `bg-white` | Page base, card base |
| `bg-slate-50` | Subtle tint (tab bar, segmented control) |
| `bg-slate-100` | Progress track, small icon bg, hover state |
| `border-slate-200` | **Default border** for cards/inputs/panels (white-on-white). Hover → `border-slate-300`. See §8.1. |
| `border-slate-100` | Lighter divider (section-to-section) hoặc subtle separator. See §8.2. |

### 2.7 DO NOT

- ❌ `bg-red-*` cho brand → `bg-brand-*`
- ❌ `text-white` trên vivid bg (500-600) → `text-on-inverse-primary`
- ❌ `text-on-inverse-primary` trên `bg-slate-900` neutral solid → `text-white`
- ❌ `gray-*`, `zinc-*`, `neutral-*` → `slate-*`
- ❌ Hardcode hex trong class names
- ❌ `-500` là canonical → DOL canonical = `-600`
- ❌ Brand red cho error/danger (brand ≠ danger)
- ❌ >2 semantic accent colors cùng lúc trong 1 view
- ❌ Accent color cho body text dài

---

## §3 Typography

### 3.1 Size Scale

| Role | Size | Tailwind | Weight |
|------|------|----------|--------|
| Display xl | 64px | `text-[64px]` | `font-black` |
| Display lg | 56px | `text-[56px]` | `font-bold` to `font-black` |
| Display md | 48px | `text-5xl` | `font-bold` |
| Display sm | 40px | `text-[40px]` | `font-bold` |
| Heading 2xl | 32px | `text-[32px]` | `font-bold` |
| Heading xl | 28px | `text-[28px]` | `font-bold` |
| Heading lg | 24px | `text-2xl` | `font-bold` |
| Heading md | 20px | `text-xl` | `font-semibold` to `font-bold` |
| Heading sm | 18px | `text-lg` | `font-semibold` |
| Body lg | 16px | `text-base` | `font-normal` |
| **Body base** | **14px** | **`text-sm`** | **`font-normal`** |
| Body sm | 12px | `text-xs` | `font-normal` |
| Label | 12px | `text-xs uppercase tracking-wide` | `font-semibold` |

> Body base (14px / `text-sm`) là default cho mọi body text.

### 3.2 Line-Height

| Context | Tailwind | Khi nào |
|---------|----------|--------|
| Decoration 1-line only | `leading-none` | Display decoration, không cho content |
| Heading 1-2 lines | `leading-snug` | Default cho heading |
| Body dense UI | `leading-tight` | Tables, chips, compact metadata |
| Body default | `leading-normal` | Standard paragraphs (default) |
| Body reading 3+ lines | `leading-relaxed` | Article, helper text, long copy |

### 3.3 Typography by Context

| Context | Size | Weight | Line-Height |
|---------|------|--------|-------------|
| Card title | `text-lg` | `font-bold` | `leading-snug` |
| Card description | `text-sm` | `font-normal` | `leading-normal` |
| Card metadata | `text-xs` | `font-medium` | `leading-tight` |
| Section heading | `text-2xl` | `font-bold` | `leading-snug` |
| Page title | `text-[28px]` to `text-[32px]` | `font-bold` | `leading-snug` |
| Hero title | `text-[40px]` to `text-[56px]` | `font-bold` to `font-black` | `leading-tight` |
| Button label | `text-sm` | `font-semibold` | - |
| Form label | `text-xs uppercase tracking-wide` | `font-semibold` | - |
| Helper/error text | `text-xs` to `text-sm` | `font-normal` | `leading-normal` |
| Utility surface (logged-in) | `text-sm` (14px) | `font-normal` | `leading-normal` |

### 3.4 Rules

- Body baseline logged-in surfaces: **14px** (`text-sm`). Không upscale lên 15-16px.
- AI inline headings giữ 14px - hierarchy qua `font-weight` + spacing.
- Max **3 font-size levels per card**: title → body → label.
- Heading phải nặng hơn body ≥1 weight level.
- Paragraph copy ≥14px (never <13px - accessibility).
- Metric values (%, band, count) được upscale. Topic text giữ body scale.
- Micro-label có thể uppercase + `tracking-wide`, nhưng không lạm dụng.

---

## §4 Spacing

**Nguyên tắc**: Generous - thoáng hơn mặc định. Spacing tạo hierarchy, không phải dividers.

### 4.1 Hierarchy Levels

| Level | Quan hệ | Gap | Ví dụ |
|-------|---------|-----|-------|
| **A** Atom | Icon+label, inline elements | `gap-1.5` to `gap-2` (6-8px) | Icon cạnh text trong button |
| **B** Molecule | Label+input, title+subtitle | `gap-2` to `gap-4` (8-16px) | Form field group |
| **C** Organism | Header+content, card internals | `gap-4` to `gap-6` (16-24px) | Content stack trong card |
| **D** Section | Block ↔ block, sections | `gap-8` to `gap-12` (32-48px) | Page-level sections |

### 4.2 Common Defaults

| Context | Tailwind | Giá trị |
|---------|----------|---------|
| Icon+text in button | `gap-2` | 8px |
| Related items in group | `gap-3` | 12px |
| Card content stack | `gap-4` | 16px |
| Standard card padding | `p-5` | 20px |
| Large card/modal padding | `p-6` | 24px |
| Between card groups | `gap-6` to `gap-8` | 24-32px |
| Page section gap | `gap-10` to `gap-16` | 40-64px |
| Page padding mobile | `px-4` | 16px |
| Page padding tablet | `px-6` | 24px |
| Page padding desktop | `px-8` to `px-12` | 32-48px |
| Max content width | `max-w-6xl mx-auto` | 1152px |

### 4.3 Rules

- Spacing giữa groups > spacing trong group → hierarchy rõ ràng.
- Padding top/bottom ≈ hoặc > left/right → cân bằng visual.
- Multiples of 4px. Không dùng arbitrary odd values.
- Không dùng same spacing cho mọi level.
- Min 12px (`gap-3`) giữa unrelated elements.
- Ưu tiên spacing để phân tách → chỉ dùng divider khi spacing chưa đủ.

---

## §5 Radius

**Nguyên tắc**: Soft-large radius - friendly, modern. Radius tăng tỷ lệ theo element size.

### 5.1 Controls (Buttons, Inputs)

| Element Height | Tailwind | px |
|----------------|----------|----|
| h-6 (24px) | `rounded-md` | 6px |
| h-8 (32px) | `rounded-lg` | 8px |
| h-9 (36px) | `rounded-xl` | 12px |
| h-10 (40px) | `rounded-xl` | 12px |
| h-12 (48px) | `rounded-2xl` | 16px |
| h-14 (56px) | `rounded-[20px]` | 20px |
| h-16 (64px) | `rounded-3xl` | 24px |

### 5.2 Surfaces (Cards, Containers)

| Type | Tailwind | px |
|------|----------|----|
| Standard card | `rounded-xl` | 12px |
| Feature/elevated card | `rounded-2xl` | 16px |
| Large section block | `rounded-3xl` | 24px |

### 5.3 Overlays (Modals, Dropdowns)

| Type | Tailwind | px |
|------|----------|----|
| Tooltip / small popup | `rounded-lg` | 8px |
| Dropdown / Popover | `rounded-xl` | 12px |
| Modal | `rounded-2xl` | 16px |
| Large modal / Bottom sheet | `rounded-3xl` | 24px |

### 5.4 Pill

`rounded-full` chỉ dùng cho: chip, capsule tag, status pill, avatar, circle control.
**KHÔNG** `rounded-full` cho card, modal, input, button thường.
Micro-badge / data cell nhỏ có thể dùng corner sắc hơn (e.g., `rounded-md`).

---

## §6 Surface & Background

### 6.1 Surface Hierarchy (4 levels)

| Level | Background | Depth | Dùng cho |
|-------|-----------|-------|----------|
| 1 - Page | `bg-white` | Flat, boundary-less | Nền page, không chia lô |
| 2 - Card | `bg-white` + border + shadow | Nổi nhẹ | Card, panel, dropdown |
| 3 - Emphasis | Badge, glow, icon tile, accent | Nhấn nhẹ | Status badge, progress |
| 4 - Hero | Layout + typography + accent block | Visual focus | Hero section (NOT dark slab) |

> Hero logged-in nổi nhờ layout + typography + accent + image tint nhẹ, không phải dark slab.

### 6.2 Background Tints

| Context | Class | Khi nào |
|---------|-------|--------|
| Page base | `bg-white` | Default cho mọi page |
| Tab bar / segmented control | `bg-slate-50` | Subtle tint, boundary nhẹ |
| Floating tab (sticky, scroll) | `bg-white/70 backdrop-blur-xl` | Glass effect |
| Progress track, icon bg, hover | `bg-slate-100` | Small element backgrounds |

**KHÔNG** dùng `bg-slate-100` cho tab/segmented containers → quá đậm, vi phạm boundary-less.
**KHÔNG** chia section bằng dải `bg-slate-50` / `bg-[#f8fafc]` luân phiên → phá boundary-less principle.

### 6.3 Dark Exceptions (chỉ 3 trường hợp)

| Cho phép | Ví dụ |
|----------|-------|
| Backdrop | Overlay, scrim, modal dimmer |
| Media frame | Video area, image lightbox |
| Utility floating UI | AI helper panel nhỏ, dev tooling |

**KHÔNG** biến hero, stats card, content block thành dark surface.
**KHÔNG** mix section sáng/tối kiểu 2 themes trong cùng page.

### 6.4 Wireframe Mode

Wireframe là layout structure, không tuân thủ boundary-less:
- Border: `border border-slate-200` (solid, rõ ràng)
- Background: `bg-slate-50/30` (tint nhẹ, phân biệt với UI mode)
- Annotation: `bg-blue-50 border border-blue-200`

---

## §7 Shadow & Depth

### 7.1 Tailwind Scale

Tailwind shadow utilities are remapped to DOL neutral shadow tone in consuming
projects. Use the familiar Tailwind class; the mapping layer gives it DOL depth.

| Tailwind | DS source | Khi dùng |
|------|-------|---------|
| `shadow-sm` / `shadow` | `shadow-neutral/to-bot/1` | Card nhẹ, input group, white-on-white surface |
| `shadow-md` | `shadow-neutral/to-bot/2` | Dropdown nhỏ, sticky nhẹ, popover nhẹ |
| `shadow-lg` | `shadow-neutral/to-bot/3` | Hover card, raised panel |
| `shadow-xl` | `shadow-neutral/to-bot/4` | Modal, sheet, prominent overlay |
| `shadow-2xl` | `shadow-neutral/to-bot/5` | Hero floating, coachmark, rare premium emphasis |

### 7.2 Hover Interaction - Standalone Cards

Card đứng riêng (dashboard, feature card) - hover tăng border + shadow:

```
Default:  border border-slate-200 shadow-sm
Hover:    hover:border-slate-300 hover:shadow-lg
Always:   transition-all duration-300
```

### 7.3 Hover Interaction - List/Grid Items

Card trong list/grid - hover chỉ đổi background, KHÔNG thêm border/shadow:

```
Hover:    hover:bg-slate-50
```

- Khi card cha đổi bg hover → **BỎ HẲN** `hover:border-*` ở cha và `group-hover:shadow-*` ở icon con.
- Background tint đã đủ phân tách visual.

### 7.4 Accent-Tinted Shadow

Khi card thuộc domain/skill cụ thể, shadow tint theo accent (opacity giữ trong tier):

| Domain | Tailwind |
|--------|----------|
| Blue/Info | `shadow-lg shadow-info-600/10` |
| Brand | `shadow-lg shadow-brand-600/10` |
| Success | `shadow-lg shadow-success-600/10` |

### 7.5 Rules

- **KHÔNG** `shadow-xl`, `shadow-2xl` cho card default → quá đậm. Dùng `shadow-sm`.
- Max **2 elevation levels** per view.
- Shadow transition luôn kèm `transition-all duration-300` (card lớn: `duration-500`).
- Colored shadow chỉ khi có intent rõ ràng (brand/AI/skill accent).
- Border + shadow kết hợp: `border border-slate-200 shadow-sm`.

---

## §8 Borders & Dividers

### 8.1 White-on-White (Bắt buộc)

Khi element `bg-white` nằm trên white surface:
- **Bắt buộc** `border border-slate-200`.
- Shadow là **bổ trợ**, không thay thế border.
- **Rule: Border là nền tảng, shadow là gia vị.**

### 8.2 Divider Strategy

1. **Spacing trước divider** - phân tách bằng khoảng trống trước. Nếu spacing đủ rõ hierarchy → không cần divider.
2. Khi cần divider: `border-slate-200` (standard) hoặc `border-slate-100` (nhẹ, tinh tế).
3. **KHÔNG** `border-slate-50` hoặc `divide-slate-50` trên nền trắng → ~1% contrast, invisible.
4. Card CTA area: **KHÔNG** `border-t` tách CTA. Dùng `pt-6` spacing thay thế.
5. `border-slate-50` chỉ OK khi surface background đã tối hơn white (e.g., trên `bg-slate-100`).

---

## §9 Component Recipes

### 9.1 Card

```html
<div class="bg-white border border-slate-200 rounded-xl p-5
            shadow-sm
            hover:border-slate-300 hover:shadow-lg
            transition-all duration-300">
  <h3 class="text-lg font-bold text-slate-900">Title</h3>
  <p class="mt-3 text-sm text-slate-600">Description</p>
</div>
```

### 9.2 Button - Primary (Brand)

```html
<button class="bg-brand-600 text-on-inverse-primary hover:bg-brand-700
               rounded-lg px-4 py-2.5 text-sm font-semibold
               transition-colors">
  Label
</button>
```

### 9.3 Button - Secondary

```html
<button class="bg-white text-slate-700 border border-slate-200
               hover:bg-slate-50
               rounded-lg px-4 py-2.5 text-sm font-semibold
               transition-colors">
  Label
</button>
```

### 9.4 Button - Info / Action

```html
<button class="bg-blue-600 text-on-inverse-primary hover:bg-blue-700
               rounded-lg px-4 py-2.5 text-sm font-semibold
               transition-colors">
  Label
</button>
```

### 9.5 Input

```html
<input class="w-full border border-slate-200 bg-white text-slate-900
              placeholder:text-slate-500
              focus:border-blue-500 focus:ring-2 focus:ring-blue-500/20
              rounded-lg px-3 py-2.5 text-sm"
       placeholder="Placeholder text" />
```

Error state:
```html
<input class="w-full border border-red-500 bg-red-50 text-red-900
              focus:ring-2 focus:ring-red-500/20
              rounded-lg px-3 py-2.5 text-sm" />
```

### 9.6 Badge / Tag

```html
<!-- Status badge -->
<span class="bg-green-50 text-green-600 px-2.5 py-1 rounded-full text-xs font-medium">
  Active
</span>

<!-- Skill tag -->
<span class="bg-emerald-50 text-emerald-600 px-2.5 py-1 rounded-full text-xs font-medium">
  Reading
</span>
```

### 9.7 Alert / Banner

```html
<!-- Error -->
<div class="bg-red-50 border border-red-200 text-red-700 p-4 rounded-xl text-sm">
  Error message here.
</div>

<!-- Warning -->
<div class="bg-amber-50 border border-amber-200 text-amber-800 p-4 rounded-xl text-sm">
  Warning message here.
</div>

<!-- Success -->
<div class="bg-green-50 border border-green-200 text-green-700 p-4 rounded-xl text-sm">
  Success message here.
</div>

<!-- Info -->
<div class="bg-blue-50 border border-blue-200 text-blue-700 p-4 rounded-xl text-sm">
  Info message here.
</div>
```

### 9.8 Modal

```html
<div class="fixed inset-0 bg-black/50 flex items-center justify-center p-4">
  <div class="bg-white rounded-2xl shadow-xl
              p-6 max-w-lg w-full">
    <h2 class="text-xl font-bold text-slate-900">Modal Title</h2>
    <p class="mt-3 text-sm text-slate-600">Content goes here.</p>
    <div class="mt-6 flex gap-3 justify-end">
      <button class="bg-white text-slate-700 border border-slate-200
                     hover:bg-slate-50 rounded-lg px-4 py-2.5 text-sm font-semibold">
        Cancel
      </button>
      <button class="bg-brand-600 text-on-inverse-primary hover:bg-brand-700
                     rounded-lg px-4 py-2.5 text-sm font-semibold">
        Confirm
      </button>
    </div>
  </div>
</div>
```

### 9.9 Dropdown / Popover

```html
<div class="bg-white border border-slate-200 rounded-xl
            shadow-md p-1.5 min-w-[200px]">
  <button class="w-full text-left px-3 py-2 text-sm text-slate-700
                 hover:bg-slate-50 rounded-lg transition-colors">
    Option 1
  </button>
  <button class="w-full text-left px-3 py-2 text-sm text-slate-700
                 hover:bg-slate-50 rounded-lg transition-colors">
    Option 2
  </button>
</div>
```

### 9.10 Header on Brand Background

```html
<header class="bg-brand-600 text-on-inverse-primary p-6">
  <h1 class="text-xl font-bold">Title</h1>
  <p class="text-on-inverse-secondary text-sm">Subtitle</p>
</header>
```

### 9.11 Icon-only Button (a11y mandatory)

Khi button không có visible label (icon-only — toolbar segmented control, view-mode switcher, filter pill icon), BẮT BUỘC có cả `title` (tooltip) lẫn `aria-label` (screen reader). Cả hai dùng cùng một string, static, không nội suy động.

```html
<!-- Standalone icon button -->
<button type="button"
        title="Grid view"
        aria-label="Grid view"
        class="inline-flex items-center justify-center
               h-8 w-8 rounded-lg border border-slate-200
               text-slate-600 hover:bg-slate-50 hover:border-slate-300
               transition-colors">
  <svg class="h-4 w-4" aria-hidden="true">…</svg>
</button>
```

**Rules**:
- `title` text = `aria-label` text (consistency cho keyboard + mouse user).
- Icon SVG: `aria-hidden="true"` (parent button đã announce, tránh double-announce).
- Hit target tối thiểu `h-8 w-8` (32×32px) — không nhỏ hơn cho touch.
- Khi build segmented/toggle icon group: primitive (`ToggleGroupItem`) PHẢI accept + forward `title` prop, internally set `aria-label` từ cùng giá trị.
- **Anti-pattern**: icon-only button KHÔNG có `aria-label` → screen reader đọc "button" trống; user mới gặp tooltip cũng không có hint.

---

## §10 Motion

- Hover/focus: `transition-colors duration-200` (button) hoặc `transition-all duration-300` (card).
- Large card / feature block: `duration-500`.
- Motion phải ngắn, có mục đích: hover lift, reveal, dropdown, state transition.
- Nếu interaction vẫn rõ khi bỏ animation → giữ animation. Nếu không → bỏ.
- Avoid: hiệu ứng phô diễn trên logged-in surfaces.
- Layout transitions: `150-300ms ease-out`. Không instant.
- Loading state: skeleton, spinner, hoặc "Đang tải..." - không để blank.

---

## §11 Anti-patterns

> 🛑 **Match-and-refuse** (per DIRECTION §10): nếu code bạn sắp emit khớp một row dưới, **STOP** - rewrite element approach từ đầu, không chỉ swap value. CORE §11 = universal quick-ref; xem DIRECTION §10 cho 10 named slop patterns + WHY.
>
> 📐 **Named pattern exceptions**: một số rule (đặc biệt `core-11-layout` row 04 "Card trong card") có **named pattern exceptions** - pattern dùng nesting INTENTIONALLY với different treatment per tier (e.g., Constellation Block 3-tier). Trước khi refuse nesting/composition, check [`../pattern-registry.md`](https://dol-wiki.khoajak.design/ai/raw/anti-pattern-registry.md) để xem có named pattern exception không.

### Layout

<dol_anti_pattern scope="core-11-layout">

| ID | ❌ Không làm | ✅ Thay bằng |
|----|-------------|-------------|
| 01 | Content >1280px không max-width | `max-w-6xl mx-auto` hoặc `max-w-7xl` |
| 02 | Page padding <16px mobile | Min `px-4` mobile, `px-6` tablet, `px-8` desktop |
| 03 | Sections không gap | `gap-10`+ giữa page sections |
| 04 | Card trong card, box trong box | 1 shell per function group |
| 05 | Grid quá đều, không focal point | Cho phép 1-2 elements lớn/prominent hơn |
| 06 | Content chia lô xám/trắng luân phiên | `bg-white` boundary-less |

</dol_anti_pattern>

### Color

<dol_anti_pattern scope="core-11-color">

| ID | ❌ Không làm | ✅ Thay bằng |
|----|-------------|-------------|
| 01 | Brand red cho error/danger | Brand red = CTA/accent. Danger = `bg-red-*` |
| 02 | >2 accent colors cùng lúc | 1 brand + 1 status per context |
| 03 | White card trên white bg không border | `border-slate-200` bắt buộc |
| 04 | Blue cho mọi thứ prominent | Blue = progress/info/active/link. Prominent = brand |
| 05 | Gradient full page | Hero/header only. Body neutral |

</dol_anti_pattern>

### Typography

<dol_anti_pattern scope="core-11-typography">

| ID | ❌ Không làm | ✅ Thay bằng |
|----|-------------|-------------|
| 01 | >3 font sizes trong 1 card | Max 3: title → body → label |
| 02 | Body <13px | Min 14px (`text-sm`) |
| 03 | Heading cùng weight với body | Heading nặng hơn ≥1 level |
| 04 | >4 text colors per view | Stick to semantic roles: primary/secondary/dim/placeholder |
| 05 | Mixed-language drift trong copy | Vietnamese nhất quán cho affordances |

</dol_anti_pattern>

### Spacing & Depth

<dol_anti_pattern scope="core-11-spacing-depth">

| ID | ❌ Không làm | ✅ Thay bằng |
|----|-------------|-------------|
| 01 | Shadow quá đậm (`shadow-xl`/`shadow-2xl` cho card default) | `shadow-sm` default, max 2 levels per view |
| 02 | Padding 4 phía khác nhau bất đối xứng | Multiple of 4px. Top/bottom ≈ left/right |
| 03 | <8px giữa unrelated elements | Min 12px (`gap-3`) giữa unrelated |
| 04 | Divider thay spacing | Spacing trước, divider nếu thật sự cần |

</dol_anti_pattern>

### Interaction

<dol_anti_pattern scope="core-11-interaction">

| ID | ❌ Không làm | ✅ Thay bằng |
|----|-------------|-------------|
| 01 | Button không hover/focus state | Min hover brightness hoặc bg change |
| 02 | Click target <32px | Min 36px interactive, 44px primary actions |
| 03 | Loading state blank | Skeleton hoặc loading indicator |
| 04 | Card hover thêm border + shadow + bg cùng lúc | Standalone: border + shadow. List item: bg only |
| 05 | Icon con bung shadow khi card cha hover | Chỉ card cha thay đổi - con giữ nguyên |

</dol_anti_pattern>

### Tailwind (Anti-drift Convention)

> Tailwind v4 hỗ trợ `@theme`, arbitrary values, và custom-property shorthand.
> Các rule dưới đây là **DOL workspace convention** để giữ codebase deterministic - không phải giới hạn kỹ thuật của TW.

<dol_anti_pattern scope="core-11-tailwind">

| ID | ❌ Không làm | ✅ Thay bằng | Lý do |
|----|-------------|-------------|-------|
| 01 | Dynamic class: `` `bg-${color}-600` `` | Static class đầy đủ: `bg-blue-600`. Map prop sang static strings | TW scan tĩnh, class động bị tree-shake |
| 02 | `bg-(--token)` hoặc `var(--token)` trong class | Standard Tailwind numeric: `bg-brand-600` | Anti-drift: giữ single naming convention |
| 03 | `gray-*`, `zinc-*`, `neutral-*` | `slate-*` | DOL dùng slate family duy nhất |
| 04 | Hardcode hex trong class names | Dùng Tailwind palette classes | Consistency + dark mode support |

</dol_anti_pattern>

---

## §12 KID Domain Overrides

Khi build cho **DOL Kid** domain, override các rule sau. Mọi rule khác trong CORE.md giữ nguyên.

| Aspect | General DOL | KID Override |
|--------|------------|--------------|
| Heading font | Plus Jakarta Sans | **Quicksand** |
| Body font | Inter | **Quicksand** |
| Visual feel | Professional-warm | **Cute but calm, playful but not noisy** |
| Content density | Standard | **1 objective, 1 message, 1 CTA per screen** |
| Spacing micro | `gap-2` (8px) | `gap-2` (8px) - same |
| Spacing component | `gap-3` to `gap-4` | `gap-3` to `gap-4` (12-16px) |
| Spacing card padding | `p-5` to `p-6` | `p-5` to `p-6` (20-24px) |
| Spacing section | `gap-6` to `gap-8` | `gap-6` to `gap-8` (24-32px) |
| Color palette | GM (General Mode) | **KM (Kid Mode)** - 12 families remapped |

> KID color mapping: xem `DOL-DS-token/docs/tailwind-color-guideline.md` §KM.
> Radius, shadow, border, surface hierarchy → giữ nguyên theo CORE.md.

---

## §13 Deep Reference

Khi cần tra cứu chi tiết hơn CORE.md:

| Topic | File | Repo |
|-------|------|------|
| **AI agent entry for code UI task** (router + hard rules + self-check) | **`../ai-entry/CODE-UI.md`** | DS-Token |
| Color mapping đầy đủ (18 families) | `../../docs/tailwind-color-guideline.md` | DS-Token |
| Color system rules (34 rules) | `../../docs/color-system-rules.md` | DS-Token |
| **AI color quick-ref** (mapping table + safe/unsafe classes) | **`../../docs/ai-color-context.md`** | DS-Token |
| **Design philosophy + cross-topic anti-patterns** | **`../ds-guideline/DIRECTION.md`** | DS-Token |
| **Named composition patterns (cross-product)** | **`../pattern-registry.md`** | DS-Token |
| Typography design intent | `../ds-guideline/typography.md` | DS-Token |
| Color design intent | `../ds-guideline/color.md` | DS-Token |
| Radius design intent | `../ds-guideline/radius.md` | DS-Token |
| Spacing design intent | `../ds-guideline/spacing.md` | DS-Token |
| Shadow/Effects + style layer precedence | `../ds-guideline/shadow.md` | DS-Token |
| KID basic guideline | `../kid/Design System Guideline/KID_DS_Basic_Guideline.md` | DS-Token |

> CORE.md đã distill toàn bộ actionable rules từ các file trên.
> Chỉ tra deep reference khi cần hiểu *tại sao* một rule tồn tại hoặc edge cases phức tạp.
>
> **Cho AI agent**: nếu task là build/modify UI code, start tại `../ai-entry/CODE-UI.md` (router + safety-net rules) thay vì đọc CORE.md full ngay.

---

<!-- ============ source: design-guideline/anti-pattern-registry.md ============ -->


# DOL Anti-Pattern Registry

**Total**: 29 scopes · 180 anti-pattern rows across 6 source files.

> Single-file lookup index for every `<dol_anti_pattern>` row across DOL guidelines.
> AI agents load THIS file instead of grep-scrolling 6+ markdown files.
> Citation format: `<scope>#<ID>` - e.g., `landing-5.4-cta#05`, `slop-08`, `figma-naming-6-binding#01`.

## How to use this registry

1. **Before shipping UI**: scan your output against applicable scope(s) listed in CODE-UI §5.2
2. **When refusing**: cite specific row `<scope>#<ID>`, then point to source file for REWRITE guidance
3. **When extending**: new anti-pattern goes in the relevant product file; this registry regenerates from source

Source files + regeneration:
```bash
python3 "DOL-DS-token/design-guideline/ui-style-guide/extract-anti-patterns.py"
```

## DIRECTION

Source: `ds-guideline/DIRECTION.md`

### `direction-10-layout` (4 rows)

| ID | ❌ PATTERN |
|----|-----------|
| `direction-10-layout#01` | Content rộng hơn 1280px không có max-width |
| `direction-10-layout#02` | Padding page <16px mobile |
| `direction-10-layout#03` | Section liền nhau không có khoảng cách rõ |
| `direction-10-layout#04` | Grid quá đều, không focal point |

### `direction-10-typography` (4 rows)

| ID | ❌ PATTERN |
|----|-----------|
| `direction-10-typography#01` | Hơn 3 cấp font-size trong 1 card |
| `direction-10-typography#02` | Body text <13px |
| `direction-10-typography#03` | Heading + body cùng weight |
| `direction-10-typography#04` | Quá nhiều màu text trong 1 view |

### `direction-10-color-brand` (9 rows)

| ID | ❌ PATTERN |
|----|-----------|
| `direction-10-color-brand#01` | `bg-red-*` cho brand |
| `direction-10-color-brand#02` | `bg-brand-*` cho error/danger |
| `direction-10-color-brand#03` | Hơn 2 semantic accents đồng thời |
| `direction-10-color-brand#04` | `bg-blue-*` cho "mọi thứ nổi bật" |
| `direction-10-color-brand#05` | Shade `-500` làm canonical |
| `direction-10-color-brand#06` | `text-white` trên vivid bg (shade 500-600) |
| `direction-10-color-brand#07` | `gray-*` / `zinc-*` / `neutral-*` |
| `direction-10-color-brand#08` | Background gradient rực rỡ toàn page |
| `direction-10-color-brand#09` | Card trắng trên trắng không border/shadow |

### `direction-10-spacing-depth` (3 rows)

| ID | ❌ PATTERN |
|----|-----------|
| `direction-10-spacing-depth#01` | Shadow quá đậm hoặc nhiều levels đồng thời |
| `direction-10-spacing-depth#02` | Padding nội bộ không đều 4 phía |
| `direction-10-spacing-depth#03` | Element quá sát (<8px) khi không liên quan |

### `direction-10-component-interaction` (4 rows)

| ID | ❌ PATTERN |
|----|-----------|
| `direction-10-component-interaction#01` | Button không có hover/focus |
| `direction-10-component-interaction#02` | Click target <32px |
| `direction-10-component-interaction#03` | Transition đột ngột (instant) |
| `direction-10-component-interaction#04` | Loading state trắng trơn |

### `direction-10-responsive` (3 rows)

| ID | ❌ PATTERN |
|----|-----------|
| `direction-10-responsive#01` | Text/layout y hệt desktop trên mobile |
| `direction-10-responsive#02` | Ẩn nav trên mobile mà không có thay thế |
| `direction-10-responsive#03` | Horizontal scroll trên content chính |

### `direction-10-ai-slop-universal` (10 rows)

| ID | ❌ PATTERN |
|----|-----------|
| `direction-10-ai-slop-universal#slop-01` | `border-left` hoặc `border-right: ≥2px solid <color>` trên card/list/alert |
| `direction-10-ai-slop-universal#slop-02` | `bg-gradient-*` + `text-transparent` + `bg-clip-text` trên heading/metric |
| `direction-10-ai-slop-universal#slop-03` | Card (bg-white + border + shadow) chứa Card khác cùng treatment |
| `direction-10-ai-slop-universal#slop-04` | Cùng 1 gap/padding value (vd `gap-4` everywhere) trong whole view |
| `direction-10-ai-slop-universal#slop-05` | Multiple consecutive `text-center` trong siblings (section sau section) |
| `direction-10-ai-slop-universal#slop-06` | Big icon box (rounded + tinted bg) **trên mỗi** heading trong feature list |
| `direction-10-ai-slop-universal#slop-07` | `shadow-[...rgba(brand-color)...]` box-shadow với colored glow |
| `direction-10-ai-slop-universal#slop-08` | `cubic-bezier` với negative values (overshoot) hoặc `ease-bounce`/`elastic` |
| `direction-10-ai-slop-universal#slop-09` | CSS `transition` / `transition-property` of layout props (`width`/`height`/`padding`/`margin`) - **NOT** Tailwind `transition-all` when only transform/opacity/color/shadow actually change |
| `direction-10-ai-slop-universal#slop-10` | Body text với `uppercase` + `tracking-wider` HOẶC `text-justify` |

## CORE

Source: `ui-style-guide/CORE.md`

### `core-11-layout` (6 rows)

| ID | ❌ PATTERN |
|----|-----------|
| `core-11-layout#01` | Content >1280px không max-width |
| `core-11-layout#02` | Page padding <16px mobile |
| `core-11-layout#03` | Sections không gap |
| `core-11-layout#04` | Card trong card, box trong box |
| `core-11-layout#05` | Grid quá đều, không focal point |
| `core-11-layout#06` | Content chia lô xám/trắng luân phiên |

### `core-11-color` (5 rows)

| ID | ❌ PATTERN |
|----|-----------|
| `core-11-color#01` | Brand red cho error/danger |
| `core-11-color#02` | >2 accent colors cùng lúc |
| `core-11-color#03` | White card trên white bg không border |
| `core-11-color#04` | Blue cho mọi thứ prominent |
| `core-11-color#05` | Gradient full page |

### `core-11-typography` (5 rows)

| ID | ❌ PATTERN |
|----|-----------|
| `core-11-typography#01` | >3 font sizes trong 1 card |
| `core-11-typography#02` | Body <13px |
| `core-11-typography#03` | Heading cùng weight với body |
| `core-11-typography#04` | >4 text colors per view |
| `core-11-typography#05` | Mixed-language drift trong copy |

### `core-11-spacing-depth` (4 rows)

| ID | ❌ PATTERN |
|----|-----------|
| `core-11-spacing-depth#01` | Shadow quá đậm (`shadow-xl`/`shadow-2xl` cho card default) |
| `core-11-spacing-depth#02` | Padding 4 phía khác nhau bất đối xứng |
| `core-11-spacing-depth#03` | <8px giữa unrelated elements |
| `core-11-spacing-depth#04` | Divider thay spacing |

### `core-11-interaction` (5 rows)

| ID | ❌ PATTERN |
|----|-----------|
| `core-11-interaction#01` | Button không hover/focus state |
| `core-11-interaction#02` | Click target <32px |
| `core-11-interaction#03` | Loading state blank |
| `core-11-interaction#04` | Card hover thêm border + shadow + bg cùng lúc |
| `core-11-interaction#05` | Icon con bung shadow khi card cha hover |

### `core-11-tailwind` (4 rows)

| ID | ❌ PATTERN |
|----|-----------|
| `core-11-tailwind#01` | Dynamic class: `` `bg-${color}-600` `` |
| `core-11-tailwind#02` | `bg-(--token)` hoặc `var(--token)` trong class |
| `core-11-tailwind#03` | `gray-*`, `zinc-*`, `neutral-*` |
| `core-11-tailwind#04` | Hardcode hex trong class names |

## Landing

Source: `ui-style-guide/landing.md`

### `landing-1.7-hero` (7 rows)

| ID | ❌ PATTERN |
|----|-----------|
| `landing-1.7-hero#01` | Eyebrow dùng `bg-blue-50 text-blue-600` hoặc `text-indigo-600` |
| `landing-1.7-hero#02` | Headline highlight dùng blue/indigo/purple gradient |
| `landing-1.7-hero#03` | Eyebrow text `text-xs` |
| `landing-1.7-hero#04` | Description `text-xl` hoặc `text-2xl` |
| `landing-1.7-hero#05` | Button `font-black` |
| `landing-1.7-hero#06` | Button `py-5 text-lg` (quá nặng) |
| `landing-1.7-hero#07` | Primary/secondary button khác font-weight |

### `landing-2.5-feature-grid` (6 rows)

| ID | ❌ PATTERN |
|----|-----------|
| `landing-2.5-feature-grid#01` | Identical icon boxes across ALL cards (same color/size/shape) |
| `landing-2.5-feature-grid#02` | 4+ columns on desktop |
| `landing-2.5-feature-grid#03` | Heavy shadows (`shadow-xl`) on every card |
| `landing-2.5-feature-grid#04` | Centered text in every feature card |
| `landing-2.5-feature-grid#05` | Gradient card backgrounds |
| `landing-2.5-feature-grid#06` | "Learn more" link on every card (repeated) |

### `landing-3.4-showcase` (5 rows)

| ID | ❌ PATTERN |
|----|-----------|
| `landing-3.4-showcase#01` | Screenshot với `rotate-3` / `rotate-6` |
| `landing-3.4-showcase#02` | Gradient overlay on product screenshot |
| `landing-3.4-showcase#03` | Multiple screenshots stacked tilted / overlapping |
| `landing-3.4-showcase#04` | Colored glow behind screenshot |
| `landing-3.4-showcase#05` | Screenshot full-bleed (edge-to-edge) |

### `landing-4.4-testimonials` (6 rows)

| ID | ❌ PATTERN |
|----|-----------|
| `landing-4.4-testimonials#01` | Giant decorative quote marks `"` as `text-6xl` |
| `landing-4.4-testimonials#02` | Avatar `w-20 h-20` (huge) |
| `landing-4.4-testimonials#03` | Carousel auto-advance fast |
| `landing-4.4-testimonials#04` | Testimonials without role / company |
| `landing-4.4-testimonials#05` | Star rating in different colors per testimonial |
| `landing-4.4-testimonials#06` | "★★★★★" emoji characters instead of icon |

### `landing-5.4-cta` (7 rows)

| ID | ❌ PATTERN |
|----|-----------|
| `landing-5.4-cta#01` | Multiple CTAs per section (3+ buttons) |
| `landing-5.4-cta#02` | Full-width brand color section background |
| `landing-5.4-cta#03` | "Click here" / "Submit" generic copy |
| `landing-5.4-cta#04` | CTA block immediately after hero |
| `landing-5.4-cta#05` | Multiple `!!!` in CTA copy |
| `landing-5.4-cta#06` | CTA form requires 5+ fields |
| `landing-5.4-cta#07` | CTA với countdown timer pressure |

### `landing-6-composition` (8 rows)

| ID | ❌ PATTERN |
|----|-----------|
| `landing-6-composition#01` | Outer section card dùng `rounded-2xl` (cùng inner) |
| `landing-6-composition#02` | Section dùng `p-4/p-6` thay `p-10/p-12` |
| `landing-6-composition#03` | Heading center-aligned cho mọi section header |
| `landing-6-composition#04` | Heading 1 dòng dài chiếm full width |
| `landing-6-composition#05` | Section ↔ section gap dùng `gap-12/gap-16` |
| `landing-6-composition#06` | Inner items dùng cùng padding với outer (`p-10`) |
| `landing-6-composition#07` | Outer card không có border + shadow yếu (alpha ≤0.04) |
| `landing-6-composition#08` | Eyebrow dùng plain text thay pill |

### `landing-6.6-constellation-block` (10 rows)

| ID | ❌ PATTERN |
|----|-----------|
| `landing-6.6-constellation-block#01` | Outer dùng `border-slate-100/200` (with border-color) |
| `landing-6.6-constellation-block#02` | Quên `overflow-hidden` trên middle |
| `landing-6.6-constellation-block#03` | Middle `bg-slate-50` (quá nhạt) |
| `landing-6.6-constellation-block#04` | Cùng radius cho 3 tiers (e.g., outer + middle = `rounded-[32px]`) |
| `landing-6.6-constellation-block#05` | Dùng `divide-x divide-y` thay `gap-[1px]` cho 2-col grid |
| `landing-6.6-constellation-block#06` | Bottom row OUTSIDE middle (sibling) |
| `landing-6.6-constellation-block#07` | Per-cell border + shadow trên white |
| `landing-6.6-constellation-block#08` | Cell có >3 elements (icon-tile + title + target + body + audience + CTA) |
| `landing-6.6-constellation-block#09` | Bottom row content sai platform purpose (sales tone trên self-study) |
| `landing-6.6-constellation-block#10` | Per-cell `translate-y` / `scale` lớn hover |

### `landing-7-decoration` (11 rows)

| ID | ❌ PATTERN |
|----|-----------|
| `landing-7-decoration#01` | Áp tất cả decorations vào 1 section (peek-photos + type-pattern bg + ribbon + emoji + handwritten) |
| `landing-7-decoration#02` | Type-pattern bg với generic dot/grid (không brand vocabulary) |
| `landing-7-decoration#03` | Emoji sticker random không meaning (🌟 ⭐ ✨ scattered) |
| `landing-7-decoration#04` | Handwritten font cho body / labels / buttons |
| `landing-7-decoration#05` | Photo peek-edges dùng stock photo / illustration |
| `landing-7-decoration#06` | Ribbon badge cho status indicator (active/disabled/loading) |
| `landing-7-decoration#07` | Certificate stack cho generic feature ("tính năng mới") |
| `landing-7-decoration#08` | Dotted arrow connector trong tight grid |
| `landing-7-decoration#09` | Section accent color rotation >3 distinct colors / page |
| `landing-7-decoration#10` | 2-color heading nhấn cả câu (`text-brand-600` toàn heading) |
| `landing-7-decoration#11` | Big-number block dùng `text-2xl` (số nhỏ) + `text-base` label (label to) |

## Practice

Source: `ui-style-guide/practice.md`

### `practice-2.6-answer-cards` (8 rows)

| ID | ❌ PATTERN |
|----|-----------|
| `practice-2.6-answer-cards#01` | Shake / bounce animation on incorrect |
| `practice-2.6-answer-cards#02` | Brand red for "selected" state |
| `practice-2.6-answer-cards#03` | Full border + bg + shadow change on hover |
| `practice-2.6-answer-cards#04` | Icon badge above answer text |
| `practice-2.6-answer-cards#05` | Gradient bg on correct/incorrect |
| `practice-2.6-answer-cards#06` | Huge letter prefix "A" / "B" / "C" as badge |
| `practice-2.6-answer-cards#07` | "Try again" text on incorrect |
| `practice-2.6-answer-cards#08` | Confetti / celebration animation on correct |

### `practice-4.5-timer-progress` (6 rows)

| ID | ❌ PATTERN |
|----|-----------|
| `practice-4.5-timer-progress#01` | Red flash / blink when time <1 min |
| `practice-4.5-timer-progress#02` | Timer font không `tabular-nums` |
| `practice-4.5-timer-progress#03` | Progress bar bounce/elastic easing |
| `practice-4.5-timer-progress#04` | Circular progress với huge % text center |
| `practice-4.5-timer-progress#05` | Step indicator có label "Câu 3 of 10" + dots đồng thời |
| `practice-4.5-timer-progress#06` | Auto-submit không warning |

### `practice-6.5-audio-tts` (7 rows)

| ID | ❌ PATTERN |
|----|-----------|
| `practice-6.5-audio-tts#01` | Loud feedback sounds (100% volume) |
| `practice-6.5-audio-tts#02` | Harsh buzzer for incorrect |
| `practice-6.5-audio-tts#03` | Auto-play narration without user initiate |
| `practice-6.5-audio-tts#04` | Narration indicator using brand color |
| `practice-6.5-audio-tts#05` | No visual counterpart cho audio feedback |
| `practice-6.5-audio-tts#06` | Progress bar bounce/elastic during playback |
| `practice-6.5-audio-tts#07` | Vague labels ("Play", "Pause" in English) |

## Data Entry

Source: `ui-style-guide/data-entry.md`

### `data-entry-3.7-validation` (7 rows)

| ID | ❌ PATTERN |
|----|-----------|
| `data-entry-3.7-validation#01` | Validate on keystroke (every char) |
| `data-entry-3.7-validation#02` | Required marker `*` without a11y label |
| `data-entry-3.7-validation#03` | Error as modal / toast |
| `data-entry-3.7-validation#04` | Generic "Invalid input" / "Error" copy |
| `data-entry-3.7-validation#05` | English error messages |
| `data-entry-3.7-validation#06` | Red border alone, no text |
| `data-entry-3.7-validation#07` | Block typing past max length |

### `data-entry-4.6-multistep-flow` (6 rows)

| ID | ❌ PATTERN |
|----|-----------|
| `data-entry-4.6-multistep-flow#01` | "Next" button hoạt động nhưng step invalid (validate chỉ ở submit) |
| `data-entry-4.6-multistep-flow#02` | Step indicator ẩn steps ahead |
| `data-entry-4.6-multistep-flow#03` | Autosave toast mỗi 1500ms |
| `data-entry-4.6-multistep-flow#04` | Progress bar % không map với steps |
| `data-entry-4.6-multistep-flow#05` | Wizard animation slide-between-steps (transform transition) |
| `data-entry-4.6-multistep-flow#06` | Block Back button after completing step |

### `data-entry-5.6-rich-content` (7 rows)

| ID | ❌ PATTERN |
|----|-----------|
| `data-entry-5.6-rich-content#01` | Rich editor toolbar floats trên content (không shared border) |
| `data-entry-5.6-rich-content#02` | Dropzone không show format + size limit trước upload |
| `data-entry-5.6-rich-content#03` | Remove button dưới thumbnail (not overlay) |
| `data-entry-5.6-rich-content#04` | Progress bar bên dưới row (tạo vertical shift) |
| `data-entry-5.6-rich-content#05` | Markdown preview mở modal / new tab |
| `data-entry-5.6-rich-content#06` | Editor height fixed tall (~600px) luôn |
| `data-entry-5.6-rich-content#07` | Toolbar icon-tile-above label pattern |

### `data-entry-6.8-data-tables` (8 rows)

| ID | ❌ PATTERN |
|----|-----------|
| `data-entry-6.8-data-tables#01` | Bordered cells (full grid) |
| `data-entry-6.8-data-tables#02` | Numeric cells left-aligned |
| `data-entry-6.8-data-tables#03` | Select-all checkbox = "all rows everywhere" |
| `data-entry-6.8-data-tables#04` | Inline edit commits silently on Enter (no visual feedback) |
| `data-entry-6.8-data-tables#05` | Empty state = blank tbody + "No data" text |
| `data-entry-6.8-data-tables#06` | Loading = centered spinner replacing table |
| `data-entry-6.8-data-tables#07` | Page size > 50 on mobile |
| `data-entry-6.8-data-tables#08` | Row click = navigate AND checkbox = select |

## Figma Naming

Source: `figma-ai/naming-convention.md`

### `figma-naming-6-binding` (5 rows)

| ID | ❌ PATTERN |
|----|-----------|
| `figma-naming-6-binding#01` | Hardcoded hex in fills when matching token exists |
| `figma-naming-6-binding#02` | `text-color/*` applied to icon vectors (prefix mismatch) |
| `figma-naming-6-binding#03` | Feature-named tokens (`cause-bg-color`, `effect-text-color`) |
| `figma-naming-6-binding#04` | Inconsistent focus ring (per-component color) |
| `figma-naming-6-binding#05` | Inventing new intensity modifier (e.g., "semi-soft", "extra-dim") |