Skip to content
DOL Studio

DS-Token - Design System Overview

activeUpdated

DOL Design Guideline - Overview

Section titled “DOL Design Guideline - Overview”

Post-R19 state (2026-04-24): AI-first tiered architecture. Code UI + Figma UI + Figma canvas-organizer lanes each have purpose-scoped entry routers with TIER 0-3 access hierarchy.

30-second orientation for AI agents

Section titled “30-second orientation for AI agents”

You are here because a task involves DOL design. Before reading any file, know:

  1. Pick the right entry router by task type:

  2. Load the cheapest tier first, escalate only if needed. Both entry routers categorize every file by TIER:

    • TIER 0 - CLI precise lookup (python3 figma-ai/tools/lookup.py ...), output ≤500 tokens
    • TIER 1 - always-on short files (naming-convention, selection, workflows, DIRECTION, anti-patterns), ~20K tokens total baseline
    • TIER 2 - grep-by-section larger files (variable-registry, variable-id-map, ds-guideline topics)
    • TIER 3 - on-demand per-component detail files (components/<slug>.md, organizer/components/<category>.md)

  3. Never edit auto-generated files (component-registry / variable-id-map / variable-registry / anti-pattern-registry + all components/*.md). Edit source markdown or run generator. --check gate in 4 generators catches drift.

Purpose

Section titled “Purpose”
  • Entry doc cho design system dùng chung toàn hệ DOL Edu.
  • Hub routing vào các lane: ai-entry (AI routers), ui-style-guide (code-facing), ds-guideline (Figma intent), figma-ai (Figma AI + Organizer sub-lane), operations (runbook), kid (KID-specific).
  • Tiered context-access architecture tối ưu cho AI token budget.

design-guideline/ structure (active layer)

Section titled “design-guideline/ structure (active layer)”
design-guideline/
├── overview.md                       ← (this file) entry hub
├── ai-entry/                         ← AI agent routers (purpose-scoped)
│   ├── README.md                     hub index
│   ├── CODE-UI.md                    entry for code UI AI tasks
│   └── FIGMA-AI.md                   entry for Figma AI design tasks
├── ds-guideline/                     ← Figma design intent
│   ├── README.md                     hub + persona routing
│   ├── DIRECTION.md                  Why layer (philosophy + anti-patterns)
│   ├── typography.md                 What: font family, scale, density
│   ├── color.md                      What: semantic hierarchy, skill, CVD, shade math
│   ├── radius.md                     What: radius by element height
│   ├── spacing.md                    What: atomic levels A-D, wireframe
│   └── shadow.md                     What: shadow tiers, variable/effect/paint precedence
├── ui-style-guide/                   ← code-facing Tailwind recipes
│   ├── CORE.md                       main code reference (13 sections)
│   ├── landing.md, practice.md, data-entry.md  product-specific
│   ├── README.md                     workflow guide
│   └── audit.sh, contrast-check.py, spec.sh    3 tools
├── figma-ai/                         ← Figma AI canonical (R19 v1.3, 2026-04-24)
│   ├── README.md                     scope + tier classification
│   ├── naming-convention.md          4-category semantic token naming (TIER 1)
│   ├── variable-selection.md         intent → variable decision tree (TIER 1)
│   ├── workflows.md                  5 operational runbooks (TIER 1)
│   ├── variable-registry.md          838 AI-facing tokens (TIER 2, sectioned)
│   ├── variable-id-map.md            Figma variable IDs per collection (TIER 2)
│   ├── component-registry.md         slim INDEX for DS V2 (TIER 3 entry)
│   ├── components/                   44 per-page detail files (TIER 3 on-demand)
│   ├── organizer/                    ← Organizer Kit - canvas meta layer (R19)
│   │   ├── README.md                 folder intro + tier table
│   │   ├── usage-patterns.md         canvas layout rules + Level 1/2/3 hierarchy + anti-patterns (TIER 1)
│   │   ├── component-registry.md     slim INDEX for 10 categories (TIER 3 entry)
│   │   └── components/               10 per-category detail files
│   └── tools/
│       ├── lookup.py                 CLI (TIER 0) - 8 subcommands (DS V2 + organizer)
│       ├── extract-figma-metadata.py DS V2 generator with --check
│       ├── extract-variable-registry.py variable registry generator
│       └── resync-figma.md           re-sync runbook
├── operations/                       ← Figma MCP bridge runbook (human audience)
├── kid/                              ← KID active guideline
│   ├── README.md
│   └── Design System Guideline/
└── dol-general/                      ← DOL General active
    ├── README.md
    └── Template/                     theme adapter files for external AI builders

design-system-report/ sibling (historical layer)

Section titled “design-system-report/ sibling (historical layer)”
design-system-report/
├── cross-system/                     ← 22 md: audits, migrations, KID↔General comparisons
├── kid/                              ← KID historical reports
└── dol-general/                      ← DOL HANDOFFs + historical reports
    ├── HANDOFF_DS_TOKEN_V4.md
    ├── HANDOFF_KID_MODE.md
    └── Design System Report/

Entry sources (by role)

Section titled “Entry sources (by role)”
RoleStart here
AI code agent (autonomous - Claude Code, Codex, Cursor)ai-entry/CODE-UI.md (router + hard rules + self-check) → follows pointers vào CORE.md sections
AI code agent (paste-based)ai-entry/CODE-UI.md (paste content) OR ui-style-guide/CORE.md (single canonical)
AI Figma agent (figma-console-mcp or equivalent)ai-entry/FIGMA-AI.md - routes to DS V2 lane (UI building) AND Organizer Kit lane (canvas arrangement). TIER 0-3 table picks cheapest access.
AI arranging designs on Figma canvasai-entry/FIGMA-AI.md §4 “Organizer Kit” rows → figma-ai/organizer/usage-patterns.md
Figma designerds-guideline/DIRECTION.md → ds-guideline/README.md
New team memberds-guideline/DIRECTION.md → topic files in order → ui-style-guide/CORE.md
KID workkid/README.md
Cross-system audit../design-system-report/cross-system/README.md
Token infrastructure../docs/tailwind-color-guideline.md
DS operationsoperations/

Guideline coverage

Section titled “Guideline coverage”

DOL Design System lane hiện có guideline canon cho:

  • typography và text-style selection (density taxonomy) → ds-guideline/typography.md
  • semantic text color defaults + neutral hierarchy + CVD → ds-guideline/color.md
  • soft-large radius mapping theo element size → ds-guideline/radius.md
  • spacing, grouping, và hierarchy-first layout defaults → ds-guideline/spacing.md
  • style layer precedence (variable > effect > paint) + shadow tiers → ds-guideline/shadow.md
  • design direction (triết lý, core pillars, anti-patterns, brand semantics) → ds-guideline/DIRECTION.md
  • code implementation (Tailwind classes, component recipes) → ui-style-guide/CORE.md
  • practice/product UI implications (exercise layout, online-test structure, score/result, leaderboard, attempt history, material ordering checks) → ui-style-guide/practice.md
  • Figma UI building (DS V2 components + token binding) → figma-ai/README.md + variable-selection.md + workflows.md
  • Figma canvas arrangement (Design area banners, flow arrows, notes) → figma-ai/organizer/README.md + organizer/usage-patterns.md
  • cross-surface anti-patterns (R15: 151 entries × 26 scopes) → anti-pattern-registry.md
  • external AI builder adapter → dol-general/Template/

KID lane có guideline riêng trong kid/ (KID-specific tokens, visual language).

Boundary

Section titled “Boundary”
  • Mỗi design system tự giữ guideline/report của mình trong lane riêng.
  • Historical reports (HANDOFFs, migration audits, KID-vs-General comparisons) → ../design-system-report/.
  • Active guideline cần update → ./design-guideline/.
  • Runbook operations không lẫn với guideline canon hoặc report canon.

Portability assumption (explicit)

Section titled “Portability assumption (explicit)”

This guideline system assumes monoworkspace topology - all 4 repos (DOL-DS-token, DOL Education Documentation, dol-edu-playground, DOL Wiki/site) checked out side-by-side in a shared parent directory. Paths like ai-memory/lessons/*.md in guideline refs resolve against the workspace-root ai-memory/ folder, not DOL-DS-token’s own ai-memory/.

If you’re running an AI agent on DOL-DS-token alone (e.g., cloud CI, single-repo checkout, gh codespaces on just this repo):

  • Workspace-level ai-memory/lessons/ references may not resolve (they live at workspace root, not DS-Token root)
  • Known refs affected: landing-tone-discipline.md, other workspace-level lessons mentioned in guideline files
  • Mitigation: either (a) checkout full workspace parent dir, or (b) vendor-copy relevant lessons into DOL-DS-token/ai-memory/lessons/ - currently NOT automated

This is a deliberate trade-off - keeping lessons at workspace root lets multi-repo agents share one learning source. Cost: portability cliff when single-repo.

Not a bug today (the team’s Claude Code workflow always has workspace checked out); flagged for future decision if DS-Token is published as standalone package consumed by external AI.

Section titled “Navigation”
  • Root of active guideline: ./ds-guideline/README.md
  • Code-facing entry: ./ui-style-guide/CORE.md
  • Historical reports: ../design-system-report/
  • Token references: ../docs/
  • Workspace canonical workflow: see workspace root CLAUDE.md Design System Documentation Map