---
title: DOL UI Guide - AI Code Entry
updated: 2026-04-25
last_reviewed: 2026-04-25
status: active
role: derived-entry-router
normative_source: ui-style-guide/CORE.md
purpose: Entry point for AI agents when task = build or modify UI code for DOL
scope: code-ui-only
audience: Claude Code, Codex, Cursor, Windsurf (autonomous) + paste-based AI (graceful)
related_resources:
  - ai-entry/README.md
  - ui-style-guide/CORE.md
  - docs/ai-color-context.md
  - data-entry-authoring/README.md
  - data-entry-authoring/PRODUCT-LIFECYCLE.md
  - data-entry-authoring/PATTERN-LEARNING.md
  - data-entry-authoring/STYLE-LANGUAGE.md
  - data-entry-authoring/AI-CODE.md
---

> 📌 **Authority**: This file is a **derived entry router**. The normative source for ALL executable UI rules is [`../ui-style-guide/CORE.md`](../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.