Jon Chery
496303471d
---ci--- project: atelier phase: 7 milestone: v0.1 status: complete phase_role: final milestone_complete: true requirements: covered: [ATELIER-01, ATELIER-02, ATELIER-03, ATELIER-04, ATELIER-05, ATELIER-06, ATELIER-07, ATELIER-08, ATELIER-09, ATELIER-10, ATELIER-11, ATELIER-12, ATELIER-13, ATELIER-14, ATELIER-15, ATELIER-16, ATELIER-17, ATELIER-18, ATELIER-19, ATELIER-20, ATELIER-21, ATELIER-22, ATELIER-23, ATELIER-24, ATELIER-25, ATELIER-26, ATELIER-27, ATELIER-28, ATELIER-29, ATELIER-30, ATELIER-31, ATELIER-32, ATELIER-33, ATELIER-34, ATELIER-35] partial: [] ship: milestone: v0.1 type: NFR tag: v0.0.7 merge: milestone/v0.1-atelier -> main release: https://git.cloudinit.dev/cloudinit-bot/atelier/releases/tag/v0.0.7 ---/ci--- Milestone v0.1 — Initial Framework (NFR, complete). 8 core principles (C1-C8), 11 domains, 110 domain principles, 27 derived docs, 4 good + 3 bad examples, 4 language docs, full matrix, 3 review docs. All 35 requirements covered. 7 patches (v0.0.0 pre-execution through v0.0.7 final). v0.0.7 IS the v0.1.0 milestone release.
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? |