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

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