AI Entry - Start Here

activeUpdated3 tuần trước

🎯 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 (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`

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

→ Primary: 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`
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 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 §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 ../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 §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
`../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 ../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

Hard rules § 2 - never break them. They’re the safety floor.
CORE.md is the single canonical UI reference. When unsure, read it in full.
Match task → router § 4 - load only what you need.
Self-check § 5 before saying done.
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):

Create new entry file in this folder
Add a row to §4 task router
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.