# 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?