@champpaba/claude-agent-kit 3.0.3 → 3.3.0

package/.claude/CHANGELOG.md

@@ -5,6 +5,248 @@
 
 ---
 
+## v3.3.0: Design Validation System (No Pseudocode)
+
+**Problem Solved:** Design system compliance was not enforced. uxui-frontend agents didn't read `design-system/data.yaml`, resulting in hardcoded colors, arbitrary spacing, and inconsistent animations. The validation logic was written as TypeScript pseudocode that Claude never executed.
+
+**Solution:** Created a single source of truth (`design-validator.md`) with imperative Thai/English instructions. Converted all procedural pseudocode to step-by-step commands that Claude follows.
+
+### Key Changes
+
+| Component | Before | After |
+|-----------|--------|-------|
+| design-validator.md | Did not exist | NEW - Single source of truth |
+| cdev.md Step 2-5 | TypeScript pseudocode | Imperative instructions |
+| ux-tester.md Steps 2-5 | TypeScript pseudocode | Imperative instructions |
+| uxui-frontend STEP 0.5 | Brief mention | Full step-by-step protocol |
+
+### Design Validation Flow
+
+```
+PREVENTION (Before Implementation)
+├── Main Claude: Pre-Flight Check before invoking uxui-frontend
+└── uxui-frontend: STEP 0.5 - Read data.yaml, report tokens
+
+DETECTION (After Implementation)
+└── ux-tester: Step 5.5 - Chrome DevTools style comparison
+```
+
+### What Gets Validated
+
+| Token Category | Violation Example | Expected |
+|----------------|-------------------|----------|
+| Colors | #3b82f6, text-blue-500 | bg-primary, text-foreground |
+| Spacing | p-5, gap-7 | p-4, p-6, gap-8 (scale) |
+| Animation | duration-200 | duration-150, 300, 500ms |
+| Shadows | mixed sm+xl | consistent level |
+
+### Files Changed
+
+| File | Change |
+|------|--------|
+| `.claude/lib/design-validator.md` | NEW - Single source of truth |
+| `.claude/agents/02-uxui-frontend.md` | v2.1.0 - Enhanced STEP 0.5 |
+| `.claude/agents/07-ux-tester.md` | v1.1.0 - Steps 2-5 rewritten |
+| `.claude/commands/cdev.md` | Steps 2-5 rewritten, Step 4.0 added |
+| `.claude/lib/README.md` | Added design-validator.md entry |
+| `.claude/CLAUDE.md` | v3.3.0 + Design Validation section |
+
+### Why This Matters
+
+**Before:**
+- Logic scattered across 4 files
+- TypeScript pseudocode that Claude ignored
+- No enforcement of design tokens
+- ux-tester couldn't validate actual CSS
+
+**After:**
+- Single source of truth (design-validator.md)
+- Imperative instructions Claude follows
+- Pre-flight check before visual agents
+- Chrome DevTools validation of computed styles
+
+---
+
+## v3.2.0: Consolidated Pre-Work Context
+
+**Problem Solved:** `/csetup` generated two separate pseudocode outputs (`research-checklist.md` and `INTEGRATION_RISKS.md`) that were never actually created. Agents had to discover context from multiple scattered sources.
+
+**Solution:** Consolidated all agent context into a single `pre-work-context.md` file with direct execution instructions. Merged Step 2.7 (Best Practices) into Step 2.6.
+
+### Key Changes
+
+| Component | Before | After |
+|-----------|--------|-------|
+| Step 2.6 | ~1000 lines of pseudocode | ~300 lines of direct instructions |
+| Step 2.7 | Separate best practices step | Merged into Step 2.6 |
+| Output files | research-checklist.md + INTEGRATION_RISKS.md + best-practices/*.md | Single `pre-work-context.md` |
+| Agent discovery | Multiple files to read | One file with all context |
+
+### Step 2.6 Structure (New - v3.2.0)
+
+```
+Step 2.6.1: Analyze Change Characteristics (type, complexity, risk)
+Step 2.6.2: Detect Libraries (from package files + specs)
+Step 2.6.3: Fetch Best Practices via Context7 (direct MCP calls)
+Step 2.6.4: Determine Research Layers (adaptive depth)
+Step 2.6.5: Detect Integration Warnings (cross-library)
+Step 2.6.6: Generate Critical Checklist Items (security/compliance)
+Step 2.6.7: Write pre-work-context.md (single consolidated file)
+Step 2.6.8: Output Summary
+Step 2.6.9: Skip Conditions
+```
+
+### pre-work-context.md Structure
+
+```markdown
+# Pre-Work Context: {changeId}
+
+## 1. Change Analysis (type, complexity, risk)
+## 2. Library Best Practices (from Context7)
+## 3. Research Findings (domain knowledge)
+## 4. Integration Warnings (cross-library concerns)
+## 5. Critical Checklist (security/compliance must-haves)
+## 6. Quick Reference (package manager, commands)
+```
+
+### Agent Pre-Work Checklist Update
+
+**Version:** 3.0.0 (Pre-Work Context Integration)
+
+- Step 0: Read pre-work-context.md (NEW - primary source)
+- Step 0.1: Library Requirements Check (fallback)
+- Step 0.2: Library Feasibility Validation (was 0.5)
+- Step 0.3: Memory Context Query (was 0.6)
+
+### Files Changed
+
+| File | Change |
+|------|--------|
+| `csetup.md` | Rewrote Step 2.6 with direct execution |
+| `csetup.md` | Removed Step 2.7 (merged into 2.6) |
+| `csetup.md` | Renumbered Step 2.8 → Step 2.7 |
+| `pre-work-checklist.md` | Added Step 0 (read pre-work-context.md) |
+| `pre-work-checklist.md` | Renumbered steps (0.5→0.2, 0.6→0.3) |
+| `CLAUDE.md` | Updated to v3.2.0 |
+
+### Why This Matters
+
+**Before:**
+- Agents had to read 5+ files to get context
+- research-checklist.md was pseudocode that never executed
+- INTEGRATION_RISKS.md was pseudocode that never executed
+- Context was scattered and inconsistent
+
+**After:**
+- Agents read ONE file (`pre-work-context.md`) in STEP 0
+- All context is consolidated and actually generated
+- Main Claude follows direct instructions (not pseudocode)
+- Integration warnings + checklist items in one place
+
+---
+
+## v3.1.1: Direct Best Practices Execution
+
+**Problem Solved:** Step 2.7 (Auto-Setup Best Practices) was written as pseudocode with helper functions (`extractLibrariesSemantically`, `parseContext7Response`, etc.) that Main Claude never actually executed. Best practices files were documented but never created.
+
+**Solution:** Rewrote Step 2.7 as direct, executable instructions that Main Claude can follow. No more pseudocode - just clear steps with actual MCP tool names.
+
+### Key Changes
+
+| Component | Before | After |
+|-----------|--------|-------|
+| Step 2.7 | ~1000 lines of pseudocode | ~130 lines of direct instructions |
+| Helper functions | 6 fake functions | Removed entirely |
+| MCP tool calls | Written as code syntax | Written as clear instructions |
+| Output format | Complex extraction logic | Simple template |
+
+### Step 2.7 Structure (New)
+
+```
+Step 2.7.1: Detect Libraries (from package.json, requirements.txt, spec files)
+Step 2.7.2: Resolve via Context7 (call MCP tools directly)
+Step 2.7.3: Create Best Practices Files (using template)
+Step 2.7.4: Create index.md (registry)
+Step 2.7.5: Output Summary
+Step 2.7.6: Skip Conditions
+```
+
+### Files Changed
+
+| File | Change |
+|------|--------|
+| `csetup.md` | Rewrote Step 2.7, removed ~1000 lines of pseudocode |
+| `csetup.md` | Removed helper functions (extractLibrariesSemantically, etc.) |
+| `csetup.md` | Updated detectAdditionalTech as REMOVED |
+| `CLAUDE.md` | Updated version to 3.1.1 |
+
+### Why This Matters
+
+Before: Main Claude would read Step 2.7 as documentation and skip it.
+After: Main Claude follows clear instructions and actually calls Context7.
+
+---
+
+## v3.1.0: TDD Classification + Development Principles Injection
+
+**Problem Solved:** TDD classification was a simple one-liner (`risk=HIGH || complexity>=7`) that missed critical patterns like auth, payment, and external integrations. Development principles (SOLID, DRY, KISS) were documented but never injected to agents.
+
+**Solution:** Comprehensive TDD classification based on `tdd-classification.md` patterns, integrated into `task-analyzer.md` Step 2.6. Development principles injected to ALL agents via `/cdev`.
+
+### Key Changes
+
+| Component | Before | After |
+|-----------|--------|-------|
+| TDD classification | 1-line in csetup.md | Full pattern matching in task-analyzer.md |
+| development-principles.md | Listed but not used | Injected to ALL agents via /cdev |
+| tdd-classifier.md | Duplicate file | Deleted (merged into tdd-classification.md) |
+
+### TDD Classification (Step 2.6)
+
+Now classifies based on:
+
+| Pattern | Examples | TDD Required |
+|---------|----------|--------------|
+| Security operations | auth, jwt, encrypt, permission | ✅ Always |
+| Financial operations | payment, stripe, calculate, tax | ✅ Always |
+| External integrations | webhook, sendgrid, twilio | ✅ Always |
+| Data transformations | serialize, parse, etl | ✅ Always |
+| Complex UI | multi-step, wizard, keyboard-nav | ✅ Always |
+| Simple CRUD reads | get, list, fetch | ❌ Test-alongside OK |
+| Presentational UI | button, card, modal | ❌ No TDD |
+| Database/Integration | schema, migration, validation | ❌ No TDD |
+
+### Development Principles Injection
+
+`/cdev` now injects to ALL agent prompts:
+
+```markdown
+## 🏛️ Development Principles (Level 1 - ALL Agents)
+
+**REQUIRED READING:** @.claude/contexts/patterns/development-principles.md
+
+| Principle | Summary |
+|-----------|---------|
+| **KISS** | Choose simple solutions over complex ones |
+| **YAGNI** | Build only what you need now |
+| **SRP** | One responsibility per module |
+| **DRY** | Single source of truth for all knowledge |
+| **Fail Fast** | Detect and raise errors immediately |
+| **Observability** | Log everything that matters |
+```
+
+### Files Changed
+
+| File | Change |
+|------|--------|
+| `task-analyzer.md` | Added Step 2.6 TDD Classification |
+| `csetup.md` | Updated phase generation to use TDD from tasks |
+| `cdev.md` | Added development-principles injection |
+| `tdd-classifier.md` | **DELETED** (merged) |
+| `CLAUDE.md` | Updated references and version |
+
+---
+
 ## v3.0.0: Template-Free Architecture (Task Analyzer v2.0)
 
 **Problem Solved:** Phase templates (`phase-templates.json`) were limiting and caused task loss. When `tasks.md` had 5 detailed phases but template had only 2, tasks disappeared. Templates overrode the single source of truth.

package/.claude/CLAUDE.md

@@ -1,8 +1,8 @@
 # CLAUDE.md
 
 > **Navigation Hub for AI Agents**
-> **Template Version:** 3.0.0 - Template-Free Architecture
-> **Latest:** Task Analyzer v2.0 - AI-driven analysis, no keyword matching, auto-add best practices
+> **Template Version:** 3.3.0 - Design Validation System
+> **Latest:** Single Source of Truth for design compliance (prevention + detection)
 
 ---
 
@@ -26,6 +26,7 @@
 | `README.md` | **Visual design summary** (human-readable) | UI/Frontend phases |
 | `data.yaml` | Design tokens + psychology (~300 lines) | Quick UI reference |
 | `page-plan.md` | UI component layout + content strategy | uxui-frontend agent |
+| `pre-work-context.md` | **v3.2.0!** All agent context (best practices, warnings, checklist) | All agents - STEP 0 ✨ |
 | `phases.md` | Execution plan with agent assignments | All phases |
 | `flags.json` | Progress tracking | All phases |
 
@@ -75,6 +76,8 @@ Universal, framework-agnostic template for AI-assisted development.
 - `@/.claude/contexts/design/index.md` (General design principles - fallback)
 
 **Development:**
+- `@/.claude/contexts/patterns/development-principles.md` - **v3.1.0!** SOLID, DRY, KISS, Fail Fast (Level 1 - ALL agents) ✨
+- `@/.claude/contexts/patterns/tdd-classification.md` - TDD workflow classification patterns
 - `@/.claude/contexts/patterns/task-classification.md` (Agent selection guide)
 - `@/.claude/contexts/patterns/agent-coordination.md` (When to run agents parallel/sequential)
 - `@/.claude/contexts/patterns/error-recovery.md` (How agents handle errors & escalate)
@@ -86,7 +89,7 @@ Universal, framework-agnostic template for AI-assisted development.
 **Project Setup:**
 - `/extract https://site.com` - Extract design from reference sites
 - `/designsetup @prd.md` - Interactive design system setup
-- `/csetup` - **v3.0.0:** Template-free! AI-driven task analysis, auto-add best practices, incremental milestones
+- `/csetup` - **v3.2.0:** Generates `pre-work-context.md` with best practices, research, warnings, checklists
 
 **Page Planning (UI Tasks) - v2.0.0:**
 - `/pageplan @prd.md @brief.md` - Generate page structure with auto page type detection
@@ -122,30 +125,29 @@ Universal, framework-agnostic template for AI-assisted development.
 **Implementation Logic:**
 - `@/.claude/lib/README.md` - Implementation logic overview
 - `@/.claude/lib/agent-executor.md` - Agent retry & escalation logic (used by /cdev) + Incremental testing execution
-- `@/.claude/lib/tdd-classifier.md` - TDD classification logic (used by /csetup)
-- `@/.claude/lib/task-analyzer.md` - **v2.0!** Template-free AI-driven task analysis ✨
+- `@/.claude/lib/task-analyzer.md` - **v3.1.0!** Template-free task analysis with TDD classification (Step 2.6) ✨
 - `@/.claude/lib/flags-updater.md` - Progress tracking protocol (Main Claude updates flags.json)
 - `@/.claude/lib/agent-router.md` - Mandatory agent routing rules (enforce delegation)
+- `@/.claude/lib/design-validator.md` - **v3.3.0!** Design system validation (prevention + detection) ✨
 - `@/.claude/contexts/patterns/agent-discovery.md` - Shared agent discovery flow
 
 ---
 
-## 📚 Best Practices System (v2.5.0 - Smart Topic Query)
+## 📚 Best Practices System (v3.2.0 - Consolidated Pre-Work Context)
 
 **Quick Summary:**
-- `/csetup` **dynamically detects any library** from spec text + package files (no hardcoded mappings)
-- **Works with any language:** JavaScript, Python, Rust, Go, PHP, Ruby - automatically
-- **Context7 validates** each potential library name and resolves to official docs
-- **v2.5.0:** Smart Topic Query includes other library names for cross-library integration docs
-- **v2.5.0:** Auto-generates `INTEGRATION_RISKS.md` with detected concerns
-- Files created in `.claude/contexts/domain/project/best-practices/`
-- **Agents read** best practices + integration risks before coding
+- `/csetup` generates **single `pre-work-context.md`** with ALL agent context
+- **Consolidates:** Best practices, research findings, integration warnings, critical checklists
+- **Context7 validates** each library and fetches best practices
+- **Agents read ONE file** instead of multiple scattered files
+- **File location:** `openspec/changes/{changeId}/pre-work-context.md`
 
 **Key Changes:**
 | Version | Change |
 |---------|--------|
 | v2.3.0 | NLP extraction + Context7 resolution (zero maintenance) |
 | v2.5.0 | Smart Topic Query + Integration Risk Detection |
+| v3.2.0 | **Consolidated `pre-work-context.md`** (single file for all agent context) |
 
 **Detection Sources:**
 | Source | Examples |
@@ -158,23 +160,22 @@ Universal, framework-agnostic template for AI-assisted development.
 | PHP | composer.json |
 | Ruby | Gemfile |
 
-**Flow (v2.5.0):**
+**Flow (v3.2.0):**
 ```
-/csetup → extract potential library names from ALL text sources
-        → Context7 resolve-library-id (validates if real library)
-        → Context7 get-library-docs (Smart Topic Query with other lib names)
-        → detect integration risks from docs content
-        → generate .md files for each verified library
-        → generate INTEGRATION_RISKS.md if risks detected
-/cdev   → inject paths into prompt → agent reads → validation checks
+/csetup → analyze change (type, complexity, risk)
+        → detect libraries from spec + package files
+        → Context7 resolve + fetch best practices
+        → determine research layers
+        → detect integration warnings
+        → generate critical checklist items
+        → write pre-work-context.md (single file)
+/cdev   → agents read pre-work-context.md in STEP 0
 ```
 
-**Output Files:**
-| File | Content |
-|------|---------|
-| `{lib}.md` | Library best practices with integration info |
-| `INTEGRATION_RISKS.md` | Cross-library risks + checklist (if any detected) |
-| `index.md` | Registry of all best practices files |
+**Output File:**
+| File | Sections |
+|------|----------|
+| `pre-work-context.md` | 1. Change Analysis, 2. Library Best Practices, 3. Research Findings, 4. Integration Warnings, 5. Critical Checklist, 6. Quick Reference |
 
 ---
 
@@ -212,6 +213,58 @@ Universal, framework-agnostic template for AI-assisted development.
 
 ---
 
+## 🎯 Design Validation System (v3.3.0 - NEW!)
+
+**→ See:** `@/.claude/lib/design-validator.md` for full specification
+
+**Problem Solved:**
+- uxui-frontend agent ไม่อ่าน design-system/data.yaml → CSS ไม่ตรง design
+- ux-tester อ่านแค่ code ไม่ได้เห็น actual rendered output
+- Logic กระจายหลายไฟล์ → ไม่มี enforcement
+
+**Solution: Single Source of Truth**
+
+```
+┌─────────────────────────────────────────────────────────────┐
+│                    PREVENTION (Pre-Work)                     │
+├─────────────────────────────────────────────────────────────┤
+│  Main Claude → Pre-Flight Design Check (before /cdev)        │
+│  uxui-frontend → STEP 0.5: Read data.yaml (MANDATORY)       │
+└─────────────────────────────────────────────────────────────┘
+                           ↓
+┌─────────────────────────────────────────────────────────────┐
+│                    DETECTION (Post-Work)                     │
+├─────────────────────────────────────────────────────────────┤
+│  ux-tester → Chrome DevTools Style Comparison                │
+│              Compare computed styles vs data.yaml tokens     │
+└─────────────────────────────────────────────────────────────┘
+```
+
+**What Gets Validated:**
+
+| Token Category | Example Violation | Expected |
+|----------------|-------------------|----------|
+| Colors | #3b82f6 | bg-primary (from data.yaml) |
+| Spacing | p-5, gap-7 | p-4, p-6, gap-8 (scale) |
+| Animation | duration-200 | duration-150, 300, 500ms |
+| Shadows | mixed sm+xl | consistent level |
+
+**Agent Responsibilities:**
+
+| Agent | What to Do |
+|-------|------------|
+| Main Claude | Pre-flight check before invoking uxui-frontend |
+| uxui-frontend | STEP 0.5: Read data.yaml, report loaded tokens |
+| ux-tester | Step 5.5: Chrome DevTools validation |
+
+**Files Updated:**
+- `.claude/lib/design-validator.md` (NEW - Single Source of Truth)
+- `.claude/agents/02-uxui-frontend.md` (v2.1.0 - references design-validator)
+- `.claude/agents/07-ux-tester.md` (v1.1.0 - Design Compliance Check)
+- `.claude/commands/cdev.md` (Step 4.0 - Pre-Flight Check)
+
+---
+
 ## ⚡ Context Optimization (v2.1.0)
 
 **→ See:** `@/.claude/lib/detailed-guides/context-optimization.md` for complete guide
@@ -310,6 +363,10 @@ User: "Build login system"
 **Recent versions:**
 | Version | Key Feature |
 |---------|-------------|
+| v3.3.0 | **Design Validation System** (prevention + detection, single source of truth) |
+| v3.2.0 | Consolidated Pre-Work Context (single `pre-work-context.md` for agents) |
+| v3.1.1 | Direct Best Practices Execution (Step 2.7 rewritten, no pseudocode) |
+| v3.1.0 | TDD Classification + Development Principles Injection |
 | v3.0.0 | Template-Free Architecture (AI-driven Task Analyzer v2.0) |
 | v2.8.0 | Critical Flow Injection (auto-inject security/compliance items) |
 | v2.7.0 | UX Testing Agent (persona-based, approval gate) |

package/.claude/agents/02-uxui-frontend.md

@@ -7,8 +7,9 @@ color: blue
 
 # UX-UI Frontend Agent
 
-> **Version:** 2.0.0 (Claude 4.5 Optimized)
+> **Version:** 2.1.0 (Design Validator Integration)
 > **Role:** Build UI components with mock data. Focus on design quality and accessibility.
+> **Design Validation:** `.claude/lib/design-validator.md` (Part 2)
 
 ---
 
@@ -68,27 +69,97 @@ WHY: UI development shouldn't be blocked by backend availability. Mock data enab
 
 → See `.claude/contexts/patterns/agent-discovery.md`
 
-**STEP 0.5: Load Design & Content (uxui-frontend specific)**
+---
 
-```bash
-# Check for project-specific design tokens
-Read: design-system/data.yaml
+## STEP 0.5: Load Design System (MANDATORY)
+
+→ **Full Protocol:** `.claude/lib/design-validator.md` (Part 3)
+
+**ก่อนเขียน CSS/Tailwind ใดๆ ต้องทำขั้นตอนนี้ก่อน:**
+
+### ขั้นตอนที่ 1: อ่าน design-system/data.yaml
+
+อ่านไฟล์ `design-system/data.yaml`
+
+**ถ้ามีไฟล์:** จดค่าต่อไปนี้:
+- colors: primary, secondary, background, foreground, muted, accent (พร้อม hex values)
+- spacing scale: 4, 8, 12, 16, 24, 32, 48, 64
+- animation durations: **150ms, 300ms, 500ms เท่านั้น!**
+- shadows: sm, md, lg, xl
+- typography: font family, sizes
+
+**ถ้าไม่มีไฟล์:**
+```
+⚠️ Design System NOT FOUND
+   - Path: design-system/data.yaml (missing)
+   - Fallback: Using .claude/contexts/design/*.md
+   - Recommendation: Run /designsetup to generate design system
+```
+→ อ่าน `.claude/contexts/design/*.md` แทน
+
+### ขั้นตอนที่ 2: อ่าน page-plan.md (ถ้ามี)
+
+อ่านไฟล์ `openspec/changes/{change-id}/page-plan.md`
 
-# Check for page plan (from /pageplan command)
-Read: openspec/changes/{change-id}/page-plan.md
+**ถ้ามี:**
+- ดู Component reuse list, new components, animation blueprint
+- ข้าม STEP 3 (component search) ไปเลย เพราะ page-plan ทำไว้แล้ว
+- Implement ทุก section ใน Section 2 (Page Structure)
+
+### ขั้นตอนที่ 3: Report ก่อนเริ่มเขียน code
+
+**ต้อง report นี้ก่อนเขียน CSS/Tailwind:**
+
+```
+✅ Design System Loaded (STEP 0.5)
+   - Source: design-system/data.yaml
+   - Colors: primary=#xxx, secondary=#xxx, background=#xxx, foreground=#xxx
+   - Spacing scale: 4, 8, 12, 16, 24, 32, 48, 64
+   - Animation durations: 150ms, 300ms, 500ms
+   - Shadows: sm, md, lg, xl
 ```
 
-**Priority order:**
-1. **data.yaml** (project-specific) → Use all tokens, colors, spacing, psychology
-2. **page-plan.md** (if exists) → Use component plan, content draft, animation blueprint
-3. **design/*.md** (fallback) → General design principles
+### กฎการใช้ Design Tokens
 
-**If page-plan.md exists:**
-- Extract: Component reuse list, new components, content draft, animation blueprint (Section 2.6)
-- Skip STEP 3 (component search already done)
-- Implement ALL sections from Section 2 (Page Structure)
+**ห้ามใช้ (NEVER):**
 
-WHY: page-plan.md has buyer avatar analysis and conversion-optimized content that tasks.md doesn't provide.
+| ห้าม | ตัวอย่าง |
+|------|---------|
+| Hardcoded colors | `#3b82f6`, `rgb(59,130,246)`, `text-blue-500` |
+| Arbitrary spacing | `p-5`, `gap-7`, `m-[13px]`, `p-[22px]` |
+| Random duration | `duration-200`, `duration-250`, `duration-400` |
+| Mixed shadow levels | ใช้ `shadow-sm` ที่หนึ่ง `shadow-xl` ที่อื่น |
+
+**ต้องใช้ (ALWAYS):**
+
+| ใช้ | ตัวอย่าง |
+|-----|---------|
+| Theme colors | `bg-primary`, `text-foreground`, `bg-muted` |
+| Spacing scale | `p-4`, `p-6`, `gap-8`, `m-16` |
+| Standard durations | `duration-150`, `duration-300`, `duration-500` |
+| Consistent shadows | เลือก level เดียวสำหรับ cards ทั้งหมด |
+
+### ขั้นตอนที่ 4: Report หลังเขียน code เสร็จ
+
+**ต้อง report การใช้ tokens ใน output:**
+
+```
+📊 Design Token Usage Report
+   Colors used: text-foreground, bg-primary, bg-muted, border-border
+   Spacing used: p-4, p-6, p-8, gap-4, gap-8
+   Animations: duration-150, duration-300
+   Shadows: shadow-md (consistent)
+
+   ✅ All tokens from data.yaml
+```
+
+**ถ้ามี non-standard values ต้องบอกเหตุผล:**
+
+```
+⚠️ Non-standard values used:
+   - p-5 (reason: needed odd spacing for alignment)
+   - #custom-color (reason: brand requirement not in data.yaml)
+```
 
 ---
 
@@ -311,9 +382,21 @@ Design:
 - Shadows: {level}
 - Accessibility: {features}
 
+📊 Design Token Usage Report:
+- Colors used: text-foreground, bg-primary, bg-muted, ...
+- Spacing used: p-4, p-6, gap-8, ...
+- Animations: duration-150, duration-300
+- Shadows: shadow-md
+
+✅ All tokens from data.yaml
+OR
+⚠️ Non-standard values: {list with reasons}
+
 Next Step: {next task or agent}
 ```
 
+**IMPORTANT:** Include token usage report in final output. ux-tester will validate these against data.yaml using Chrome DevTools.
+
 ---
 
 ## Handoff to Frontend Agent