scan-design-system（扫描设计系统）

[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 ATTENTION ask user whether to skip.

Prerequisites: MUST ATTENTION READ before executing:

Scan & Update Reference Doc — Surgical updates only, never full rewrite. 1. Read existing doc first — understand current structure and manual annotations 2. Detect mode: Placeholder (only headings, no content) → Init mode. Has content → Sync mode. 3. Scan codebase for current state (grep/glob for patterns, counts, file paths) 4. Diff findings vs doc content — identify stale sections only 5. Update ONLY sections where code diverged from doc. Preserve manual annotations. 6. Update metadata (date, counts, version) in frontmatter or header 7. NEVER rewrite entire doc. NEVER remove sections without evidence they're obsolete.

Output Quality — Token efficiency without sacrificing quality. 1. No inventories/counts — AI can grep | wc -l. Counts go stale instantly 2. No directory trees — AI can glob/ls. Use 1-line path conventions 3. No TOCs — AI reads linearly. TOC wastes tokens 4. No examples that repeat what rules say — one example only if non-obvious 5. Lead with answer, not reasoning. Skip filler words and preamble 6. Sacrifice grammar for concision in reports 7. Unresolved questions at end, if any

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. (content auto-injected by hook — check for [Injected:...] header before reading)

Workflow:

1. Read — Load current target doc, detect init vs sync mode
2. Scan — Discover design system structure via parallel sub-agents
3. Report — Write findings to external report file
4. Generate — Build/update reference doc from report
5. 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

1. Read docs/project-reference/design-system/README.md
2. Detect mode: init (placeholder) or sync (populated)
3. If sync: extract existing sections and note what's already well-documented
4. 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 live
• appMappings — 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

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

1. Write updated doc with <!-- Last scanned: YYYY-MM-DD --> at top
2. Verify: 3 design doc paths exist on filesystem
3. Verify: component paths in inventory match actual files
4. Report: sections updated, component count, token categories documented

Closing Reminders

• IMPORTANT MUST ATTENTION break work into small todo tasks using TaskCreate BEFORE starting
• IMPORTANT MUST ATTENTION search codebase for 3+ similar patterns before creating new code
• IMPORTANT MUST ATTENTION cite file:line evidence for every claim (confidence >80% to act)
• IMPORTANT MUST ATTENTION add a final review todo task to verify work quality
• IMPORTANT MUST ATTENTION read existing doc first, scan codebase, diff, surgical update only. Never rewrite entire doc.
• IMPORTANT MUST ATTENTION follow output quality rules: no counts/trees/TOCs, rules > descriptions, 1 example per pattern, primacy-recency anchoring.