component-architecture
Skill30 starsChanged 5 months agoMITView on GitHub
Audit and refactor a frontend codebase's component structure, or design a component library from scratch, using atomic design, composition, and disciplined prop interfaces. Use when the user says 'my components are a mess', 'this component is 800 lines', 'refactor my components', 'build a component library', 'how should I structure my components', 'too much prop drilling', 'we keep rebuilding the same button', or asks where a new component should live — even if they never say 'atomic design'. Produces a component inventory audit, refactored component code (extracted atoms/molecules, typed prop interfaces, variant systems), and per-component documentation.
6 other projects use a version of this.
Adopted by
Most recently taken up by
- bfernandois059/dev-workflow-skillstheir own version, first seen Oct 20, 2026
- yogvidwankhede/vishwakarmatheir own version, first seen Sep 26, 2026
- nahid-sparktales/agent-dispatchertheir own version, first seen Sep 21, 2026
- batur/ts-baseline-docstheir own version, first seen Jul 29, 2026
- Deepak-Dhungel/claude-code-skillstheir own version, first seen Jun 4, 2026
- basidiocarp/pileustheir own version, first seen May 25, 2026
Other versions6 projects use a version of this.
Word for word · 0
None found.
Edited · 0
None found.
Wrote their own version · 6
- nahid-sparktales/agent-dispatcher★ 59same name
- batur/ts-baseline-docs★ 1same name
- bfernandois059/dev-workflow-skills★ 1same name
- Deepak-Dhungel/claude-code-skills★ 1same name
- yogvidwankhede/vishwakarma★ 1same name
- basidiocarp/pileus★ 0same name
How matches are found. Word for word: the exact same text. Edited: shares passages with this file (“99% same” means 99% of its five-word phrases also appear here; 10% or more counts). Their own version: similar meaning, or, weakest, the same name. We can’t tell which project had it first. Projects are counted among the 200 most-starred candidates, and mentions are links to the repository we found, up to 50 per site, so both counts are a floor.
In this repository39 other files it gives its agents.
- brand-assetSkill
- creative-strategistSkill
- image-generationSkill
- orchestratorSkill
- original-designSkill
- product-photographySkill
- product-videoSkill
- remotion-script-writerSkill
- social-graphicsSkill
- talking-headSkill
- accessibility-excellenceSkill
- color-systemSkill
- design-engineer-mindsetSkill
- design-foundationSkill
- error-handling-recoverySkill
- frontend-orchestratorSkill
- interaction-physicsSkill
- layout-systemSkill
- loading-statesSkill
- performance-optimizationSkill
- typography-systemSkill
- visual-hierarchy-refactoringSkill
- brand-voiceSkill
- content-atomizerSkill
- direct-response-copySkill
- email-sequencesSkill
- keyword-researchSkill
- lead-magnetSkill
- newsletterSkill
- orchestratorSkill
- positioning-anglesSkill
- seo-contentSkill
- seo-strategySkill
- tweet-writerSkill
- product-design-reviewSkill
- fable-like-implementationSkill
- foundation-sprintSkill
- sol-orchestratorSkill
- sprint-runnerSkill
The file
We split this skill into the rules it gives an agent
5 rules. 0 are common, 4 are distinctive, and 1 is very specific to this project.
0
Common
Most of the 6 edited versions we read keep these.
4
Distinctive
This author's own choices. Worth a look.
1
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Distinctive: line 12
Use for: component decomposition, prop interface design, variant systems, extracting a shared library, deciding controlled vs uncontrolled, …
- Distinctive: line 23
Before proposing anything, build a component inventory from the actual code:
- Distinctive: line 27
Check for an existing design system or UI kit (shadcn/ui, MUI, Chakra, internal package).
- Distinctive: line 51
Controlled vs uncontrolled: if any other UI must react to the value while editing (live validation, dependent fields, character counts) → …
- Very specific: line 78
Every extracted/refactored shared component gets docs: purpose, props table, variants with when-to-use, states, accessibility notes, edge …
“Common” is measured: kept by at least 6 in 10 of the 6 edited versions of this file we could read. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.
Files
Component Architecture
Turn a tangle of one-off components into a composable system: audit what exists, classify it into atomic levels, then refactor the worst offenders into small, typed, documented pieces. The prime directive: a component earns its existence by having one responsibility and a prop interface that makes invalid states unrepresentable. Deliver working refactored code plus an audit the user can act on — never just advice.
When to use / when not to
Use for: component decomposition, prop interface design, variant systems, extracting a shared library, deciding controlled vs uncontrolled, component documentation.
Hand off instead when the real need is:
- Visual tokens (spacing, color, type scales) →
skills/frontend-design/design-foundation - Animation/feedback inside components →
skills/frontend-design/interaction-physics - Keyboard/ARIA behavior of components →
skills/frontend-design/accessibility-excellence - Render performance (memoization, re-renders) →
skills/frontend-design/performance-optimization - Unsure where to start across the whole frontend →
skills/frontend-design/frontend-orchestrator
Step 0 — Inspect the codebase, then ask only what's left
Before proposing anything, build a component inventory from the actual code:
- Locate component directories (
components/,ui/,src/app/**,lib/). Note the framework and styling approach (Tailwind, CSS Modules, CSS-in-JS, vanilla) — match it; never introduce a new styling system uninvited. - Count components and flag: files > ~200 lines, components that both fetch data and render detailed markup, duplicated UI (multiple button/input/card implementations), inline styles repeating the same values, class-based inheritance.
- Check for an existing design system or UI kit (shadcn/ui, MUI, Chakra, internal package). If one exists, extend its conventions — don't build a parallel system.
Ask the user (one batch, only what the code didn't answer): scope (whole app, one feature, or one painful component?) and whether a shared library/package is the goal or just cleaner local structure. If the request already implies scope ("refactor this file"), don't ask — state assumptions and proceed.
Workflow
1. Classify the inventory into atomic levels
- Atoms — indivisible, no component dependencies: Button, Input, Label, Icon, Badge, Spinner.
- Molecules — small compositions of atoms with one purpose: FormInput (Label+Input+Error), SearchBar.
- Organisms — sections with business purpose and often state: NavBar, Card, Modal, Form.
- Templates — page layouts arranging organisms; not reusable across page types.
- Pages — templates with real data; use them to find edge cases.
Decision rule: if you can't classify a component, it's doing too much — that's a refactor candidate, not a taxonomy problem.
2. Prioritize refactors by leverage
Order: (1) duplicated atoms (consolidate first — everything else builds on them), (2) god components violating single responsibility, (3) prop interfaces that allow invalid states, (4) missing variants forcing copy-paste. Propose the top 3–5 refactors with a one-line payoff each; have the user confirm scope before rewriting broadly. For a single-component request, skip the vote and refactor it.
3. Refactor with these decision rules
- Split rule: a component that fetches data, manages form state, AND renders detailed markup becomes an orchestrator plus focused children. Split by responsibility, not by line count.
- Composition over inheritance, always. Variants are props (
variant,size), presets are thin wrappers — never subclasses. - Controlled vs uncontrolled: if any other UI must react to the value while editing (live validation, dependent fields, character counts) → controlled. Fire-and-forget input read once on submit → uncontrolled is fine. Never mix modes in one component.
- Prop interface rules: union types instead of booleans that can conflict (
variant: 'primary' | 'danger', notisPrimary+isDanger); constrain to valid options; pass throughclassNameand ARIA attributes; callbacks namedon<Event>. If two boolean props can combine into an invalid state, redesign the interface. - Extraction threshold: extract a shared component at the 2nd–3rd duplication if the copies are genuinely the same concept. Two things that look alike but change for different reasons stay separate — wrong abstractions cost more than duplication.
Canonical shape for an atom (full gallery in references/patterns.md):
interface ButtonProps {
variant?: 'primary' | 'secondary' | 'ghost' | 'danger';
size?: 'sm' | 'md' | 'lg';
disabled?: boolean;
loading?: boolean;
onClick?: () => void;
children: React.ReactNode;
}
export const Button = ({ variant = 'primary', size = 'md', disabled, loading, ...rest }: ButtonProps) => (
<button
className={`button button--${variant} button--${size}`}
disabled={disabled || loading}
{...rest}
/>
);4. Document what you build
Every extracted/refactored shared component gets docs: purpose, props table, variants with when-to-use, states, accessibility notes, edge cases. Use the template in references/patterns.md. Put docs where the team will see them (Storybook stories if Storybook exists, otherwise a colocated README.md or JSDoc).
Required output format
Deliver both artifacts:
1. The code — refactored/created component files, edited in place, following the project's existing styling and naming conventions. All call sites updated; the app must still compile.
2. Component Architecture Audit (markdown):
## Component Inventory
| Component | File | Level | Verdict | Issue |
| Button (x3 impls) | src/... | atom | consolidate | 3 duplicate implementations |
| UserProfile | src/... | ??? | split | fetches + validates + renders (412 lines) |
| Card | src/... | organism | keep | — |
## Refactors applied
1. [name] — what changed, files touched, why (one line each)
## Refactors recommended (not applied)
1. [name] — payoff, estimated blast radius
## Conventions going forward
- Directory structure: [atoms/molecules/organisms or project's own scheme]
- Prop rules adopted: [union variants, no conflicting booleans, ...]
- When to extract: [the 2–3 rule as applied to this codebase]Quality bar (check before delivering)
- Every refactored component has exactly one responsibility you can state in one sentence
- No prop interface permits an invalid state (no conflicting booleans, no unconstrained strings for variants)
- No inheritance for variants anywhere in delivered code
- Each shared component is explicitly controlled or uncontrolled, never both
- Interactive components keep keyboard operability and visible focus (don't strip what existed)
- All call sites updated; imports resolve; existing styling system respected
- Every new shared component has docs (purpose, props, variants, states)
- Audit table covers the inspected scope, not just the files you touched
Hard don'ts: don't rename the user's public component APIs without flagging it as breaking; don't introduce a new state-management or styling library as a side effect; don't atomize prematurely — a 40-line coherent component doesn't need splitting.
Integration
skills/frontend-design/design-foundation→ feeds this skill the token vocabulary components should consume (spacing/color/type variables).skills/frontend-design/interaction-physics← consumes your component states (hover/active/loading) and animates them.skills/frontend-design/loading-statesandskills/frontend-design/error-handling-recovery← consume your component inventory to add loading/error variants systematically.skills/frontend-design/accessibility-excellence← audits the components you produce; build with semantic elements so it has less to fix.
References
references/patterns.md— full code examples per atomic level, single-responsibility before/after, controlled/uncontrolled implementations, the component documentation template, and size conventions. Read it when actually writing the refactored code or docs.
Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

