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

2.1 KiB

Raw Blame History

Design Tokens — Derived Rules

Derives from domains/uiux/first-principles.md P7 (Hierarchy), P8 (Consistency), P9 (Simplicity).

What is a Token

A design token is the smallest unit of a design system: a color, a spacing, a font size, a radius. It has a name and a value. The name is the API; the value is the implementation.

The Token Hierarchy

Global tokens (e.g., --color-blue-500)
  → Alias tokens (e.g., --color-button-primary)
    → Component tokens (e.g., --button-primary-bg)

Global tokens are the raw palette. They have no semantic meaning.
Alias tokens have meaning: "this is the button background." They reference global tokens.
Component tokens are scoped to a component. They reference alias tokens.
Components reference component or alias tokens, never global tokens directly.

No Raw Values (P8 Consistency)

A component never hardcodes #3b82f6 or 16px. It references --color-button-primary or --space-4.
A hardcoded value is a token that should exist but does not. It is design debt.
The token is the API to the design system. Bypassing it bypasses the system.

Naming (P3 Clarity)

Tokens are semantic, not visual: --color-text-primary, not --color-dark-gray.
Visual names couple to the implementation. Semantic names survive a redesign.
--color-button-primary-bg is clear. --color-blue is not (which button? what state?).

Theming via Tokens (P5 Forgiveness, core C5 Reversibility)

Themes are sets of token values. Switch theme = switch token values, not switch CSS.
Dark mode: --color-text-primary: #fff instead of #000. The component code does not change.
A component that hardcodes colors cannot be themed. A component that uses tokens can.

What Violates Token Discipline

Violation	Principle
`color: #3b82f6` in a component	P8 Consistency
`--color-blue-500` referenced by a component directly	P9 (skip alias)
`--color-dark-gray` (visual name)	P3 Clarity
A component that cannot be themed	P5, core C5
No global tokens, every component invents its own palette	P8

2.1 KiB Raw Blame History