ux-atomic-design

What this skill does

<!-- VERSION: 1.2.0 | DATE: 2026-03-04 | SOURCE: skills/user-experience/SKILL.md | PARENT: /user-experience skill | REVISION: iter3 quality gate fixes — evidence quality (Phase 5 Activity 3 maturity thresholds labeled as heuristics with drift-ratio-based token governance criteria), actionability (Phase 5 Activity 3 coverage metric specified as component coverage from Phase 4 Activity 1; Phase 1 Activity 2 wave entry verification evidence source added) -->

# Atomic Design Sub-Skill

> **Version:** 1.2.0
> **Framework:** Jerry User-Experience -- Atomic Design
> **Constitutional Compliance:** Jerry Constitution v1.0
> **Parent Skill:** `/user-experience` (`skills/user-experience/SKILL.md`)
> **Wave:** 3 (Design System)
> **Project:** PROJ-022 User Experience Skill | GitHub Issue [#138](https://github.com/geekatron/jerry/issues/138)

## Document Sections

| Section | Purpose |
|---------|---------|
| [Document Audience](#document-audience-triple-lens) | Triple-Lens audience guide |
| [Purpose](#purpose) | Sub-skill overview and key capabilities |
| [When to Use This Sub-Skill](#when-to-use-this-sub-skill) | Activation triggers and scope boundaries |
| [Available Agents](#available-agents) | Single agent with role, model, and output location |
| [P-003 Compliance](#p-003-compliance) | Worker agent hierarchy position |
| [Invoking the Agent](#invoking-the-agent) | Invocation via ux-orchestrator |
| [Methodology](#methodology) | Brad Frost's 5-level hierarchy, design tokens, composition rules, Storybook coverage model, 5-phase execution procedure |
| [MCP Dependencies](#mcp-dependencies) | Storybook REQ with manual fallback; Figma ENH; Zeroheight ENH; Context7 for component library docs |
| [Output Specification](#output-specification) | Output location, L0/L1/L2 structure, required sections |
| [Routing](#routing) | Keywords and lifecycle-stage routing integration |
| [Cross-Framework Integration](#cross-framework-integration) | Handoff from heuristic evaluation and to inclusive design |
| [Synthesis Hypothesis Confidence](#synthesis-hypothesis-confidence) | Confidence classifications for Atomic Design outputs |
| [Constitutional Compliance](#constitutional-compliance) | Governing principles and AI-augmented analysis limitations |
| [Registration](#registration) | H-26 parent-routed registration model and AGENTS.md confirmation |
| [Deployment Status](#deployment-status) | Wave 3 stub agent status and implementation timeline |
| [Quick Reference](#quick-reference) | Common workflows and agent selection hints |
| [References](#references) | Full repo-relative paths, requirements traceability, external citations |

## Document Audience (Triple-Lens)

This SKILL.md serves multiple audiences:

| Level | Audience | Sections to Focus On |
|-------|----------|---------------------|
| **L0 (Stakeholder)** | Product managers, designers | [Purpose](#purpose), [When to Use This Sub-Skill](#when-to-use-this-sub-skill), [Quick Reference](#quick-reference) |
| **L1 (Developer)** | Engineers invoking the agent | [Invoking the Agent](#invoking-the-agent), [Methodology](#methodology), [Output Specification](#output-specification) |
| **L2 (Architect)** | Workflow designers, skill maintainers | [Cross-Framework Integration](#cross-framework-integration), [MCP Dependencies](#mcp-dependencies), [Synthesis Hypothesis Confidence](#synthesis-hypothesis-confidence) |

---

## Purpose

The Atomic Design sub-skill provides structured component taxonomy architecture using Brad Frost's Atomic Design methodology (2016). It targets tiny teams (1-5 people) who need to move beyond ad-hoc component creation toward a systematic, hierarchical design system that promotes consistency, reuse, and scalability across their product interface.

This sub-skill is part of Wave 3 (Design System), meaning it requires Wave 2 completion (launched product with analytics OR 1 completed Lean UX hypothesis cycle) before deployment. It bridges the gap between iterative experimentation (Wave 2) and accessibility evaluation (Wave 3: Inclusive Design) by providing a structured component inventory that the inclusive design evaluator can audit.

### Key Capabilities

- **5-Level Component Taxonomy** -- Classifies interface elements into Atoms, Molecules, Organisms, Templates, and Pages following Brad Frost's hierarchy, establishing a shared vocabulary for design and development
- **Design Token Auditing** -- Inventories and validates design tokens (colors, typography, spacing, breakpoints) for consistency across the component hierarchy, identifying token drift and redundancy
- **Component Inventory Construction** -- Produces comprehensive inventories of existing components with classification level, Storybook coverage status, reuse frequency, and variant count
- **Composition Rule Documentation** -- Documents valid composition patterns (which atoms compose which molecules, which molecules compose which organisms) to prevent inconsistent component assembly
- **Storybook Integration Assessment** -- Evaluates component library documentation coverage in Storybook, identifying components without stories, missing states, and undocumented variants
- **Component Reuse Analysis** -- Identifies duplicate or near-duplicate components that should be consolidated, quantifying reuse opportunities and estimating design debt reduction

> **Source:** Key capabilities derived from parent SKILL.md [skills/user-experience/SKILL.md Section "Key Capabilities"] ("Atomic Design -- Brad Frost's 5-level component taxonomy (Wave 3)") and [skills/user-experience/SKILL.md Section "Available Agents"] ("Atomic design component taxonomy architect").

---

## When to Use This Sub-Skill

Activate when:

- Building or refactoring a component library and need a systematic classification framework
- Auditing an existing design system for component hierarchy completeness and consistency
- Inventorying components with their Storybook coverage status for gap identification
- Analyzing design token consistency across a component hierarchy (colors, typography, spacing)
- Documenting composition rules between atoms, molecules, and organisms
- Identifying duplicate or near-duplicate components for consolidation
- Preparing a component inventory for downstream accessibility evaluation
- Transitioning from ad-hoc component creation to a structured design system during the "During design" lifecycle stage

Do NOT use for:

- Evaluating an existing interface against usability heuristics -- use `/ux-heuristic-eval` (Nielsen's 10) instead. Atomic Design classifies components; heuristic evaluation assesses usability quality.
- Accessibility compliance auditing -- use `/ux-inclusive-design` (WCAG 2.2) instead. Atomic Design produces the component inventory that inclusive design evaluates for accessibility. Use this sub-skill first, then pass the inventory to `/ux-inclusive-design`.
- Testing hypotheses about design changes -- use `/ux-lean-ux` (Lean UX) instead. Atomic Design structures components; Lean UX tests whether design changes improve outcomes.
- Measuring quantitative UX health metrics -- use `/ux-heart-metrics` (Google GSM) instead. Atomic Design focuses on component architecture, not metric measurement.
- Understanding user motivations and jobs -- use `/ux-jtbd` (Jobs-to-Be-Done) instead. Atomic Design operates at the component level, not the user motivation level.
- Diagnosing why users fail to take a specific action -- use `/ux-behavior-design` (Fogg B=MAP) instead. Atomic Design focuses on structural component classification, not behavioral diagnosis.
- Running a full rapid prototyping sprint -- use `/ux-design-sprint` (Design Sprint 2.0) instead.
- Security-focused interface review -- use `/eng-team` instead.
- General research without UX component focus -- use `/problem-solving` instead.

> **Source:** Routing logic derived from [skills/user-experience/SKILL.md Section "Lifecycle-Stage Routing"] ("During design: Building component system -> /ux-