atelier/domains/uiux/components.md

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?