---
title: AI Entry - Start Here
updated: 2026-04-30
status: active
purpose: Single canonical entry point for any AI agent working on DOL Edu (code or Figma)
audience: Claude Code, Codex, Cursor, Windsurf, v0, Figma Make, ChatGPT, Gemini, etc.
related_resources:
  - ai-entry/CODE-UI.md
  - ai-entry/FIGMA-AI.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/FIGMA-DESIGNER.md
  - ../data-entry-authoring/AI-CODE.md
  - ../data-entry-authoring/AI-FIGMA.md
  - ../overview.md
  - ../ui-style-guide/CORE.md
  - ../../docs/DS-Tailwind-Bridge-Guide.md
  - ../../docs/ai-color-context.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`](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`](../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`](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`](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`.