Frontend Component Boundaries
"One responsibility per component" sounds precise and is actually
underspecified — a component that renders a labeled input with validation has
"one responsibility" by any reasonable reading, and so does a component that
renders an entire checkout form. The rule doesn't tell you which one is
right; it just supplies false confidence for whichever granularity you picked
first. This skill replaces the slogan with the actual criteria.
Composes with the library:
- frontend-performance-budgets — the client/server component split in
RSC frameworks is a boundary decision governed by this skill, whose
performance consequence is covered there
- resilient-ui-states — where a loading/error/empty state machine lives
(owned by the fetching component vs. passed down) is a boundary decision
- non-overwhelming-ux — a boundary that fragments one user-perceived task
across many components can still be correct code architecture while
producing a confusing, disjointed UI; keep the two judgments separate
Methodological decision: five criteria, not one rule
There is no single normative source for component granularity — this is a
heuristic/methodological section, not a cited standard. Evaluate a proposed
boundary against all five; a boundary that fails most of them is probably
wrong, but a boundary that satisfies four and stretches the fifth may still
be the right call. This is a judgment call, not a formula — the failure
mode of "one responsibility" was treating a heuristic as a formula; do not
replace it with a stricter one.
- Cohesion — do the pieces inside this boundary change together because
they represent one coherent piece of UI state or behavior? (A form field's
label, input, and its own validation message are cohesive; splitting them
into three components that must be wired together by the parent on every
use is not a responsibility split, it's friction.)
- Behavior — does this boundary encapsulate a distinct interaction or
state machine (open/closed, valid/invalid, loading/error) that the rest of
the tree doesn't need to know about? A boundary around behavior hides
complexity; a boundary that just wraps markup with no behavior of its own
adds an indirection with nothing to show for it.
- Semantics — does the boundary correspond to something a person
describing the UI out loud would name ("the price card", "the filter
panel")? If the only way to describe a component's purpose requires
describing its internal implementation, the boundary is probably drawn at
the wrong level.
- Reuse — is this rendered, or plausibly about to be rendered, in more
than one place with the same behavior? Reuse is a reason to extract a
boundary, not a requirement for one — a component used exactly once is
not automatically wrong.
- Shared reason to change — when a product requirement changes, does it
touch this whole boundary as a unit, or does it touch pieces that are
artificially fused together (a data-fetching concern bundled with a purely
presentational concern that a designer would want to change independently
of the API)?
Composition over configuration (empirical/industry heuristic)
SHOULD prefer composing smaller components (children, slots, render
props) over a single component with many boolean/variant props controlling
its internals. Applies when the variations represent genuinely different
content or behavior. Does not apply when the "variants" are truly just
styling toggles on otherwise-identical markup — in that case a single
component with a variant prop is simpler than five near-duplicate
components.
A prop list is a warning sign at the point where a caller has to read the
component's internals to know which combination of props is valid — that's
config-space explosion, not flexibility.
Props describe intent, not implementation (heuristic)
onSelect, onConfirm, onDismiss describe what the consumer is doing;
handleClick, handleChange describe what the component does internally and
leak that detail to every caller. SHOULD name props/events for the
caller's intent. This is a naming heuristic, not a structural boundary rule —
it doesn't change where the boundary is, only how legible it is once drawn.
Local state by default (heuristic, not a rule about component size)
SHOULD keep state local to the component that owns the behavior it
drives, and lift it only when a sibling or ancestor genuinely needs to read
or drive the same state. MUST NOT lift state to global/context by default
"in case it's needed later" — that's speculative coupling, and it makes every
consumer of the global state a hidden dependency on every other one.
Failure modes / anti-patterns
- Ceremonial fragmentation: splitting a cohesive unit (label + input +
error) into three separate component files because "one responsibility"
was read as "one DOM element," producing a parent that has to manually wire
IDs, ARIA attributes, and state between them — the split adds a place to
break
aria-describedby wiring, it doesn't remove complexity.
- God component: the inverse failure — one component doing data fetching,
business logic, and rendering of an entire page section, where no single
criterion above justifies keeping it fused (fails cohesion and shared
reason to change, because a copy-change and an API-change now touch the
same file for unrelated reasons).
- Boolean prop explosion: a component with
isCompact, isDark,
hideFooter, showIcon, variant, each combination untested, most
combinations never actually rendered — a config surface nobody can reason
about, disguised as one component.
- Premature global state: state lifted to context/global store "for
reusability" before a second consumer exists — every future reader of that
state now has to understand a wider blast radius than the feature needed.
- Reuse-driven fragmentation with divergent behavior: two call sites that
look similar today are forced to share one component, and future changes
add branching (
if (variant === 'checkout')) inside it instead of letting
them diverge — reuse was a reason to extract, not a reason to weld
permanently.
Verifiable checks
1---2name: frontend-component-boundaries3description: Decide where to cut a frontend component's boundary by cohesion, behavior, semantics, reuse, and shared reasons to change — not by a mechanical "one responsibility per component" rule that produces ceremonial fragmentation. Use whenever creating a new component, splitting or merging existing ones, or reviewing a PR that adds/removes component files. Trigger on "should this be its own component", "this component is doing too much", "prop drilling", "too many props", "extract a component", "where does this state live". Not a naming/style-guide skill — it's about the structural decision of where the boundary goes.4metadata:5 source: https://skillmd.com/skills/annatchijova/frontend-component-boundaries6---78# Frontend Component Boundaries910"One responsibility per component" sounds precise and is actually11underspecified — a component that renders a labeled input with validation has12"one responsibility" by any reasonable reading, and so does a component that13renders an entire checkout form. The rule doesn't tell you which one is14right; it just supplies false confidence for whichever granularity you picked15first. This skill replaces the slogan with the actual criteria.1617Composes with the library:1819- **frontend-performance-budgets** — the client/server component split in20 RSC frameworks is a boundary decision governed by *this* skill, whose21 performance consequence is covered *there*22- **resilient-ui-states** — where a loading/error/empty state machine lives23 (owned by the fetching component vs. passed down) is a boundary decision24- **non-overwhelming-ux** — a boundary that fragments one user-perceived task25 across many components can still be correct code architecture while26 producing a confusing, disjointed UI; keep the two judgments separate2728---2930## Methodological decision: five criteria, not one rule3132There is no single normative source for component granularity — this is a33heuristic/methodological section, not a cited standard. Evaluate a proposed34boundary against all five; a boundary that fails most of them is probably35wrong, but a boundary that satisfies four and stretches the fifth may still36be the right call. **This is a judgment call, not a formula** — the failure37mode of "one responsibility" was treating a heuristic as a formula; do not38replace it with a stricter one.39401. **Cohesion** — do the pieces inside this boundary change together because41 they represent one coherent piece of UI state or behavior? (A form field's42 label, input, and its own validation message are cohesive; splitting them43 into three components that must be wired together by the parent on every44 use is not a responsibility split, it's friction.)452. **Behavior** — does this boundary encapsulate a distinct interaction or46 state machine (open/closed, valid/invalid, loading/error) that the rest of47 the tree doesn't need to know about? A boundary around behavior hides48 complexity; a boundary that just wraps markup with no behavior of its own49 adds an indirection with nothing to show for it.503. **Semantics** — does the boundary correspond to something a person51 describing the UI out loud would name ("the price card", "the filter52 panel")? If the only way to describe a component's purpose requires53 describing its internal implementation, the boundary is probably drawn at54 the wrong level.554. **Reuse** — is this rendered, or plausibly about to be rendered, in more56 than one place with the same behavior? Reuse is a *reason* to extract a57 boundary, not a *requirement* for one — a component used exactly once is58 not automatically wrong.595. **Shared reason to change** — when a product requirement changes, does it60 touch this whole boundary as a unit, or does it touch pieces that are61 artificially fused together (a data-fetching concern bundled with a purely62 presentational concern that a designer would want to change independently63 of the API)?6465## Composition over configuration (empirical/industry heuristic)6667**SHOULD** prefer composing smaller components (children, slots, render68props) over a single component with many boolean/variant props controlling69its internals. **Applies when** the variations represent genuinely different70content or behavior. **Does not apply** when the "variants" are truly just71styling toggles on otherwise-identical markup — in that case a single72component with a `variant` prop is simpler than five near-duplicate73components.7475A prop list is a warning sign at the point where a caller has to read the76component's internals to know which combination of props is valid — that's77config-space explosion, not flexibility.7879## Props describe intent, not implementation (heuristic)8081`onSelect`, `onConfirm`, `onDismiss` describe what the consumer is doing;82`handleClick`, `handleChange` describe what the component does internally and83leak that detail to every caller. **SHOULD** name props/events for the84caller's intent. This is a naming heuristic, not a structural boundary rule —85it doesn't change where the boundary is, only how legible it is once drawn.8687## Local state by default (heuristic, not a rule about component size)8889**SHOULD** keep state local to the component that owns the behavior it90drives, and lift it only when a sibling or ancestor genuinely needs to read91or drive the same state. **MUST NOT** lift state to global/context by default92"in case it's needed later" — that's speculative coupling, and it makes every93consumer of the global state a hidden dependency on every other one.9495## Failure modes / anti-patterns9697- **Ceremonial fragmentation**: splitting a cohesive unit (label + input +98 error) into three separate component files because "one responsibility"99 was read as "one DOM element," producing a parent that has to manually wire100 IDs, ARIA attributes, and state between them — the split *adds* a place to101 break `aria-describedby` wiring, it doesn't remove complexity.102- **God component**: the inverse failure — one component doing data fetching,103 business logic, and rendering of an entire page section, where no single104 criterion above justifies keeping it fused (fails cohesion *and* shared105 reason to change, because a copy-change and an API-change now touch the106 same file for unrelated reasons).107- **Boolean prop explosion**: a component with `isCompact`, `isDark`,108 `hideFooter`, `showIcon`, `variant`, each combination untested, most109 combinations never actually rendered — a config surface nobody can reason110 about, disguised as one component.111- **Premature global state**: state lifted to context/global store "for112 reusability" before a second consumer exists — every future reader of that113 state now has to understand a wider blast radius than the feature needed.114- **Reuse-driven fragmentation with divergent behavior**: two call sites that115 look similar today are forced to share one component, and future changes116 add branching (`if (variant === 'checkout')`) inside it instead of letting117 them diverge — reuse was a reason to extract, not a reason to weld118 permanently.119120## Verifiable checks121122- [ ] For each component boundary, at least one of the five criteria123 (cohesion, behavior, semantics, reuse, shared reason to change) is124 articulable in one sentence — if none apply, question the split.125- [ ] No component requires the parent to manually re-wire ARIA126 relationships (`aria-describedby`, `aria-controls`) across a split that127 exists for organizational reasons only.128- [ ] Boolean/variant props on a single component: if there are more than129 ~4-5, or combinations exist that are never actually used, the130 component is a candidate for splitting by variant instead of branching131 internally.132- [ ] State lives in the lowest common owner of the components that need it133 — not lifted further "for later" without a current second consumer.134- [ ] Prop and event names describe what the caller is doing135 (`onSelect`/`onConfirm`) rather than the component's internal handler136 name.