Component Architecture
Right-size a component — one responsibility, least state, composition over 15 boolean props. Fix the boundary, not the symptom.
v1.0.0 · ~598 tokens · ⬇ 0 · Updated July 6, 2026
What it does
Designs/refactors a component around clean boundaries: one responsibility, presentational vs container split, composition over configuration (kill boolean-prop explosion), own the least state and lift only when shared, derive don't store, a minimal specific prop/event contract. Splits oversized components by responsibility with a reason for each.
Example uses
Split a 500-line component
One component fetches data, transforms it, renders three views, and handles every event — and every change breaks something.
UserDashboard.tsx is 540 lines: it fetches three endpoints, computes stats, renders a table, a chart, and a filter bar, and owns 11 useState hooks. Split it by responsibility — a container for data, presentational components for the table, chart, and filters, and a hook for the stats derivation — and give me the prop and event contract for each piece with the reason for every split.Kill the boolean-prop explosion
A shared component has grown a dozen boolean props that fork rendering and nobody knows which combinations are valid.
Our shared Modal component takes isConfirm, isDanger, hasFooter, hideClose, isFullscreen, and nine more booleans, and half the combinations render broken layouts. Refactor toward composition — a base Modal with children and slots plus a small set of specific variants — and show the migration path for the roughly 40 existing call sites.Decide where state lives
Sibling components each keep their own copy of the same state and drift out of sync.
In our checkout flow, CartSummary and ShippingForm each keep their own copy of the selected shipping method, and they desync when the user goes back a step. Decide where that state should live — lifted to the nearest common parent, no higher — convert the stored totals into derived values computed from it, and show me the before and after data flow.Install
# 1. Create the skill folder in your Claude setup mkdir -p ~/.claude/skills/component-architecture # 2. Download SKILL.md into it (or move the file you just downloaded) # → ~/.claude/skills/component-architecture/SKILL.md # 3. Claude Code auto-discovers it on next launch.
Inside the skill
--- name: component-architecture description: Design or refactor a UI component with clean props, state, and composition boundaries. Use when building a non-trivial component, when one has grown messy, or when asked "how should I structure this component", "this component is too big", "review my component design". Right-sizes responsibilities. --- # Component Architecture A component should do one thing, own the minimum state, and be obvious to reuse. Most component pain is a boundary drawn in the wrong place — fix the boundary. ## Decide the boundaries - **One responsibility.** If you can't name a component in a short phrase, it's doing too much — split it. A 400-line component is usually 4 components and a hook. - **Presentational vs container**: separate "how it looks" (props in, events out, no data fetching) from "where data comes from". Presentational components are trivially testable and reusable; keep them dumb. - **Composition over configuration**: a component with 15 boolean props that fork rendering should be several components (or use `children`/slots). Flags that change layout = split. ## State: own the least, lift only when shared - Local UI state (open/hover/input) → in the component. - State two siblings need → lift to the nearest common parent, no higher. - Server data → a data hook / query layer, not tangled into render. - **Derive, don't store**: if a value can be computed from props/state, compute it — don't duplicate it into state that can drift out of sync. ## Props: a clean contract - Minimal and specific. Pass data, not the whole object if only a field is used. - Events out via callbacks (`onSelect(id)`), not by reaching into the child. - Sensible defaults; required vs optional explicit. Avoid boolean-prop explosion (see composition). - Don't leak internal structure through props — the parent shouldn't need to know how the child works. ## Rules - Draw the boundary by responsibility and reuse, not by line count alone — but line count is a smell. - Prefer composition and derived state; they remove whole classes of bugs. - A component that fetches, transforms, styles, and handles 6 events is 4 jobs — separate them. ## Output The component structure (which pieces, what each owns), the prop/event contract for each, where state lives, and the specific splits/extractions if refactoring — with the reason for each.
Changelog
- v1.0.02026-07-03Initial clean-room write.
Frequently asked questions
Is Component Architecture free?
Yes. Component Architecture is free to download and MIT-licensed.
Where do I install Component Architecture?
Place the SKILL.md file in ~/.claude/skills/component-architecture/ and Claude Code auto-discovers it on next launch.
How many tokens does Component Architecture use?
About 598 tokens — it is designed to be token-lean.
We're developers and SaaS builders who use these tools daily in production. Every review comes from hands-on experience building real products — DealPropFirm, ThePlanetIndicator, PropFirmsCodes, and many more. We don't just review tools — we build and ship with them every day.
Written and tested by developers who build with these tools daily.