DOL UI Guide - AI Code Entry

📌 Authority: This file is a derived entry router. The normative source for ALL executable UI rules is ../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 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 ../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
../../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.