jig-ui 0.1.0 → 0.2.1

package/README.md

@@ -37,6 +37,17 @@ global one.
 Update later with `npx jig-ui@latest update` — files you have edited are left
 alone.
 
+Install writes the rules and the design tokens into `.jig/`. Import the tokens
+your surface needs — one brand file, one mode file:
+
+```css
+@import ".jig/tokens/brand.default.css";
+@import ".jig/tokens/mode.product.css";
+```
+
+Copy `brand.default.css` to `brand.<yourproject>.css` and edit that; `jig update`
+will not overwrite a file you have changed.
+
 Token setup is currently manual: copy `jig.config.example.json` to
 `jig.config.json` and import the token files described in
 `rules/02-tokens.md`. A scaffolding command for this is planned but not yet
@@ -46,14 +57,14 @@ implemented.
 
 | File | Contents | Load |
 | --- | --- | --- |
-| `rules/00-anti-patterns.md` | 48 universal rules with corrections | **Always** |
+| `rules/00-anti-patterns.md` | 87 universal rules with corrections | **Always** |
 | `rules/01-modes.md` | `editorial` / `product` / `operator` profiles | **Always** |
 | `rules/02-tokens.md` | Token contract, naming, consumption | On setup, or when adding a token |
 | `rules/03-patterns.md` | Component anatomy and behaviour | When building a covered pattern |
 | `rules/04-principles.md` | Five frames + seven tiebreakers | Novel decisions, or rule conflicts |
 | `rules/05-copy.md` | Interface text rules | Writing any user-facing string |
-| `tokens/brand.*.css` | Identity. One per project. | Imported by the app |
-| `tokens/mode.*.css` | Density, scale, rhythm, motion | One per surface |
+| `.jig/tokens/brand.*.css` | Identity. One per project. | Imported by the app |
+| `.jig/tokens/mode.*.css` | Density, scale, rhythm, motion | One per surface |
 
 `00` and `01` are the always-loaded core and are sized to stay cheap in context. `03` is the largest file and should be loaded per-pattern rather than wholesale.
 
@@ -64,7 +75,7 @@ Drop this in the project root so mode selection does not require asking on every
 ```jsonc
 // jig.config.json
 {
-  "brand": "tokens/brand.acme.css",
+  "brand": ".jig/tokens/brand.acme.css",
   "surfaces": [
     { "match": "/",         "mode": "editorial" },
     { "match": "/app/**",   "mode": "product"   },
@@ -78,8 +89,8 @@ Without this file, follow the selection procedure in `rules/01-modes.md`: infer,
 ## Consuming tokens
 
 ```css
-@import "tokens/brand.acme.css";   /* one per project */
-@import "tokens/mode.product.css"; /* one per surface  */
+@import ".jig/tokens/brand.acme.css";   /* one per project */
+@import ".jig/tokens/mode.product.css"; /* one per surface  */
 ```
 
 Then `var(--color-text-strong)`, `var(--spacing-card)`, `var(--text-body)` in any framework. For Tailwind v4, wrap both imports in `@theme` to generate utilities. See `rules/02-tokens.md`.
@@ -108,8 +119,12 @@ Re-run after any significant edit to `00` or `03`.
 
 Written from general UI and accessibility practice, plus the constraints specific to agent-generated output — which is where most of the structure comes from: the anti-patterns-first ordering, the mode split, the brand × mode token architecture, and the decidability test applied to every rule.
 
-**Not yet reconciled against *Practical UI*.** The numeric defaults throughout are placeholders chosen for internal consistency, not values derived from any source. Adham Dannaway's book (2nd ed. 2024) is the intended source for most of them. See `RECONCILE.md` for the open list; where the book states a position, overwrite the default here.
-
-principles.design informed the rules-versus-principles split, and the standard `rules/04-principles.md` is held to.
+**The numeric defaults are being reconciled.** Type scale, spacing steps, control sizes
+and motion durations started as internally consistent guesses and are being checked, row by
+row, against an external reference on interface design. `RECONCILE.md` tracks the status of
+each: adopted, deliberately kept different, or still open. The accessibility floors are
+outside that process — contrast ratios and target sizes come from WCAG 2.1 AA and are not
+adjustable.
 
-Nothing here reproduces either source. Read the book — it teaches the reasoning that this system only records the output of.
+principles.design informed the rules-versus-principles split, and the standard
+`rules/04-principles.md` is held to.

package/dist/index.js

@@ -250,11 +250,16 @@ function renderCommandTable(metadata) {
 }
 
 // src/install/vendor.ts
-function vendorHeader(file, version2) {
+var DELIMITERS = {
+  html: ["<!--", "-->"],
+  css: ["/*", "*/"]
+};
+function vendorHeader(file, version2, style = "html") {
+  const [open, close] = DELIMITERS[style];
   return [
-    `<!-- ${file} \u2014 vendored from Jig v${version2}.`,
+    `${open} ${file} \u2014 vendored from Jig v${version2}.`,
     "     Licensed Apache-2.0. See .jig/LICENSE and .jig/NOTICE.",
-    "     Edit freely: `jig update` will not overwrite a file you have changed. -->",
+    `     Edit freely: \`jig update\` will not overwrite a file you have changed. ${close}`,
     "",
     ""
   ].join("\n");
@@ -361,6 +366,15 @@ function install(opts) {
     const body = readFileSync2(join3(rulesDir, file), "utf8");
     planned.push({ key: relKey(".jig", file), content: vendorHeader(file, opts.version) + body, checkable: true });
   }
+  const tokensDir = join3(opts.packageRoot, "tokens");
+  for (const file of readdirSync(tokensDir).filter((f) => f.endsWith(".css")).sort()) {
+    const body = readFileSync2(join3(tokensDir, file), "utf8");
+    planned.push({
+      key: relKey(".jig", "tokens", file),
+      content: vendorHeader(file, opts.version, "css") + body,
+      checkable: true
+    });
+  }
   planned.push({
     key: relKey(".jig", "rules.index.json"),
     content: readFileSync2(join3(opts.packageRoot, "rules.index.json"), "utf8"),
@@ -452,6 +466,15 @@ function update(opts) {
     }
     write(key, vendorHeader(file, opts.version) + readFileSync3(join4(rulesDir, file), "utf8"));
   }
+  const tokensDir = join4(opts.packageRoot, "tokens");
+  for (const file of readdirSync2(tokensDir).filter((f) => f.endsWith(".css")).sort()) {
+    const key = relKey(".jig", "tokens", file);
+    if (isModified(installRoot, key, existing)) {
+      skipped.push(key);
+      continue;
+    }
+    write(key, vendorHeader(file, opts.version, "css") + readFileSync3(join4(tokensDir, file), "utf8"));
+  }
   const indexKey = relKey(".jig", "rules.index.json");
   if (isModified(installRoot, indexKey, existing)) {
     skipped.push(indexKey);

package/package.json

@@ -1,11 +1,11 @@
 {
   "name": "jig-ui",
-  "version": "0.1.0",
+  "version": "0.2.1",
   "description": "A design system for coding agents. 104 numbered UI rules, brand x mode design tokens, and an installer for Claude Code, Codex, Cursor and opencode.",
   "license": "Apache-2.0",
   "type": "module",
   "bin": {
-    "jig": "./dist/index.js"
+    "jig": "dist/index.js"
   },
   "files": [
     "dist",

package/rules/00-anti-patterns.md

@@ -67,12 +67,13 @@ Where several already apply — a table's rows are aligned, alike, and close —
 ✅ Let the content pick the layout. Three items of unequal weight are a list, not a grid.
 
 ### A-07 Oversized radius everywhere
-❌ A single large radius (16px+) applied to cards, buttons, inputs and badges alike
-✅ `--radius-control` for controls, `--radius-surface` for containers. Both derive from `--radius-sm`, which is a brand decision. Small elements take small radii.
+❌ One radius applied to cards, buttons, inputs and badges alike, regardless of element size
+✅ `--radius-control` for controls, `--radius-surface` for containers. `--radius-control` selects `sm` in every mode; `--radius-surface` selects `md` in `editorial` and `product`, `sm` in `operator` — the selection is per-mode, not a fixed derivation. Small elements take small radii.
+In `operator`, `--radius-surface` also selects `sm`, so cards, buttons and inputs converge on one 8px radius. That is not this rule recurring: it is a per-mode selection made deliberately for density. The distinction is whether the value was chosen or defaulted to.
 
 ### A-08 Shadow as the only depth cue
 ❌ A drop shadow on every card, or several shadow sizes with no rule governing which means what
-✅ `--shadow-surface` is `none` in all three modes. Depth comes from `--color-stroke-weak` or a surface-colour step. `--shadow-raised` exists for overlays only — dialogs, popovers, dropdowns.
+✅ `--shadow-surface` is `none` in all three modes. Depth comes from `--color-stroke-weak` or a surface-colour step. `--shadow-raised` exists for exactly two cases: overlays — dialogs, popovers, dropdowns — and sticky navigation in `editorial`, which must read as above the content scrolling beneath it.
 
 ### A-09 Marketing voice in an application
 ❌ "Supercharge your workflow" on an internal dashboard
@@ -191,7 +192,7 @@ Two legitimate departures, and they are not the same:
 ### C-68 Non-interactive elements styled like interactive ones
 ❌ A "Verified" badge with the brand fill and the shape of the primary button; decorative icons carrying the same border and colour as a secondary button
 ✅ Things that look alike are expected to behave alike. If an element does nothing when clicked, it must not carry the visual signature of something that does — brand fill, button shape, or control border.
-Differentiate deliberately: change the shape (a badge is more rounded than a button), the tone (`success` for a verified state rather than `brand`), and the emphasis (a `fill` background rather than a solid one, so the real primary action stays the most prominent thing on screen).
+Differentiate deliberately: change the shape (a badge, pill, chip or avatar takes `--radius-full`, more rounded than a button's `--radius-control`), the tone (`success` for a verified state rather than `brand`), and the emphasis (a `fill` background rather than a solid one, so the real primary action stays the most prominent thing on screen).
 The converse also holds: two elements that do the same job should look the same.
 
 ---

package/rules/01-modes.md

@@ -62,23 +62,25 @@ At a seam between modes:
 **Reader:** first-time, on mobile data, scanning before committing attention.
 **Tiebreaker:** legibility over density. When in doubt, larger and further apart.
 
-| Property | Value |
+| Property | This mode selects |
 | --- | --- |
-| Body size | 18px (16px minimum on dense secondary text) |
-| Type ratio | 1.250 (major third) |
-| Heading ramp | 24 / 32 / 48 / 64 |
-| Measure | 68ch |
-| Base unit | 4px |
-| Section rhythm | 96px desktop · 56px mobile |
-| Card padding | 32px |
-| Control height | 48px |
-| Radius | brand default (typically 8px) |
-| Elevation | none, except sticky navigation |
-| Motion | 200–300ms; entrance animation permitted **once**, in the first viewport only |
-| Colour usage | Neutral-dominant. Accent for links and primary CTA only. |
+| UI text | `--text-body` |
+| Long-form text | `--text-prose` · `--leading-prose` |
+| Heading ramp | `--text-h3` → `--text-h2` → `--text-h1` |
+| Type ratio | 1.250 Major Third — the largest of the three |
+| Measure | `--measure-prose` |
+| Section rhythm | `--spacing-section` |
+| Card padding | `--spacing-card` |
+| Control height | `--size-control` — the tallest of the three |
+| Radius | `--radius-control` (sm) · `--radius-surface` (md) |
+| Elevation | `--shadow-none`; `--shadow-raised` for sticky nav only |
+| Motion | `--duration-base`; entrance animation **once**, first viewport only |
+| Colour usage | Neutral-dominant. `--color-brand` for links and primary CTA only. |
 | Imagery | Central. Real photography or commissioned illustration. |
 | Keyboard | Standard tab order; no shortcuts expected |
 
+Resolved values: `02-tokens.md`.
+
 **Mode-specific rules**
 - One hero maximum, at the top. A second full-viewport section is a second hero.
 - Every page states its subject above the fold in text, not only in an image.
@@ -94,24 +96,26 @@ At a seam between modes:
 **Reader:** returning, task-focused, moderate familiarity, mixed device.
 **Tiebreaker:** predictability over novelty. A boring pattern the user already knows beats a better one they must learn.
 
-| Property | Value |
+| Property | This mode selects |
 | --- | --- |
-| Body size | 16px |
-| Type ratio | 1.200 (minor third) |
-| Heading ramp | 20 / 24 / 32 |
-| Measure | 60ch |
-| Base unit | 4px |
-| Section rhythm | 48px desktop · 32px mobile |
-| Card padding | 24px |
-| Control height | 40px |
-| Table row height | 48px |
-| Radius | brand default, one step tighter than `editorial` |
-| Elevation | overlays only (modal, popover, dropdown) |
-| Motion | 150ms; state change only, no entrance animation |
-| Colour usage | Accent for primary action. Full semantic set. Status as subtle fill plus text. |
+| UI text | `--text-body` |
+| Long-form text | `--text-prose` · `--leading-prose` |
+| Heading ramp | `--text-h3` → `--text-h2` → `--text-h1` |
+| Type ratio | 1.200 Minor Third — the mid value of the three |
+| Measure | `--measure-prose` |
+| Section rhythm | `--spacing-section` |
+| Card padding | `--spacing-card` |
+| Control height | `--size-control` — the mid value of the three |
+| Table row height | `--size-row` |
+| Radius | `--radius-control` (sm) · `--radius-surface` (md) |
+| Elevation | `--shadow-none`; `--shadow-raised`/`--shadow-overlay` for overlays only (modal, popover, dropdown) |
+| Motion | `--duration-base`; state change only, no entrance animation |
+| Colour usage | `--color-brand` for primary action. Full semantic set. Status as subtle fill plus text. |
 | Imagery | Sparse. Illustration permitted in empty states only. |
 | Keyboard | Shortcuts for frequent actions; documented in-app |
 
+Resolved values: `02-tokens.md`.
+
 **Mode-specific rules**
 - One primary action per view. Everything else is secondary or tertiary.
 - Destructive actions are never adjacent to their most common neighbour, and always confirm.
@@ -127,25 +131,27 @@ At a seam between modes:
 **Reader:** expert, in the tool for hours, keyboard-driven, high repetition.
 **Tiebreaker:** speed of repeated use over clarity of first use. Discoverability is worth sacrificing for throughput here, and nowhere else.
 
-| Property | Value |
+| Property | This mode selects |
 | --- | --- |
-| Body size | 14px |
-| Type ratio | 1.150 |
-| Heading ramp | 16 / 18 / 22 |
-| Measure | 72ch (prose only; data columns are not prose) |
-| Base unit | 4px |
-| Section rhythm | 24px |
-| Card padding | 12px |
-| Control height | 32px (28px in compact rows) |
-| Table row height | 36px |
-| Radius | 4px maximum |
-| Elevation | overlays only, minimal |
-| Motion | 100ms; **no entrance animation of any kind** |
+| UI text | `--text-body` |
+| Long-form text | `--text-prose` · `--leading-prose` |
+| Heading ramp | `--text-h3` → `--text-h2` → `--text-h1` |
+| Type ratio | 1.125 Major Second — the smallest of the three |
+| Measure | `--measure-prose` (prose only; data columns are not prose) |
+| Section rhythm | `--spacing-section` |
+| Card padding | `--spacing-card` |
+| Control height | `--size-control` — the shortest of the three (`--size-control-sm` in compact rows) |
+| Table row height | `--size-row` (`--size-row-compact` in compact rows) |
+| Radius | `--radius-control` (sm) · `--radius-surface` (sm) — both sm in this mode |
+| Elevation | `--shadow-none`; overlays only, minimal |
+| Motion | `--duration-base`; **no entrance animation of any kind** |
 | Colour usage | Neutral-dominant. Colour is *exclusively* semantic. No decorative accent. |
 | Imagery | None. Icons only. |
 | Keyboard | Full keyboard operation mandatory. Shortcut reference required. |
 | Numerals | Tabular figures mandatory on all numeric columns |
 
+Resolved values: `02-tokens.md`.
+
 **Mode-specific rules**
 - Density is the feature. More rows visible beats more comfortable rows.
 - Every table supports: sort, filter, column visibility, and a stable row identity across refreshes.
@@ -163,11 +169,12 @@ Useful when a decision straddles two modes.
 
 | | `editorial` | `product` | `operator` |
 | --- | --- | --- | --- |
-| Body | 18px | 16px | 14px |
-| Control height | 48px | 40px | 32px |
-| Section rhythm | 96px | 48px | 24px |
-| Card padding | 32px | 24px | 12px |
-| Motion | 200–300ms | 150ms | 100ms |
+| Type ratio | 1.250 | 1.200 | 1.125 |
+| Body | `--text-body` | same as editorial | smaller |
+| Control height | tallest | mid | shortest |
+| Section rhythm | `--spacing-xxl` | `--spacing-xl` | `--spacing-m` |
+| Card padding | `--spacing-m` | `--spacing-m` | `--spacing-s` |
+| Motion | slowest | mid | fastest |
 | Entrance animation | once, first viewport | none | none |
 | Decorative colour | accent only | primary action | none |
 | Imagery | central | empty states | none |
@@ -182,7 +189,7 @@ Attempting to vary these by mode is a category error:
 - **Accessibility floors.** Contrast, focus indication, target size, semantic markup. Identical in all three. `operator` being dense does not license a 24px tap target or a 3:1 body contrast.
 - **Brand identity.** Palette, typeface, logo, voice.
 - **State completeness.** Every mode renders loading, empty, error and disabled.
-- **The anti-pattern file.** All 48 rules apply everywhere.
+- **The anti-pattern file.** All 87 rules in it apply everywhere.
 
 ---
 
@@ -192,17 +199,17 @@ Per project, one file supplying:
 
 - **Palette** — neutral ramp (12 steps, warm/cool/true declared), one accent ramp, semantic set (danger, warning, success, info) tuned to the accent's temperature.
 - **Typeface** — display and text families, and whether they differ. Numeric font-feature settings.
-- **Radius personality** — the base radius that mode scales from. This carries more brand character than colour does.
+- **Radius personality** — the brand-scale radius options (`sm`, `md`, `lg`, `full`) that each mode selects from, not a fixed derivation. This carries more brand character than colour does.
 - **Elevation personality** — border-led or shadow-led. Pick one; do not mix within a project.
 - **Voice** — sentence case or title case, contraction policy, error-message tone.
 
-Default when no brand is supplied: warm neutral ramp anchored on `#fafaf7`, no accent, 6px base radius, border-led elevation. Greyscale output plus a stated question beats an invented purple (`A-01`).
+Default when no brand is supplied: warm neutral ramp anchored on `#fafaf7`, no accent, 8px base radius (`--radius-sm`), border-led elevation. Greyscale output plus a stated question beats an invented purple (`A-01`).
 
 ---
 
 ## Notes for the author (not for the agent)
 
-**Decided, not derived.** These numbers are internally consistent and defensible, but several are judgement calls that should be tuned once you have run real work through them: the 18px editorial body, the 36px operator row, the three section-rhythm values, and the motion durations. Change them in this file, never at the call site.
+**Decided, not derived.** These numbers are internally consistent and defensible, but several are judgement calls that should be tuned once you have run real work through them: the operator row height, the three section-rhythm values, and the motion durations. Change them in this file, never at the call site.
 
 **Where your taste is recorded here:**
 - The zero-JS default in `editorial` — a stronger position than most systems take, and consistent with your writing on JS-dependent forms.

package/rules/02-tokens.md

@@ -19,9 +19,13 @@ tokens/
 
 A surface loads **exactly one brand file and exactly one mode file**.
 
+**Tokens live at `.jig/tokens/`.** That is the only location, in every scope and
+every project — `jig install` puts them there, `jig update` refreshes them there,
+and nothing relocates them. Import from that path and it stays correct.
+
 ```css
-@import "tokens/brand.acme.css";
-@import "tokens/mode.operator.css";
+@import ".jig/tokens/brand.acme.css";
+@import ".jig/tokens/mode.operator.css";
 ```
 
 Three separate mode files rather than one file with variants. The trade: a surface cannot switch modes at runtime, and shared values are duplicated across three files. In exchange each surface ships only the tokens it uses, the files are independently readable, and there is no cascade to reason about. For a system where mode is a routing decision rather than a user preference, that is the right trade.
@@ -50,7 +54,7 @@ Limited options, chosen once. The point is not the specific values — it is tha
 | --- | --- | --- | --- | --- | --- |
 | 8 | 16 | 24 | 32 | 48 | 80 |
 
-Modes **select** from these; they never define their own values. `--spacing-card` is `L` in `editorial`, `M` in `product`, `S` in `operator` — same option set, different selection. This is why there are no arbitrary numbers left in the mode files.
+Modes **select** from these; they never define their own values. `--spacing-card` is `M` in `editorial`, `M` in `product`, `S` in `operator` — same option set, different selection. This is why there are no arbitrary numbers left in the mode files.
 
 **Type — the scale ratio varies by mode**, because scale size should track interface complexity. A large ratio gives dramatic steps that suit content-led pages; a small ratio gives fine gradations that suit dense tools needing many levels in little space.
 
@@ -60,6 +64,8 @@ Modes **select** from these; they never define their own values. `--spacing-card
 | `product` | 1.200 Minor Third | | 14 | 16 | 18 | 20 | 24 | 32 |
 | `operator` | 1.125 Major Second | | 12 | 14 | 16 | 16 | 18 | 22 |
 
+`editorial` omits the rung the ratio would put between H2 and H1 (a step near 40); the ratio names the ladder, not every adjacent step — its H2→H1 jump (32→48) is 1.5, not 1.25.
+
 **`--text-body` and `--text-prose` are different roles, not two sizes of the same thing.** Body is UI text — labels, controls, table cells, short strings read in glances. Prose is sustained reading, and never drops below 18px on a page anyone is expected to actually read (`B-75`).
 
 Line heights are unitless and floor at **1.5** for body and prose, easing down as size rises. Raise it further when lines are long, when the typeface is heavy or dark, or when it simply looks large for its nominal size. Between 1.5 and 2 is the comfortable band for prose.
@@ -72,7 +78,9 @@ Line heights are unitless and floor at **1.5** for body and prose, easing down a
 
 **Typeface.** One sans serif by default: most legible small, neutral across brands, least likely to be the wrong choice. When picking one — prefer a popular face with many weights, a tall x-height and generous default spacing, with OpenType features and the language coverage the product needs. When in doubt, the platform system font is tried, tested and free to load. A second face is permitted for headings only (`B-76`).
 
-**Radius — three options**, by element size: 8px small (buttons, inputs, badges), 16px medium (cards, panels), 32px large (hero surfaces).
+**Radius — four options**, by element size: 8px small (buttons, inputs), 16px medium (cards, panels), 32px large (hero media and full-bleed surfaces), and a full/pill radius for pills, badges, avatars and chips (`--radius-full`).
+
+`--radius-control` selects `sm` in all three modes. `--radius-surface` selects `md` in `editorial` and `product`, but `sm` in `operator` — the selection is per-mode, not a fixed derivation. `--radius-lg` and `--radius-full` are brand-scale options; no mode currently selects either.
 
 **Shadow — two options** with stated meanings: `raised` sits above the page, `overlay` floats over it. `A-08` still prefers a stroke; these exist for when depth is the point.
 
@@ -186,8 +194,8 @@ In dark, elevated surfaces get **lighter**, not shadowed. Border-led elevation s
 
 **Plain CSS, any framework**
 ```css
-@import "tokens/brand.default.css";
-@import "tokens/mode.product.css";
+@import ".jig/tokens/brand.default.css";
+@import ".jig/tokens/mode.product.css";
 
 .card {
   background: var(--color-surface);
@@ -201,8 +209,8 @@ In dark, elevated surfaces get **lighter**, not shadowed. Border-led elevation s
 ```css
 @import "tailwindcss";
 @theme {
-  @import "tokens/brand.default.css";
-  @import "tokens/mode.product.css";
+  @import ".jig/tokens/brand.default.css";
+  @import ".jig/tokens/mode.product.css";
 }
 ```
 Yields `bg-surface`, `rounded-surface`, `p-card`, `text-body` as utilities.

package/rules/03-patterns.md

@@ -38,7 +38,7 @@ Read this before building any pattern that reports something to the user. The mo
 
 | Weight | Treatment | Use |
 | --- | --- | --- |
-| **Primary** | Solid `--color-brand` fill, `--color-brand-on` text, `--radius-control` | The one action the view exists for |
+| **Primary** | Solid `--color-brand` fill, `--color-on-brand` text, `--radius-control` | The one action the view exists for |
 | **Secondary** | Transparent fill, `--color-brand` border **and** text, same radius and height | The alternative, or several actions of equal weight |
 | **Tertiary** | Transparent, no border, `--color-brand` **underlined** text | Least important actions, repeated actions, destructive actions |
 
@@ -53,7 +53,7 @@ Four numbers, and most button designs in the wild fail at least one:
 | Button **shape** — fill or border — against its background | **3:1** |
 | Button **text** against the button | **4.5:1** |
 | Two buttons sharing a style, distinguished only by contrast | **3:1 between them** |
-| Hit area | **48×48px** |
+| Hit area | `--size-touch-target` — **48×48px** floor |
 
 A secondary button's fill or border is **not decorative**. It is the only thing identifying the element as a button, so it carries the 3:1 non-text requirement (`02-tokens.md`). Strip it and you have coloured text.
 

package/rules/04-principles.md

@@ -5,7 +5,7 @@
 
 Two kinds of principle, doing opposite work.
 
-**Part 1 — Frames (five).** Generative. Use these to find the rule that does not exist yet. `00`–`03` cover known failures; these are the method for recognising a new one. Adapted from the foundations in *Practical UI* (Adham Dannaway).
+**Part 1 — Frames (five).** Generative. Use these to find the rule that does not exist yet. `00`–`03` cover known failures; these are the method for recognising a new one.
 
 **Part 2 — Tiebreakers.** Adjudicative. Use only when two existing rules point in different directions.
 

package/tokens/brand.default.css

@@ -21,7 +21,10 @@
   --brand-h: 264;
   --brand-s: 0%;
   --brand-l: 15%;
-  --brand-base: hsl(var(--brand-h) var(--brand-s) var(--brand-l));
+
+  /* The solid brand colour. Interactive elements reference this (I-56).
+     The variations below are alpha steps off the same hue. */
+  --color-brand: hsl(var(--brand-h) var(--brand-s) var(--brand-l));
 
   /* ================= ELEVATION BACKGROUNDS (solid) =================
      Light comes from above: higher elevation is lighter.
@@ -50,32 +53,42 @@
 
   /* ================= SYSTEM COLOURS =================
      Three, with familiar traffic-light meanings. Four variations each.
-     Never the only signal — pair with an icon and text (C-20). */
-  --error-base:   hsl(0   71% 44%);
-  --warning-base: hsl(42  82% 36%);
-  --success-base: hsl(162 95% 26%);
-  /* info is NOT in the book's set of three. Kept as an optional fourth. */
-  --info-base:    hsl(220 70% 42%);
-
-  --color-text-error:          hsl(0 71% 44% / 100%);
-  --color-stroke-error-strong: hsl(0 71% 44% / 80%);
-  --color-stroke-error-weak:   hsl(0 71% 44% / 20%);
-  --color-fill-error:          hsl(0 71% 44% / 5%);
-
-  --color-text-warning:          hsl(42 82% 36% / 100%);
-  --color-stroke-warning-strong: hsl(42 82% 36% / 80%);
-  --color-stroke-warning-weak:   hsl(42 82% 36% / 20%);
-  --color-fill-warning:          hsl(42 82% 36% / 5%);
-
-  --color-text-success:          hsl(162 95% 26% / 100%);
-  --color-stroke-success-strong: hsl(162 95% 26% / 80%);
-  --color-stroke-success-weak:   hsl(162 95% 26% / 20%);
-  --color-fill-success:          hsl(162 95% 26% / 5%);
-
-  --color-text-info:          hsl(220 70% 42% / 100%);
-  --color-stroke-info-strong: hsl(220 70% 42% / 80%);
-  --color-stroke-info-weak:   hsl(220 70% 42% / 20%);
-  --color-fill-info:          hsl(220 70% 42% / 5%);
+     Never the only signal — pair with an icon and text (C-20).
+
+     Requirements when you replace one:
+       - text (100%)          >= 4.5:1 against --color-bg-base AND --color-bg-raised
+       - stroke-strong (80%)  >= 3:1 against the same two, composited
+       - stroke-weak and fill are decorative and have no floor
+     These are not style preferences. A system colour that fails them is
+     unreadable to the people the colour exists to warn.
+     Each colour is one h/s/l triple (plus a fill alpha, which differs between
+     light and dark) referenced by all four variations below, so changing the
+     colour means changing it in one place instead of 4–5. */
+  --error-h:   0;   --error-s:   71%; --error-l:   44%; --error-fill-a:   5%;
+  --warning-h: 42;  --warning-s: 82%; --warning-l:  29%; --warning-fill-a: 5%;
+  --success-h: 162; --success-s: 95%; --success-l: 23%; --success-fill-a: 5%;
+  /* info is NOT in the reference's set of three. Kept as an optional fourth. */
+  --info-h:    220; --info-s:    70%; --info-l:    42%; --info-fill-a:    5%;
+
+  --color-text-error:          hsl(var(--error-h) var(--error-s) var(--error-l) / 100%);
+  --color-stroke-error-strong: hsl(var(--error-h) var(--error-s) var(--error-l) / 80%);
+  --color-stroke-error-weak:   hsl(var(--error-h) var(--error-s) var(--error-l) / 20%);
+  --color-fill-error:          hsl(var(--error-h) var(--error-s) var(--error-l) / var(--error-fill-a));
+
+  --color-text-warning:          hsl(var(--warning-h) var(--warning-s) var(--warning-l) / 100%);
+  --color-stroke-warning-strong: hsl(var(--warning-h) var(--warning-s) var(--warning-l) / 80%);
+  --color-stroke-warning-weak:   hsl(var(--warning-h) var(--warning-s) var(--warning-l) / 20%);
+  --color-fill-warning:          hsl(var(--warning-h) var(--warning-s) var(--warning-l) / var(--warning-fill-a));
+
+  --color-text-success:          hsl(var(--success-h) var(--success-s) var(--success-l) / 100%);
+  --color-stroke-success-strong: hsl(var(--success-h) var(--success-s) var(--success-l) / 80%);
+  --color-stroke-success-weak:   hsl(var(--success-h) var(--success-s) var(--success-l) / 20%);
+  --color-fill-success:          hsl(var(--success-h) var(--success-s) var(--success-l) / var(--success-fill-a));
+
+  --color-text-info:          hsl(var(--info-h) var(--info-s) var(--info-l) / 100%);
+  --color-stroke-info-strong: hsl(var(--info-h) var(--info-s) var(--info-l) / 80%);
+  --color-stroke-info-weak:   hsl(var(--info-h) var(--info-s) var(--info-l) / 20%);
+  --color-fill-info:          hsl(var(--info-h) var(--info-s) var(--info-l) / var(--info-fill-a));
 
   /* ================= STATE LAYERS =================
      Transparent overlays, so hover and press need no new colours and work on
@@ -92,8 +105,8 @@
   --font-mono:    ui-monospace, "SF Mono", "Cascadia Code", monospace;
   --font-numeric-features: "tnum" 1, "lnum" 1;
 
-  /* ================= RADIUS — three, by element size ================= */
-  --radius-sm:   8px;    /* buttons, inputs, badges, checkboxes */
+  /* ================= RADIUS — four, by element size ================= */
+  --radius-sm:   8px;    /* buttons, inputs, checkboxes */
   --radius-md:   16px;   /* cards, panels                       */
   --radius-lg:   32px;   /* large surfaces, hero media          */
   --radius-full: 9999px;
@@ -125,26 +138,13 @@
     --brand-l: 88%;      /* lighten and desaturate the brand for dark surfaces */
     --color-on-brand: hsl(var(--brand-h) 6% 10%);
 
-    /* System colours lighten and desaturate in dark mode. */
-    --color-text-error:          hsl(0 60% 72% / 100%);
-    --color-stroke-error-strong: hsl(0 60% 72% / 80%);
-    --color-stroke-error-weak:   hsl(0 60% 72% / 20%);
-    --color-fill-error:          hsl(0 60% 72% / 8%);
-
-    --color-text-warning:          hsl(42 70% 70% / 100%);
-    --color-stroke-warning-strong: hsl(42 70% 70% / 80%);
-    --color-stroke-warning-weak:   hsl(42 70% 70% / 20%);
-    --color-fill-warning:          hsl(42 70% 70% / 8%);
-
-    --color-text-success:          hsl(162 45% 66% / 100%);
-    --color-stroke-success-strong: hsl(162 45% 66% / 80%);
-    --color-stroke-success-weak:   hsl(162 45% 66% / 20%);
-    --color-fill-success:          hsl(162 45% 66% / 8%);
-
-    --color-text-info:          hsl(220 55% 74% / 100%);
-    --color-stroke-info-strong: hsl(220 55% 74% / 80%);
-    --color-stroke-info-weak:   hsl(220 55% 74% / 20%);
-    --color-fill-info:          hsl(220 55% 74% / 8%);
+    /* System colours lighten and desaturate in dark mode. Only the h/s/l and
+       fill-alpha vars need overriding here — the four hsl() declarations
+       above pick the new values up automatically. */
+    --error-h:   0;   --error-s:   60%; --error-l:   72%; --error-fill-a:   8%;
+    --warning-h: 42;  --warning-s: 70%; --warning-l:  70%; --warning-fill-a: 8%;
+    --success-h: 162; --success-s: 45%; --success-l: 66%; --success-fill-a: 8%;
+    --info-h:    220; --info-s:    55%; --info-l:    74%; --info-fill-a:    8%;
 
     --shadow-raised:  none;
     --shadow-overlay: 0 8px 24px -8px rgb(0 0 0 / 60%);