[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:

Scan & Update Reference Doc — Read existing doc first, scan codebase for current state, diff against doc content, update only changed sections, preserve manual annotations. MUST READ .claude/skills/shared/scan-and-update-reference-doc-protocol.md for full protocol and checklists.

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

• MUST break work into small todo tasks using TaskCreate BEFORE starting
• MUST search codebase for 3+ similar patterns before creating new code
• MUST cite file:line evidence for every claim (confidence >80% to act)
• MUST add a final review todo task to verify work quality MANDATORY IMPORTANT MUST READ the following files before starting:
• MUST READ .claude/skills/shared/scan-and-update-reference-doc-protocol.md before starting