Richie
87e596ddb2
- docs/reference/component-lifecycle.md: 10-stage quality gate sequence (build → stories → audit/critique/harden → fix → polish → present → iterate → normalize → preflight → commit) - docs/reference/retroactive-review-plan.md: Plan to review 30+ existing components using condensed process (~3.5 sessions) - Updated /build-atom, /build-molecule, /build-organism to include internal QA stages automatically - CLAUDE.md: added lifecycle reference as critical rule #8 Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
155 lines
6.9 KiB
Markdown
155 lines
6.9 KiB
Markdown
# Component Lifecycle
|
|
|
|
Every component follows this lifecycle. Skills are run in order — each stage must
|
|
pass before moving to the next. This prevents ad-hoc back-and-forth tweaking.
|
|
|
|
## The Stages
|
|
|
|
```
|
|
┌─────────────────────────────────────────────────────────────┐
|
|
│ 1. BUILD /build-atom, /build-molecule, /build-organism │
|
|
│ 2. STORIES /write-stories │
|
|
│ 3. INTERNAL QA /audit → /critique → /harden │
|
|
│ 4. FIX Fix all P0 and P1 issues from stage 3 │
|
|
│ 5. POLISH /polish → /typeset → /adapt │
|
|
│ 6. PRESENT Show to user in Storybook │
|
|
│ 7. ITERATE User feedback → targeted fixes (1-2 rounds) │
|
|
│ 8. NORMALIZE /normalize (cross-component consistency) │
|
|
│ 9. PREFLIGHT /preflight │
|
|
│ 10. COMMIT git add → commit → push │
|
|
└─────────────────────────────────────────────────────────────┘
|
|
```
|
|
|
|
## When to use each skill
|
|
|
|
### Stage 1 — BUILD
|
|
**Skill:** `/build-atom`, `/build-molecule`, `/build-organism`
|
|
**When:** Starting a new component. The skill handles reading memory files,
|
|
checking the registry, creating the file structure, and writing the code.
|
|
**Output:** Component .tsx + stories .tsx + index.ts
|
|
|
|
### Stage 2 — STORIES
|
|
**Skill:** `/write-stories`
|
|
**When:** If the build skill didn't produce comprehensive stories, or if stories
|
|
need updating after changes. Stories must cover: default, all variants, all
|
|
sizes, disabled, loading, error, long content, minimal content.
|
|
**Output:** Complete story coverage in Storybook
|
|
|
|
### Stage 3 — INTERNAL QA (run before showing to user)
|
|
Three skills, run in this order:
|
|
|
|
1. **`/audit`** — Technical quality (a11y, performance, theming, responsive, design).
|
|
Produces a score out of 20 and P0-P3 issues.
|
|
2. **`/critique`** — UX design review (hierarchy, emotion, cognitive load, composition).
|
|
Produces a score out of 40 and priority issues.
|
|
3. **`/harden`** — Edge cases (error states, empty states, loading, boundaries, disabled).
|
|
Ensures robustness for real-world data.
|
|
|
|
**Exit criteria:** No P0 issues remaining. P1 issues documented.
|
|
|
|
### Stage 4 — FIX
|
|
**No skill — just implementation work.**
|
|
**When:** Fix all P0 and P1 issues found in stage 3.
|
|
Then re-run the relevant check (e.g., if the fix was an a11y issue, re-run
|
|
`/audit` to verify). Don't re-run all three unless the fixes were broad.
|
|
**Exit criteria:** P0 = 0, P1 = 0 (or documented as intentional with rationale).
|
|
|
|
### Stage 5 — POLISH
|
|
Three skills, run as needed based on the component:
|
|
|
|
1. **`/polish`** — Visual alignment, spacing, transitions, copy, micro-details.
|
|
Run on every component.
|
|
2. **`/typeset`** — Typography: hierarchy, line length, weight, readability.
|
|
Run on text-heavy components (cards, forms, detail panels).
|
|
3. **`/adapt`** — Responsive: touch targets, overflow, mobile spacing.
|
|
Run on layout components (organisms, cards, navigation).
|
|
|
|
**Optional context-specific skills:**
|
|
- **`/quieter`** — Run on components that handle sensitive moments (pricing,
|
|
commitment steps, error messaging). Not needed for utility atoms.
|
|
- **`/clarify`** — Run on components with decision points or complex information
|
|
(FuneralFinder, ArrangementForm, PricingTable). Not needed for simple atoms.
|
|
|
|
### Stage 6 — PRESENT
|
|
**No skill — show in Storybook.**
|
|
**When:** All internal QA is done. The component should be in its best state
|
|
before the user sees it. Present with a brief summary of what it does, key
|
|
design decisions, and scores from audit/critique.
|
|
|
|
### Stage 7 — ITERATE
|
|
**No skill — targeted fixes from user feedback.**
|
|
**When:** User reviews in Storybook and gives feedback. This should be 1-2 rounds
|
|
max because stages 3-5 caught most issues. If feedback requires major changes,
|
|
go back to stage 1. Minor tweaks stay here.
|
|
**Exit criteria:** User approves.
|
|
|
|
### Stage 8 — NORMALIZE
|
|
**Skill:** `/normalize`
|
|
**When:** After user approval, run against the component's tier (e.g., `/normalize atoms`)
|
|
to check it's consistent with its peers. This catches: token access patterns (D031),
|
|
transition timing, focus styles, spacing methods, displayName, exports.
|
|
**Note:** This is a cross-component check, so it's most valuable after several
|
|
components in a tier are done. Can be batched.
|
|
|
|
### Stage 9 — PREFLIGHT
|
|
**Skill:** `/preflight`
|
|
**When:** Before committing. Verifies TypeScript, Storybook build, token sync,
|
|
hardcoded values, exports, ESLint, Prettier.
|
|
**Exit criteria:** All critical checks pass.
|
|
|
|
### Stage 10 — COMMIT
|
|
**No skill — git workflow.**
|
|
Stage, commit with descriptive message, push. Husky runs lint-staged automatically.
|
|
|
|
---
|
|
|
|
## Shorthand for quick reference
|
|
|
|
| Stage | Skill(s) | Who triggers | Blocking? |
|
|
|-------|----------|-------------|-----------|
|
|
| Build | /build-{tier} | User requests | — |
|
|
| Stories | /write-stories | Auto in build | — |
|
|
| Internal QA | /audit → /critique → /harden | Agent (auto) | P0 = blocking |
|
|
| Fix | — | Agent | Until P0/P1 = 0 |
|
|
| Polish | /polish + /typeset + /adapt | Agent (auto) | — |
|
|
| Present | — | Agent → User | — |
|
|
| Iterate | — | User feedback | 1-2 rounds |
|
|
| Normalize | /normalize | Agent (batch OK) | — |
|
|
| Preflight | /preflight | Agent (auto) | Critical = blocking |
|
|
| Commit | — | Agent | — |
|
|
|
|
**"Agent (auto)"** means I should run these proactively without being asked.
|
|
**"Agent (batch OK)"** means it can be deferred and run across multiple components.
|
|
|
|
---
|
|
|
|
## Which skills are optional vs required?
|
|
|
|
| Skill | Required for | Optional for |
|
|
|-------|-------------|-------------|
|
|
| /audit | All components | — |
|
|
| /critique | All molecules + organisms | Simple atoms (Button, Divider) |
|
|
| /harden | All interactive components | Display-only atoms (Typography, Badge) |
|
|
| /polish | All components | — |
|
|
| /typeset | Text-heavy components | Icon-only or structural components |
|
|
| /adapt | Layout components, organisms | Small inline atoms |
|
|
| /quieter | Sensitive context components | Utility atoms |
|
|
| /clarify | Decision-point components | Simple atoms |
|
|
| /normalize | All (batched by tier) | — |
|
|
| /preflight | All (before commit) | — |
|
|
|
|
---
|
|
|
|
## For existing components
|
|
|
|
Components built before this lifecycle was defined can be retroactively
|
|
reviewed using a condensed process:
|
|
|
|
1. `/normalize {tier}` — Scan the tier for consistency issues
|
|
2. `/audit {component}` — Score each component
|
|
3. Fix P0/P1 issues only (don't re-polish what's already working)
|
|
4. `/preflight` → commit
|
|
|
|
This is lighter than the full lifecycle because these components have already
|
|
been through user review and iteration.
|