[IMPORTANT] Use TaskCreate to break ALL work into small tasks BEFORE starting — including tasks for each file read. This prevents context loss from long files. For simple tasks, AI MUST ask user whether to skip.
Prerequisites: MUST READ before executing:
.claude/skills/shared/scan-and-update-reference-doc-protocol.md.claude/skills/shared/understand-code-first-protocol.md
Quick Summary
Goal: Scan project for design system artifacts and populate docs/project-reference/design-system/README.md with an overview of the design system, app-to-documentation mapping, design token inventory, and component catalog.
Workflow:
- Read — Load current target doc, detect init vs sync mode
- Scan — Discover design system structure via parallel sub-agents
- Report — Write findings to external report file
- Generate — Build/update reference doc from report
- Verify — Validate component paths and token files exist
Key Rules:
- Generic — works with any design system approach (custom, Storybook, Figma tokens, etc.)
- Discover design system organization dynamically from file system
- Map relationships between apps and their design documentation
- Every reference must point to real files found in this project
Be skeptical. Apply critical thinking, sequential thinking. Every claim needs traced proof, confidence percentages (Idea should be more than 80%).
Scan Design System
Phase 0: Read & Assess
- Read
docs/project-reference/design-system/README.md
- Detect mode: init (placeholder) or sync (populated)
- If sync: extract existing sections and note what's already well-documented
- Also check for app-specific design docs in the same directory
Phase 1: Plan Scan Strategy
Discover design system locations:
docs/project-reference/design-system/ directory and its contents- Storybook config (
.storybook/, *.stories.ts)
- Design token files (JSON, CSS, SCSS variables)
- Component library directories (shared components, UI kit)
- Figma token exports or style dictionary config
Use docs/project-config.json designSystem section if available for:
docsPath — where design docs liveappMappings — which apps have which design docs
Phase 2: Execute Scan (Parallel Sub-Agents)
Launch 2 Explore agents in parallel:
Agent 1: Design System Structure
- Glob for
docs/project-reference/design-system/** to map all design docs
- Find design token files (CSS custom properties, SCSS variables, JSON tokens)
- Discover Storybook stories (
*.stories.ts, *.stories.tsx, *.stories.mdx)
- Find component library entry points (index files, barrel exports)
- Look for style dictionary or token transformation configs
- Map app-to-design-doc relationships (which app uses which design doc)
Agent 2: Component Inventory
- Grep for reusable UI components (shared component directories, exported components)
- Find component categories (layout, forms, feedback, navigation, data display)
- Discover component variants (size, color, state variations)
- Count components per category
- Find icon sets or asset libraries
- Look for accessibility patterns in components (ARIA roles, keyboard support)
- Find documentation for individual components (JSDoc, README, Storybook docs)
Write all findings to: plans/reports/scan-design-system-{YYMMDD}-{HHMM}-report.md
Phase 3: Analyze & Generate
Read the report. Build these sections:
Target Sections
| Section |
Content |
| Design System Overview |
High-level description of the design system approach, tools, and organization |
| App Documentation Map |
Table: App name, Design doc path, Token source, Component library |
| Design Tokens |
Token categories (color, typography, spacing, elevation), file locations, naming convention |
| Component Inventory |
Table: Component name, Category, Variants, Path, Has docs? |
| Icon & Asset Library |
Icon set source, asset directory paths, usage patterns |
| Storybook |
Storybook setup (if exists), story organization, how to add new stories |
| Usage Guidelines |
How to consume tokens and components in application code |
Content Rules
- Use tables for component inventory and token listings
- Include actual token values (colors, spacing scale) where practical
- Show component usage examples from real application code
- Map each app to its specific design documentation file
Phase 4: Write & Verify
- Write updated doc with
<!-- Last scanned: YYYY-MM-DD --> at top
- Verify: 3 design doc paths exist on filesystem
- Verify: component paths in inventory match actual files
- Report: sections updated, component count, token categories documented
IMPORTANT Task Planning Notes (MUST FOLLOW)
- Always plan and break work into many small todo tasks using TaskCreate
- Always add a final review todo task to verify work quality and identify fixes/enhancements
1---2name: scan-design-system3description: [Documentation] Scan project and populate/sync docs/project-reference/design-system/README.md with design system overview, app-to-doc mapping, design tokens, and component inventory.4---5
6> **[IMPORTANT]** Use `TaskCreate` to break ALL work into small tasks BEFORE starting — including tasks for each file read. This prevents context loss from long files. For simple tasks, AI MUST ask user whether to skip.
7
8**Prerequisites:** **MUST READ** before executing:
9
10- `.claude/skills/shared/scan-and-update-reference-doc-protocol.md`
11- `.claude/skills/shared/understand-code-first-protocol.md`
12
13## Quick Summary
14
15**Goal:** Scan project for design system artifacts and populate `docs/project-reference/design-system/README.md` with an overview of the design system, app-to-documentation mapping, design token inventory, and component catalog.
16
17**Workflow:**
18
191. **Read** — Load current target doc, detect init vs sync mode
202. **Scan** — Discover design system structure via parallel sub-agents
213. **Report** — Write findings to external report file
224. **Generate** — Build/update reference doc from report
235. **Verify** — Validate component paths and token files exist
24
25**Key Rules:**
26
27- Generic — works with any design system approach (custom, Storybook, Figma tokens, etc.)
28- Discover design system organization dynamically from file system
29- Map relationships between apps and their design documentation
30- Every reference must point to real files found in this project
31
32**Be skeptical. Apply critical thinking, sequential thinking. Every claim needs traced proof, confidence percentages (Idea should be more than 80%).**
33
34# Scan Design System
35
36## Phase 0: Read & Assess
37
381. Read `docs/project-reference/design-system/README.md`
392. Detect mode: init (placeholder) or sync (populated)
403. If sync: extract existing sections and note what's already well-documented
414. Also check for app-specific design docs in the same directory
42
43## Phase 1: Plan Scan Strategy
44
45Discover design system locations:
46
47- `docs/project-reference/design-system/` directory and its contents
48- Storybook config (`.storybook/`, `*.stories.ts`)
49- Design token files (JSON, CSS, SCSS variables)
50- Component library directories (shared components, UI kit)
51- Figma token exports or style dictionary config
52
53Use `docs/project-config.json` designSystem section if available for:
54
55- `docsPath` — where design docs live
56- `appMappings` — which apps have which design docs
57
58## Phase 2: Execute Scan (Parallel Sub-Agents)
59
60Launch **2 Explore agents** in parallel:
61
62### Agent 1: Design System Structure
63
64- Glob for `docs/project-reference/design-system/**` to map all design docs
65- Find design token files (CSS custom properties, SCSS variables, JSON tokens)
66- Discover Storybook stories (`*.stories.ts`, `*.stories.tsx`, `*.stories.mdx`)
67- Find component library entry points (index files, barrel exports)
68- Look for style dictionary or token transformation configs
69- Map app-to-design-doc relationships (which app uses which design doc)
70
71### Agent 2: Component Inventory
72
73- Grep for reusable UI components (shared component directories, exported components)
74- Find component categories (layout, forms, feedback, navigation, data display)
75- Discover component variants (size, color, state variations)
76- Count components per category
77- Find icon sets or asset libraries
78- Look for accessibility patterns in components (ARIA roles, keyboard support)
79- Find documentation for individual components (JSDoc, README, Storybook docs)
80
81Write all findings to: `plans/reports/scan-design-system-{YYMMDD}-{HHMM}-report.md`
82
83## Phase 3: Analyze & Generate
84
85Read the report. Build these sections:
86
87### Target Sections
88
89| Section | Content |
90| -------------------------- | ------------------------------------------------------------------------------------------- |
91| **Design System Overview** | High-level description of the design system approach, tools, and organization |
92| **App Documentation Map** | Table: App name, Design doc path, Token source, Component library |
93| **Design Tokens** | Token categories (color, typography, spacing, elevation), file locations, naming convention |
94| **Component Inventory** | Table: Component name, Category, Variants, Path, Has docs? |
95| **Icon & Asset Library** | Icon set source, asset directory paths, usage patterns |
96| **Storybook** | Storybook setup (if exists), story organization, how to add new stories |
97| **Usage Guidelines** | How to consume tokens and components in application code |
98
99### Content Rules
100
101- Use tables for component inventory and token listings
102- Include actual token values (colors, spacing scale) where practical
103- Show component usage examples from real application code
104- Map each app to its specific design documentation file
105
106## Phase 4: Write & Verify
107
1081. Write updated doc with `<!-- Last scanned: YYYY-MM-DD -->` at top
1092. Verify: 3 design doc paths exist on filesystem
1103. Verify: component paths in inventory match actual files
1114. Report: sections updated, component count, token categories documented
112
113---
114
115**IMPORTANT Task Planning Notes (MUST FOLLOW)**
116
117- Always plan and break work into many small todo tasks using TaskCreate
118- Always add a final review todo task to verify work quality and identify fixes/enhancements
majiayu000