Jon Chery
87 lines
3.0 KiB
Markdown
87 lines
3.0 KiB
Markdown
# Component Design Principles
|
|
|
|
> Sibling to `first-principles.md` in this domain. These rules govern
|
|
> how individual UI components are designed, named, composed, and
|
|
> evolved.
|
|
|
|
## 1. Single Responsibility
|
|
A component does one thing, completely.
|
|
|
|
- If a component's name contains "And", split it.
|
|
- If a component has more than one primary action, split it.
|
|
- If a component's props cannot be described in one sentence, split it.
|
|
|
|
## 2. Composition Over Configuration
|
|
Components combine. They do not configure.
|
|
|
|
- Prefer small, composable primitives over large, configurable ones.
|
|
- Variants are separate components, not boolean props.
|
|
- Layout is composition. The component owns its content, not its
|
|
position.
|
|
- A `Button` is not `Button primary large loading disabled`. It is
|
|
`Button` composed with `<Icon>`, `<Spinner>`, and styled by context.
|
|
|
|
## 3. Explicit Boundaries
|
|
A component's contract is its props and its events.
|
|
|
|
- All inputs are typed. Required inputs are required.
|
|
- All outputs are typed. Events are named for what happened, not what
|
|
was clicked.
|
|
- A component never reads from global state implicitly.
|
|
- A component never mutates its inputs.
|
|
|
|
## 4. Predictable State
|
|
A component's state is owned at the lowest level that can manage it.
|
|
|
|
- If only the component cares, the component owns it.
|
|
- If siblings care, the parent owns it.
|
|
- If the world cares, the application owns it.
|
|
- State is never duplicated across levels.
|
|
|
|
## 5. Render Purity
|
|
Given the same props and state, a component renders the same output.
|
|
|
|
- No hidden inputs (time, randomness, network) inside the render path.
|
|
- Side effects are in effects, event handlers, or data loaders — not
|
|
in render.
|
|
- A component's render is safe to call repeatedly.
|
|
|
|
## 6. Accessible by Default
|
|
A component is not finished until it is accessible.
|
|
|
|
- Every interactive component is keyboard-reachable and screen-reader
|
|
announced.
|
|
- Every form control has a label.
|
|
- Every image has alt text or is marked decorative.
|
|
- Every focusable element has a visible focus state.
|
|
- Accessibility is in the component contract, not a wrapper.
|
|
|
|
## 7. Style via Tokens
|
|
A component references design tokens, never raw values.
|
|
|
|
- No hardcoded colors, sizes, or fonts in component code.
|
|
- Tokens are the API to the design system.
|
|
- A component without a token is a design debt.
|
|
|
|
## 8. Stable Identity
|
|
A component's identity is its public name, not its implementation.
|
|
|
|
- Renaming a component is a breaking change.
|
|
- Removing a prop is a breaking change.
|
|
- Changing a prop's semantics is a breaking change.
|
|
- Deprecate before you delete. Migrate before you rename.
|
|
|
|
## 9. Testable in Isolation
|
|
A component can be rendered, interacted with, and verified in isolation.
|
|
|
|
- Components ship with stories, examples, or fixtures.
|
|
- Tests cover behavior, not implementation.
|
|
- Visual regression is part of the contract.
|
|
|
|
## 10. Documented Intent
|
|
A component is shipped with a "why" and a "when".
|
|
|
|
- What is it for?
|
|
- When should it be used?
|
|
- When should it NOT be used?
|
|
- What are the common mistakes with it? |