DOL UI Style Guide

Hệ thống style guide thống nhất cho code surfaces của DOL Education platform. Đây là code-facing style guide (Tailwind classes, component recipes) - khác với Figma-oriented design intent trong docs/Shared/Design System/.

Cách sử dụng

Cho AI Agent

1. Luôn đọc CORE.md trước - shared visual system, đủ để build UI
2. Đọc thêm 1 product file phù hợp với task hiện tại
3. Nếu cần chi tiết color mapping → DOL-DS-token/docs/tailwind-color-guideline.md

Workflow

Agent nhận task "build exercise page"
  → Load: CORE.md            (shared visual rules)
  → Load: practice.md        (exercise-specific patterns)
  → Build UI bằng Tailwind CSS

Files

File	Scope	Sections done / total	Nội dung
CORE.md	All surfaces	13/13	Color, typography, spacing, radius, shadow, component recipes, anti-patterns
landing.md	Showcase, guest pages	7/7	§1 Hero · §2 Feature Grid · §3 Showcase · §4 Testimonials · §5 CTA Sections · §6 Composition Foundation · §7 Decoration Toolkit (R-future expansion 2026-04-25 - codified dol.vn V2 personality decode)
practice.md	Exercise, AI, Online Test	7/7	§1 Exercise Layout · §2 Answer Cards · §3 AI Content · §4 Timer+Progress · §5 Skill Colors · §6 Audio/TTS · §7 Product Logic References
data-entry.md	Content authoring	6/6	§1 Form Layout · §2 Input States · §3 Validation · §4 Multi-step Flow · §5 Rich Content Input · §6 Data Tables (all done post-R12 P5)
AUDIT.md	Review rubric (cross-product)	-	Vision-first 4-layer rubric (feeling → direction → composition → token/code) cho audit UI bất kỳ surface DOL hoặc external project consume DS-Token. Pair với skill ui-quality-audit (Claude Code).

Section Status System

Mỗi section trong product files có status:

Status	Ý nghĩa	Agent behavior
done	Pattern canonical, đã review	Build đúng theo recipe
draft	Pattern hợp lý, 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

Status nằm ở 2 nơi: frontmatter sections: map + inline status:done / status:skeleton trên heading.

Architecture

CORE.md (shared visual system - 13 sections, all done)
├── landing.md    ← extends §6 surfaces, §7 shadow, §9 recipes
├── practice.md   ← extends §2.4 skill colors, §3 typography, §9 components
└── data-entry.md ← extends §9 input/form recipes

Product files inherit toàn bộ CORE.md rules. Chỉ bổ sung patterns đặc thù, không lặp lại core rules.

Product files có thể ghi reusable UI implications từ product guideline/Notion, nhưng không thay thế product/spec source of truth. Các rule như score band, leaderboard metric, attempt counted, unlock/deadline, hoặc material ordering phải được product owner/EduDoc xác nhận nếu dùng cho product mới.

CLAUDE.md Integration

Tất cả repo CLAUDE.md + AGENTS.md có ## UI Style Guide section trỏ về CORE.md:

Repo	Pointer path
Workspace root	./DOL-DS-token/design-guideline/ui-style-guide/CORE.md
DOL-DS-token (this repo)	./design-guideline/ui-style-guide/CORE.md (local)
DOL Education Documentation	../DOL-DS-token/design-guideline/ui-style-guide/CORE.md
dol-edu-playground	../DOL-DS-token/design-guideline/ui-style-guide/CORE.md
DOL Wiki/site	../../DOL-DS-token/design-guideline/ui-style-guide/CORE.md

Relationship với existing docs

Existing file	Vai trò hiện tại
EduDoc Guidelines (6 files)	Figma design reference - design intent cho designer
Visual Contract (Playground)	Runtime contract - content đã absorbed vào CORE.md
DS-Token color docs	Deep reference - tra cứu khi cần mapping chi tiết
ai-color-context.md	AI prompt - copy-paste cho external AI tools

Tooling

3 tools, all bash/python - zero npm deps.

audit.sh - grep-based guideline violation scanner

Chạy sau khi build UI:

bash DOL-DS-token/design-guideline/ui-style-guide/audit.sh                           # scan toàn bộ workspace
bash DOL-DS-token/design-guideline/ui-style-guide/audit.sh ./dol-edu-playground       # scan 1 repo
bash DOL-DS-token/design-guideline/ui-style-guide/audit.sh ./DOL\ Wiki/site/src       # scan Wiki src

19 patterns (post-R11 expansion - 12 original + 6 Impeccable slop detectors + 1 semantic refinement). Covers: text-on-inverse, wrong neutral families, text-black, brand≠red, shadow utilities, invisible borders, dynamic TW classes, canonical shade, + slop-01 side-stripe, slop-02 gradient-text, slop-07 dark-glow, slop-08 bounce-easing, slop-09 layout-animation (CSS layout-prop transitions), slop-10 justified-text. Findings là candidates - review từng cái vì có thể có valid exceptions.

contrast-check.py - WCAG AA validation

Reads CORE.md YAML contrast-pairs block, computes WCAG 2.1 contrast ratio cho mỗi pair, emits JSON findings:

python3 DOL-DS-token/design-guideline/ui-style-guide/contrast-check.py               # default: ./CORE.md
python3 DOL-DS-token/design-guideline/ui-style-guide/contrast-check.py --summary-only # chỉ summary

Runtime: Python 3 + PyYAML (typically preinstalled). Exit 1 nếu có errors, 0 otherwise.

Known findings (resolved 2026-04-25, R23): 4 color pairs pass AA large text only (≥3:1) but fail AA normal text: success/amber/emerald/sky-600 + on-inverse-primary. Decision: LOCKED to button-label context ≥14px semibold ONLY (AA large threshold). For body text / captions / inline emphasis in these 4 families, use shade -700. Full context matrix in CORE.md §2.2 “Lưu ý contrast”.

spec.sh - export DOL design spec as JSON

Combine CORE.md YAML + .claude/rules/ui-style.md hard rules thành JSON cho external agents (Cursor, Codex, Gemini):

bash DOL\ Education\ Documentation/ui-style-guide/spec.sh                    # JSON
bash DOL\ Education\ Documentation/ui-style-guide/spec.sh markdown           # human-readable summary
bash DOL\ Education\ Documentation/ui-style-guide/spec.sh | pbcopy           # copy to clipboard (macOS)

Output shape: {version, name, tokens: {colors,typography,rounded,spacing}, contrastPairs, hardRules, sections, metadata}. Use trong system prompts của agents không có .claude/rules/ auto-load.

Machine-readable token layer (CORE.md frontmatter)

CORE.md YAML frontmatter có machine-parseable tokens (Phase A, 2026-04-22). Added:

• colors - 19 key hex values (brand + intent + skills + neutrals)
• typography - 8 most-used levels (display/heading/body/label)
• rounded - 6 scale levels (Tailwind-aligned naming)
• spacing - 10 scale + defaults
• contrast-pairs - 12 WCAG AA validation contracts (for contrast-check.py)

Intentional duplication: YAML = machine view, prose tables (§1-§5) = human canonical reference. Drift risk mitigated by spot-checking in each /reflect cycle.

Khi nào cập nhật

• Thêm rule mới vào CORE.md → update version + updated trong frontmatter
• Thêm product type mới → tạo file mới, thêm vào bảng Files, update CORE.md header
• Skeleton → done → update frontmatter sections: map + inline status
• Rule conflict giữa CORE và product file → CORE wins (product chỉ extends, không override trừ khi ghi rõ)