Files

T

Jon Chery 496303471d docs(milestone): complete v0.1 — initial framework

---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.

2026-08-05 00:36:55 +00:00

3.0 KiB

Raw Blame History

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?

3.0 KiB Raw Blame History