DOL Design System Guideline - Hub

DOL Design System Guideline (DS Guideline)

Scope: Canonical design guidelines cho DOL Design System - design intent layer (triết lý, hierarchy, rationale). For code (Tailwind classes, component recipes): see ../ui-style-guide/CORE.md (companion layer). For token values (hex, shade scale, alpha math): see ../../docs/.

File structure (R2 2026-04-22)

Sau R2 consolidation, folder này có 7 file:

ds-guideline/
├── README.md          ← (this file) hub + persona routing
├── DIRECTION.md       ← triết lý, core pillars, anti-patterns cross-topic
├── typography.md      ← font family, text scale, density taxonomy, text group
├── color.md           ← semantic hierarchy, skill colors detail, shade math, CVD detail
├── radius.md          ← control/surface/overlay radius by element height
├── spacing.md         ← atomic levels A-D, wireframe defaults
└── shadow.md          ← shadow tiers, variable/effect/paint precedence, paint inventory

• DIRECTION.md = compact “why” layer (philosophy + anti-patterns consolidated).
• 5 topic files = “what” layer (exact tokens, matrices, deep technical reference).
• README.md = this hub file (persona routing + links).

Two-layer Architecture

┌──────────────────────────────────────────────────────────┐
│ Design Intent (this folder - ds-guideline/)              │
│   → Figma designer reads here                            │
│   → Semantic tokens (spacing/space-4, control/lg, ...)   │
│   → Rationale, CVD audit, L* math, density taxonomy      │
│                                                          │
│         ↓ translates to ↓                                │
│                                                          │
│ Code Reference (ui-style-guide/CORE.md)                  │
│   → AI agent reads here to build UI                      │
│   → Tailwind classes (gap-4, rounded-xl, text-sm)        │
│   → Component recipes, anti-patterns, decision tables    │
└──────────────────────────────────────────────────────────┘

Persona routing

Persona	Start here	Then
Figma designer	DIRECTION.md → topic files 1-5	../ui-style-guide/CORE.md khi cần verify code implementation
AI code agent	../ui-style-guide/CORE.md	Topic files khi cần hiểu “tại sao”
New team member	DIRECTION.md → topic files in order → CORE.md	../../docs/ cho deep token details

Canonical Docs

#	File	Use when	Core focus	Code companion
0	DIRECTION.md	Cần hiểu bản sắc, triết lý, anti-patterns	4 core pillars, cảm giác mục tiêu, bản sắc màu, anti-patterns cross-topic	../ui-style-guide/CORE.md §1 Identity + §11 Anti-patterns
1	typography.md	Chốt typography, hierarchy chữ, density	Type scale, font pairing, density taxonomy (fit/compact/standard/extended)	../ui-style-guide/CORE.md §3 Typography
2	color.md	Chọn semantic text/status/accent color	Neutral hierarchy, property category, on-inverse, status/skill boundaries, skill colors, CVD considerations, shade scale math	../ui-style-guide/CORE.md §2 Color; ../../docs/tailwind-color-guideline.md
3	radius.md	Chọn bo góc cho control, surface, overlay	Soft-large radius defaults theo element height	../ui-style-guide/CORE.md §5 Radius
4	spacing.md	Xếp whitespace và grouping cho screen/card/wireframe	Atomic grouping (atom→molecule→organism→section), wireframe constraints	../ui-style-guide/CORE.md §4 Spacing
5	shadow.md	Giải quyết precedence + shadow tiers + paint style	Style precedence (Variable > Effect > Paint), shadow discipline, paint inventory	../ui-style-guide/CORE.md §7 Shadow & Depth

Code Reference (External)

Code-level UI rules (Tailwind classes, component recipes, executable patterns) sống trong ../ui-style-guide/:

• ui-style-guide/CORE.md - 13 sections covering color, typography, spacing, radius, surface, shadow, borders, 10 component recipes, motion, anti-patterns, KID overrides.
• Product-specific: ../ui-style-guide/{landing,practice,data-entry}.md

Recommended Read Order

For designers:

1. DIRECTION.md - philosophy + anti-patterns
2. typography.md - typography foundations
3. color.md - color semantics + CVD
4. radius.md - shape language
5. spacing.md - spacing rhythm
6. shadow.md - style layer precedence

For developers / AI agents: start với ../ui-style-guide/CORE.md, đọc files này khi cần design rationale.

What AI Can Learn Here

• DOL design philosophy + 4 core pillars (DIRECTION.md)
• typography defaults and text-style selection (with density taxonomy)
• semantic text color usage by hierarchy (with CVD awareness)
• soft-large radius defaults by element size
• spacing and grouping rules for roomy, hierarchy-first layouts
• variable, effect style, và paint style precedence
• composition anti-patterns and brand red usage discipline
• canonical read order before jumping sang code companion (../ui-style-guide/CORE.md)

Boundary

• Design intent canon của DOL Design System tổng (semantic rules, rationale, design philosophy) - this folder.
• KID-specific: ../kid/Design System Guideline/KID_DS_Basic_Guideline.md.
• Code-level UI implementation (class Tailwind nào, shadow value nào): ../ui-style-guide/CORE.md - source of truth cho mọi code surface.
• Color token mapping details (18 families, shade scale, alpha math): ../../docs/tailwind-color-guideline.md + ../../docs/alpha-decomposition-spec.md - deep reference.
• Playground-specific ops (Audio/TTS, demo image policy, implementation order): dol-edu-playground/docs/ + Playground CLAUDE.md.