Claude-Code-Workflow/.claude/skills/team-uidesign/role-specs/researcher.md

prefix, inner_loop, message_types

prefix	inner_loop	message_types
RESEARCH	false	success progress error research_ready research_progress error

Design System Researcher

Analyze existing design system, build component inventory, assess accessibility baseline, and retrieve industry-specific design intelligence via ui-ux-pro-max. Produce foundation data for downstream designer, reviewer, and implementer roles.

Phase 2: Context & Environment Detection

Input	Source	Required
Task description	From task subject/description	Yes
Session path	Extracted from task description	Yes
.msg/meta.json	/wisdom/.msg/meta.json	No

1. Extract session path and target scope from task description
2. Detect project type and tech stack from package.json or equivalent:

Package	Detected Stack
next	nextjs
react	react
vue	vue
svelte	svelte
@shadcn/ui	shadcn
(default)	html-tailwind

3. Use CLI tools (e.g., ccw cli -p "..." --tool gemini --mode analysis) or direct tools (Glob, Grep, mcp__ace-tool__search_context) to scan for existing design tokens, component files, styling patterns
4. Read industry context from session config (industry, strictness, must-have features)

Phase 3: Research Execution

Execute 4 analysis streams:

Stream 1 -- Design System Analysis:

• Search for existing design tokens (CSS variables, theme configs, token files)
• Identify styling patterns (CSS-in-JS, CSS modules, utility classes, SCSS)
• Map color palette, typography scale, spacing system
• Find component library usage (MUI, Ant Design, shadcn, custom)
• Output: <session>/research/design-system-analysis.json

Stream 2 -- Component Inventory:

• Find all UI component files; identify props/API surface
• Identify states supported (hover, focus, disabled, etc.)
• Check accessibility attributes (ARIA labels, roles)
• Map inter-component dependencies and usage counts
• Output: <session>/research/component-inventory.json

Stream 3 -- Accessibility Baseline:

• Check ARIA attribute usage patterns, keyboard navigation support
• Assess color contrast ratios (if design tokens found)
• Find focus management and semantic HTML patterns
• Output: <session>/research/accessibility-audit.json

Stream 4 -- Design Intelligence (ui-ux-pro-max):

• Call Skill(skill="ui-ux-pro-max", args="<industry> <keywords> --design-system") for design system recommendations
• Call Skill(skill="ui-ux-pro-max", args="accessibility animation responsive --domain ux") for UX guidelines
• Call Skill(skill="ui-ux-pro-max", args="<keywords> --stack <detected-stack>") for stack guidelines
• Degradation: when unavailable, use LLM general knowledge, mark _source: "llm-general-knowledge"
• Output: <session>/research/design-intelligence.json

Compile research summary metrics: design_system_exists, styling_approach, total_components, accessibility_level, design_intelligence_source, anti_patterns_count.

Phase 4: Validation & Output

1. Verify all 4 output files exist and contain valid JSON with required fields:

File	Required Fields
design-system-analysis.json	existing_tokens, styling_approach
component-inventory.json	components array
accessibility-audit.json	wcag_level
design-intelligence.json	_source, design_system

2. If any file missing or invalid, re-run corresponding stream

3. Update <session>/wisdom/.msg/meta.json under researcher namespace:

   • Read existing -> merge { "researcher": { detected_stack, component_count, wcag_level, di_source, scope } } -> write back