@brignano/design 0.1.0

package/DECISIONS.md

@@ -0,0 +1,217 @@
+# Design decisions
+
+Why the values in `tokens.css` are what they are. Each entry supersedes whatever
+came before it; nothing here is re-litigated without a new entry.
+
+---
+
+## ADR-0001 — The interactive hue is cobalt
+
+**Status:** accepted · 2026-08-23
+**Supersedes:** `brignano.io/docs/tsd-site-modernization.md` §10.3
+
+### Context
+
+`brignano.io` shipped electric indigo/violet (`#6d28d9` / `#a78bfa`). `life`
+shipped a warm functional ramp. Neither was chosen as an interactive colour —
+§10.3 records violet as resolving a *negative* constraint:
+
+> **Accent color:** ✅ **Shift the hue** away from emerald. Candidate: an
+> **electric indigo/violet** … **amber as fallback**.
+
+That decision answered "not green." A long argument followed about whether amber
+or violet should replace it, which was the wrong argument — see ADR-0004. Once
+identity, affordance and state were separated, the only question left was what
+colour a *control* should be.
+
+### Decision
+
+Cobalt (`#2563eb` / `#60a5fa`), with a full hover / pressed / focus / disabled ramp.
+
+### Rationale
+
+Cobalt, indigo and violet were all measured against both grounds. **All three
+cleared every gate**, so contrast did not decide it:
+
+| Candidate | Text (light) | Fill (light) | Text (dark) | Pressed (dark) |
+|---|---|---|---|---|
+| cobalt | 6.70 | 5.17 | 7.64 | 10.77 |
+| indigo | 7.90 | 6.29 | 6.51 | 9.74 |
+| violet | 7.10 | 5.70 | 7.13 | 10.52 |
+
+It was decided on the two things contrast can't measure:
+
+1. **Semantically inert.** Amber means caution, green means success, red means
+   error — all of them arrive with meaning already attached. Blue arrives with
+   none, which is exactly why product UIs converged on it. That is a functional
+   property, not a fashion.
+2. **Complementary to the mark hue.** Cobalt sits opposite larch on the wheel, so
+   identity and affordance never compete for the same attention.
+
+Cobalt over indigo/violet specifically: it has the most dark-mode headroom of the
+three, and blue is the most conventional link colour in existence — the lowest
+cognitive cost and the highest affordance. **Distinctiveness belongs in the brand
+layer; conventionality belongs in the control layer.** That is how you get both.
+
+### Consequences
+
+- `brignano.io` migration surface: 4 literal hexes in `app/globals.css` plus ~15
+  `violet-*` utilities. Map **by job**, not find-and-replace: `.text-primary-color`
+  → `--i-ink`, filled buttons → `--i`, focus rings → `--i-ink`.
+- The trail's summit zone (`tsd-signature-experience.md` §5.2, "summit
+  indigo/violet") is re-inked with `--mark`.
+- `life` is unaffected — it has no interactive colour today.
+
+---
+
+## ADR-0002 — Charts keep a full categorical palette, re-derived and validated
+
+**Status:** accepted · 2026-08-23
+
+### Context
+
+An earlier draft suggested the `/coding` chart palette was "undercutting the
+identity" and should derive from the brand accent. **That was wrong**, and it is
+worth recording why.
+
+Series colour answers *"which of these eight things am I looking at?"*, which needs
+eight hues a human can separate at a glance. Deriving eight series colours from one
+hue produces eight of that hue nobody can tell apart. **Charts genuinely need the
+range.** The constraint is *separability*, not restraint.
+
+### The actual problem
+
+`components/stats/chart-colors.ts` is not too colourful — it is insufficiently
+separable. Validated (light, 10 slots):
+
+```
+[FAIL] Lightness band      outside band: #ef9aa3, #34d399
+[WARN] CVD separation      worst adjacent #a78bfa <-> #06b6d4  dE 6.6 (deutan)
+[FAIL] Normal-vision floor worst adjacent #ef9aa3 <-> #f97316  dE 13.7
+[WARN] Contrast vs surface 8 of 10 below 3:1
+```
+
+ΔE 13.7 means those two are hard to separate **with full colour vision**, before
+colourblindness is considered.
+
+### Decision
+
+Keep a full 8-hue categorical palette, capped at 8 + "Other". Replace the values
+with a set that passes every hard gate in both modes (adjacent CVD ΔE 9.1 light /
+8.4 dark; normal-vision ΔE 19.6 / 19.3). Values in `tokens.chart.css`.
+
+### Consequences
+
+- **Slot order is load-bearing** — the gates measure *adjacent* pairs, so
+  re-ordering silently breaks colourblind safety. Fixed order, never cycled.
+- Three light-mode slots sit below 3:1; that is legal only with relief (visible
+  labels or a table view). The donut's centre readout and legend already satisfy it.
+- `stats-pie.tsx` already takes the top 8 and aggregates the rest — now the
+  documented rule rather than an implementation detail.
+- Colour must follow the **entity**, not its rank. The current code indexes by
+  sorted position, so a data shift repaints every series. Map name → slot once.
+- `chart-colors.ts` should read the CSS custom properties rather than literal hex,
+  or the two will drift the way everything else did.
+
+---
+
+## ADR-0003 — The system lives in one public repo, consumed as a package
+
+**Status:** accepted · 2026-08-23
+
+### Decision
+
+A standalone repo — `brignano/design` — installed as `@brignano/design`.
+
+### Rationale
+
+**It cannot live in `life`.** `life` is private and holds confirmation codes and
+booking details. `brignano.io` is public. A public site cannot install tokens from
+a private repo without handing out credentials to the repo storing your boarding
+passes. Hard blocker, not preference.
+
+**It should not live in `brignano.io`.** That makes the site the owner and every
+tool a downstream guest, pinning tools to the site's release cycle.
+
+**Copy-paste is what already failed** — two repos, two stylesheets, two accents,
+two chart palettes, and a documented decision only one of them followed.
+
+### Distribution
+
+Three channels, because there are three kinds of consumer:
+
+| Consumer | Channel |
+|---|---|
+| npm projects with a build (`brignano.io`, `life`) | git dependency pinned to a tag |
+| no-build surfaces (`homelab`, a static page) | jsDelivr against the public repo |
+| **projects that don't exist yet** | a Claude skill generated from this repo |
+
+The third is the one that matters for "as I create new things" — a skill follows
+the account, so a new project gets the system without anyone wiring it up.
+
+npm publishing is deferred until `brignano.io` actually consumes it, so the first
+published version isn't one that's immediately superseded. The scope `@brignano` is
+already owned (it is the npm username), so no org setup is needed.
+
+### Consequences
+
+- The repo must be **public**: private npm needs a paid plan, jsDelivr only serves
+  public repos, and a public `brignano.io` that can't `npm install` is broken.
+- Nothing here is secret — hex values and spacing rules aren't a moat — and the
+  documented reasoning is itself a portfolio asset.
+- Consumers pin the **same tag** and bump together. If one tracks `main` and another
+  a tag, the drift this repo exists to prevent comes straight back.
+- A token rename is a breaking change.
+
+---
+
+## ADR-0004 — One hue, one meaning
+
+**Status:** accepted · 2026-08-23
+**Supersedes:** the "single accent" model in the first draft of this system
+
+### Context
+
+The first draft had one accent carrying identity, affordance *and* warning. That is
+what produced a long amber-versus-violet argument, and the argument was unwinnable
+because the question was wrong: no hue can be all three without one meaning bleeding
+into the others.
+
+Worse, the founding rule of this system — *colour carries meaning, never
+decoration* — was being violated by the system itself. A hue with two meanings is
+exactly the thing the rule forbids, just relocated.
+
+### Decision
+
+Every hue answers exactly one question, on every surface, in both tiers. Two
+specific consequences:
+
+**1. Attention is one meaning.** A warning toast, the `NEXT UP` strip, and a
+deposit closing in six days are the same message at different volumes, so they are
+the same colour. There is no separate "warning" hue and no separate "now/next" hue.
+This is what lets a marketing site and an operational tool share one palette
+honestly rather than by coincidence.
+
+**2. Identity is not a fill.** `--mark` inks a graphic — the trail, the monogram, a
+hero rule — and nothing else.
+
+The intermediate proposal was to keep a `--brand-*` family and manage the overlap
+with amber's warning meaning by convention: brand only at large decorative scale,
+warning always with an icon. That works, and warm-brand companies do it. It was
+rejected because it is enforced by remembering, every time, forever — and rules
+enforced by remembering get forgotten by a version of you in a hurry. Naming is
+cheaper and more reliable enforcement: `--brand` invites someone to tint a button
+with it; `--mark` does not.
+
+### Consequences
+
+- `brignano.io` gives up a brand fill for tinting eyebrows and section rules. Those
+  go to ink and neutrals — arguably better, since tinted eyebrow rules are the
+  portfolio-template tell the modernization TSD set out to escape.
+- Identity now rests on the trail, the monogram, the type, and restraint. If that
+  feels thin in place, the fix is a stronger *mark*, not a tinted interface.
+- Feedback state (success/attention/danger) and domain status (booked/active/
+  overdue) share hue families deliberately. Context plus the mandatory icon-and-word
+  separates them; a form error is not "rust means overdue", but they are the same
+  register of message.
+- Nothing amber is clickable anywhere in the system.

package/DESIGN.md

@@ -0,0 +1,210 @@
+# DESIGN.md — the design system
+
+The visual contract for every brignano surface: `brignano.io`, `life`, `homelab`,
+`driftwood`, and whatever comes next. Values live in [`tokens.css`](./tokens.css)
+and [`tokens.chart.css`](./tokens.chart.css); the reasoning is in
+[`DECISIONS.md`](./DECISIONS.md).
+
+**Read this before styling anything.** An agent asked to build a page in any of
+these repos should use these tokens, not invent a palette.
+
+---
+
+## 1. The identity in one line
+
+Competence and calm. Warm, not cold; confident, not loud. Near-monochrome, with
+colour used so sparingly that when it appears you look at it.
+
+Nothing here should read as a developer-portfolio template, and nothing should
+read as a toy.
+
+## 2. Two tiers, one foundation
+
+The professional site should be more polished than a private trip planner. That
+is a difference of **density and scale**, not of design system. Colour, type
+family, motion and shape are identical; what changes is how much room things get.
+
+| | **Marketing** — `brignano.io` | **Tool** — `life`, `homelab`, `driftwood` |
+|---|---|---|
+| Opt in | `class="tier-marketing"` on `<html>` | default, no class |
+| Body size | 17px | 15px |
+| Section rhythm | `--s9` (96px) | `--s6` (32px) |
+| Measure | 68ch | 780px |
+| Display face | Silkscreen — monogram, hero eyebrows | none (aliases to `--sans`) |
+| Motion | the trail, scroll reveal | none |
+| Density | whitespace carries the layout | scanning beats reading |
+
+## 3. Colour — one hue, one meaning
+
+> **Colour carries meaning. Never decoration.**
+> If a colour doesn't tell you something you'd otherwise have to read, it
+> doesn't ship.
+
+Every hue answers exactly one question, on every surface, in both tiers:
+
+| Token | Answers | Hue |
+|---|---|---|
+| neutral ramp | the page itself | cool grey |
+| `--i-*` | *you can act on this* | cobalt |
+| `--success` | *settled, confirmed, done* | forest |
+| `--attention` | *this wants you* | larch amber |
+| `--danger` | *this has gone wrong* | rust |
+| `--mark` | identity | larch amber, graphic only |
+
+On a typical tool-tier screen you should see **one or two** coloured things. If
+you see five, the rule has slipped.
+
+### Attention is one meaning
+
+A warning toast, the `NEXT UP` strip, and a deposit closing in six days are the
+same message at different volumes. They get the same colour. There is no separate
+"warning" hue and no separate "now/next" hue — collapsing them is what makes the
+system coherent across a marketing site and an operational tool.
+
+### Identity is not a fill
+
+`--mark` inks a **graphic**: the trail line, the `A|B` monogram, a hero rule.
+That is its entire permitted use. It is never a button, chip, badge, wash, border,
+or link.
+
+This is the resolution of a real problem. Amber used to be both the brand colour
+and the warning colour, kept apart by a rule about scale — and rules enforced by
+remembering get forgotten. Identity moved to the things that were always carrying
+it (the trail, the monogram, the type, restraint), so amber in UI chrome now only
+ever means *attention*. If you're reaching for `--mark` to tint an interface
+element, the answer is a neutral or a state colour.
+
+### Colour is a surface, not text
+
+A wash (12% light / 20% dark via `color-mix`) behind an element with the text kept
+near-ink reads as *a state*. Coloured letters just read as coloured letters and
+fight legibility at small sizes. Use the `-surface` and `-line` tokens for the
+wash and its edge, and `-ink` when a state genuinely must be a label.
+
+`--attention` (`#b4741f`) is **3.85:1** on white. It is a mark and fill colour,
+not a text colour. `--attention-ink` (`#8a5714`, 6.08:1) is the text step.
+
+### Never colour alone
+
+Every state ships with an **icon and a word**. Colour is the accelerant, not the
+signal — this covers colour-vision deficiency, greyscale printing, and forced-colours
+mode in one rule.
+
+### What does NOT get colour
+
+Event type. Six types in six colours is exactly the complication this avoids —
+type is already carried by a text label. Nor `idea`, `planning`, `someday`, or
+`parked`: nothing is being asked of you, so nothing should catch your eye.
+
+## 4. Interaction
+
+The part that makes an interface feel built rather than styled.
+
+- `--i` fill, `--i-hover`, `--i-pressed`, `--i-ink` for links/icons/focus.
+- **Disabled is neutral, never hued** (`--i-disabled-bg` / `--i-disabled-ink`). A
+  greyed-out control must stop signalling "click me".
+- Focus is always visible: 2px `--i-ink` outline, 2px offset. Never remove it.
+- Hover and pressed surfaces on neutral elements come from `--surface-hover` and
+  `--surface-active`, not from opacity tricks.
+
+## 5. Type
+
+Three roles, no more:
+
+- **`--sans` (Geist)** — body and headings, both tiers. Tabular figures (`tnum`) on
+  body copy so dates, prices and countdowns align in a column.
+- **`--mono` (IBM Plex Mono)** — data that must read *precise*: confirmation codes,
+  timestamps, stat numbers, eyebrow labels.
+- **`--display` (Silkscreen)** — marketing tier only. The `A|B` monogram and hero
+  eyebrows. Used **once, well** — it is memorable precisely because it is
+  concentrated. On the tool tier it aliases to `--sans`.
+
+No serif. Abstract over literal — no mascots, clip-art, or stock scenery.
+
+## 6. Space, shape, elevation
+
+4px base (`--s1` … `--s9`). Radius: `--radius-sm` for chips and pills, `--radius`
+for cards, `--radius-lg` for hero surfaces.
+
+**Elevation differs by theme.** Light mode separates surfaces with a hairline plus
+a shadow (`--shadow-1/2/3`). Dark mode does not use borders — surfaces get
+*lighter* with elevation. This is why `--line` can stay nearly invisible in dark.
+
+## 7. Motion
+
+**Content is visible by default. Motion is progressive enhancement layered on top
+— never the thing that makes content appear.**
+
+This is a hard contract. `brignano.io` shipped a homepage whose contact CTA
+rendered at `opacity: 0` on **100% of loads**, because an animation library owned
+the visible state and computed its scroll offsets before a client-side widget grew
+the page. Any animation system that can leave content hidden when JS fails, races,
+or is disabled is disqualified.
+
+`prefers-reduced-motion` renders the final state immediately, with no transforms —
+and that block ships inside `tokens.css` so no surface can forget it. One easing
+curve (`--ease`), three durations, compositor-only properties.
+
+## 8. Charts
+
+The one place the restraint rule does **not** apply: a categorical chart needs
+enough distinct hues to tell series apart, and eight ambers help nobody. Full
+rationale in [`tokens.chart.css`](./tokens.chart.css). The short version:
+
+- Series colours are `--chart-1…8`, **assigned in fixed order, never cycled**.
+- Colour follows the entity, never its rank — a filter must not repaint survivors.
+- A 9th series folds into `--chart-other`, facets, or gets cut.
+- State colours are reserved and never become "series 4".
+- ≥2 series always carries a legend; ≤4 are also direct-labelled.
+- Text wears text tokens, never the series colour.
+- **Never a dual-axis chart.** Two measures of different scale → two charts.
+
+## 9. Accessibility floor
+
+Non-negotiable in both themes:
+
+- Body text ≥ 4.5:1; large text and UI marks ≥ 3:1.
+- Touch targets ≥ 44px on coarse pointers, with a `.touch-hit` opt-out for controls
+  whose shape is meaningful (a 22px circular checkbox forced to 44px becomes an
+  oval — it expands its hit area instead).
+- Every state carries an icon and a word.
+- Measured ratios sit next to their values in `tokens.css`. Changing a value means
+  re-measuring it.
+
+## 10. Integrating with a Tailwind consumer
+
+Tailwind's dark variant keys off a `.dark` class; these tokens key off
+`[data-theme]`. **Both must be set together**, by the same code, in both places
+that change the theme (the pre-paint script and the toggle):
+
+```js
+root.classList.toggle("dark", d);
+root.setAttribute("data-theme", d ? "dark" : "light");
+```
+
+Setting only the class is a silent, half-broken state: Tailwind utilities flip
+but the tokens do not, and the page renders one theme's tokens under the other
+theme's utilities. Setting only the attribute leaves every `dark:` utility dead.
+
+The reason the attribute is required rather than relying on
+`prefers-color-scheme`: a site with a manual toggle has already *resolved* the
+OS preference into an explicit choice. If the tokens also consulted the media
+query, a user on a dark OS who chose light would get dark tokens under light
+utilities. `[data-theme]` is what makes the choice authoritative.
+
+Import order matters — Tailwind first, then tokens, then the bridge:
+
+```css
+@import "tailwindcss";
+@import "@brignano/design/tokens.css";
+@import "@brignano/design/tailwind.css";
+```
+
+## 11. The one rule that keeps this true
+
+**Never hardcode a hex outside `tokens.css`.**
+
+Hardcoded values silently survive a theme change. `life`'s status pills carried
+literal greys for months and would have stayed light grey in dark mode.
+`brignano.io` carried four literal violet hexes plus ~15 `violet-*` utilities,
+which is why changing the accent was a migration rather than a one-line edit.

package/README.md

@@ -0,0 +1,48 @@
+# @brignano/design
+
+The shared design system for every brignano surface — `brignano.io`, `life`,
+`homelab`, `driftwood`, and whatever comes next.
+
+| File | What it is |
+|---|---|
+| [`DESIGN.md`](./DESIGN.md) | **Start here.** The rules — the three colour layers, the two tiers, type, motion. |
+| [`DECISIONS.md`](./DECISIONS.md) | Why the values are what they are. ADRs. |
+| [`tokens.css`](./tokens.css) | Single source of truth for colour, type, space, shape, motion. |
+| [`tokens.chart.css`](./tokens.chart.css) | Validated categorical palette for data viz. |
+
+## The shape of it
+
+Three layers, so no colour does two jobs:
+
+- **`--brand-*`** — identity. Larch amber. The trail, the monogram. Never a control.
+- **`--i-*`** — affordance. Cobalt. Links, buttons, focus, selection. Semantically inert.
+- **`--ok / --warn / --err / --info`** — state. Conventional hues, always with an icon and a word.
+
+Distinctiveness lives in the brand layer; conventionality lives in the control layer.
+
+## Consuming it
+
+```jsonc
+"dependencies": { "@brignano/design": "github:brignano/design#v1.0.0" }
+```
+
+```css
+@import '@brignano/design/tokens.css';
+@import '@brignano/design/tokens.chart.css'; /* only if the surface has charts */
+```
+
+The tool tier is the default. A marketing surface opts in with
+`class="tier-marketing"` on `<html>`, which unlocks the display face and opens the
+type scale. Colour is identical across tiers.
+
+## For agents
+
+Read `DESIGN.md` before styling anything. Use the tokens. **Never hardcode a hex
+outside `tokens.css`** — a literal survives a theme change silently, which is how
+`life`'s status pills sat light grey in dark mode for months.
+
+## Status
+
+Pre-1.0. Not yet published to npm — install from the git tag above. Publishing
+`v1.0.0` waits until `brignano.io` is actually consuming it, so the first published
+version isn't one that's immediately superseded.

package/package.json

@@ -0,0 +1,29 @@
+{
+  "name": "@brignano/design",
+  "version": "0.1.0",
+  "description": "Shared design system for brignano surfaces \u2014 colour, type, space, shape, motion.",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/brignano/design.git"
+  },
+  "publishConfig": {
+    "access": "public",
+    "provenance": true
+  },
+  "files": [
+    "tokens.css",
+    "tokens.chart.css",
+    "tailwind.css",
+    "DESIGN.md",
+    "DECISIONS.md"
+  ],
+  "exports": {
+    "./tokens.css": "./tokens.css",
+    "./tokens.chart.css": "./tokens.chart.css",
+    "./tailwind.css": "./tailwind.css"
+  },
+  "sideEffects": [
+    "*.css"
+  ]
+}

package/tailwind.css

@@ -0,0 +1,55 @@
+/* Tailwind v4 bridge for @brignano/design.
+   Import AFTER tokens.css and after `@import "tailwindcss"`:
+
+     @import "tailwindcss";
+     @import "@brignano/design/tokens.css";
+     @import "@brignano/design/tailwind.css";
+
+   `@theme inline` is load-bearing: it makes the generated utilities emit
+   `var(--i)` rather than baking a literal at build time, so `bg-interactive`
+   follows the light/dark switch instead of freezing one theme's value. */
+@theme inline {
+  --color-ink: var(--ink);
+  --color-ink-soft: var(--ink-soft);
+  --color-slate: var(--slate);
+  --color-bg: var(--bg);
+  --color-card: var(--card);
+  --color-line: var(--line);
+  --color-line-strong: var(--line-strong);
+  --color-surface-hover: var(--surface-hover);
+  --color-surface-active: var(--surface-active);
+
+  --color-interactive: var(--i);
+  --color-interactive-ink: var(--i-ink);
+  --color-interactive-hover: var(--i-hover);
+  --color-interactive-pressed: var(--i-pressed);
+  --color-interactive-surface: var(--i-surface);
+  --color-on-interactive: var(--on-i);
+
+  --color-success: var(--success);
+  --color-success-ink: var(--success-ink);
+  --color-success-surface: var(--success-surface);
+  --color-attention: var(--attention);
+  --color-attention-ink: var(--attention-ink);
+  --color-attention-surface: var(--attention-surface);
+  --color-danger: var(--danger);
+  --color-danger-ink: var(--danger-ink);
+  --color-danger-surface: var(--danger-surface);
+
+  --color-mark: var(--mark);
+  --color-mark-ink: var(--mark-ink);
+
+  --font-sans: var(--sans);
+  --font-mono: var(--mono);
+  --font-display: var(--display);
+
+  --radius-sm: var(--radius-sm);
+  --radius-DEFAULT: var(--radius);
+  --radius-lg: var(--radius-lg);
+
+  --shadow-1: var(--shadow-1);
+  --shadow-2: var(--shadow-2);
+  --shadow-3: var(--shadow-3);
+
+  --ease-brand: var(--ease);
+}

package/tokens.chart.css

@@ -0,0 +1,134 @@
+/* ─────────────────────────────────────────────────────────────────────────
+   tokens.chart.css — the categorical palette for data visualisation.
+
+   WHY THIS IS A SEPARATE FILE FROM THE BRAND ACCENT
+   -------------------------------------------------
+   A chart's colours do a different job from a brand's colours, so they are
+   not derived from the accent and they are not the status ramp.
+
+     brand accent (--accent)   identity. One hue. "This is Anthony."
+     status (--forest/rust)    state. RESERVED — never a series colour.
+     categorical (this file)   IDENTITY OF A SERIES. Needs 8 hues that a
+                               human can tell apart at a glance, including
+                               the ~8% of men with a colour-vision
+                               deficiency.
+
+   Trying to derive eight distinguishable series hues from one amber gives
+   you eight ambers nobody can separate. Charts genuinely need the range —
+   the constraint is separability, not restraint.
+
+   THESE VALUES ARE VALIDATED, NOT CHOSEN BY EYE
+   ----------------------------------------------
+   Both modes pass every hard gate of the six-check colour formula:
+
+     lightness band     PASS  (all 8 inside the mode's band)
+     chroma floor       PASS  (all 8 >= 0.1)
+     CVD separation     PASS  worst adjacent dE 9.1 light / 8.4 dark  (>=8)
+     normal-vision      PASS  worst adjacent dE 19.6 light / 19.3 dark (>=15)
+     contrast           light: slots 3, 4, 5 sit below 3:1 — see RELIEF below
+                        dark:  all 8 clear 3:1
+
+   The ORDER is the colourblind-safety mechanism, not decoration. Slots are
+   assigned in fixed order and NEVER cycled. Re-ordering silently breaks the
+   adjacent-pair separation the gates above measure. If you change anything
+   here, re-run the validator on both modes before shipping.
+
+   RULES OF USE
+   ------------
+   - Fixed order, never cycled. A 9th series is not a generated hue: fold it
+     into "Other", facet into small multiples, or cut it. (`stats-pie.tsx`
+     already does this correctly — top 8 + "Other".)
+   - Colour follows the ENTITY, never its rank. A filter that changes the
+     series count must not repaint the survivors. Map name -> slot once.
+   - RELIEF: on light mode, slots 3/4/5 fall below 3:1 against the surface.
+     That is legal only with visible direct labels or a table view — which
+     the donut's centre readout and the legend already provide. Do not use
+     those three as the ONLY signal for a mark with no label.
+   - Never colour-alone: >=2 series always carries a legend, and <=4 are also
+     direct-labelled.
+   - Text wears text tokens (--ink / --ink-soft / --slate), never the series
+     colour. A coloured mark beside a label carries the identity.
+   ───────────────────────────────────────────────────────────────────────── */
+
+:root {
+  --chart-surface: var(--card);
+
+  --chart-1: #2a78d6; /* blue    */
+  --chart-2: #eb6834; /* orange  */
+  --chart-3: #1baf7a; /* aqua    — relief required (2.74:1) */
+  --chart-4: #eda100; /* yellow  — relief required (2.11:1) */
+  --chart-5: #e87ba4; /* magenta — relief required (2.62:1) */
+  --chart-6: #008300; /* green   */
+  --chart-7: #4a3aa7; /* violet  */
+  --chart-8: #e34948; /* red     */
+
+  /* Everything past slot 8 aggregates here. Deliberately neutral: "Other"
+     is not an entity, so it does not earn a hue. */
+  --chart-other: var(--slate);
+
+  /* Axes, gridlines and the ring behind overlapping marks. Recessive by
+     design — the data is the ink, the frame is not. */
+  --chart-grid: var(--line);
+  --chart-axis: var(--slate);
+
+/* ─────────────────────────────────────────────────────────────────────────
+   SEQUENTIAL — one hue, light to dark, for CONTINUOUS MAGNITUDE.
+   Not categorical. Use when the thing being coloured is "how much", not
+   "which one": the GitHub contribution heatmap, a density map, a calendar.
+
+   Rules that differ from the categorical palette above:
+     - ONE hue. Never a rainbow — a rainbow implies categories where there
+       are only degrees.
+     - Lightness must be MONOTONIC. Verified: light L 0.838 -> 0.107
+       descending, dark L 0.015 -> 0.532 ascending, every adjacent step
+       separated by dL >= 0.037.
+     - `--seq-0` is NEUTRAL on purpose. Zero contributions is not a small
+       amount of the hue, it is the absence of a value — colouring it a pale
+       blue would claim data that isn't there.
+
+   The hue is cobalt, the same family as --i. That is intentional: a
+   magnitude ramp is informational, the same register as a link, and giving
+   it its own hue would add a meaning the system doesn't need.
+   ───────────────────────────────────────────────────────────────────────── */
+  --seq-0: var(--line);
+  --seq-1: #c7dcfb;
+  --seq-2: #8ab4f4;
+  --seq-3: #3b82f6;
+  --seq-4: #1d4ed8;
+}
+
+@media (prefers-color-scheme: dark) {
+  :root:not([data-theme='light']) {
+    --chart-1: #3987e5;
+    --chart-2: #d95926;
+    --chart-3: #199e70;
+    --chart-4: #c98500;
+    --chart-5: #d55181;
+    --chart-6: #008300;
+    --chart-7: #9085e9;
+    --chart-8: #e66767;
+
+    --seq-0: var(--line);
+    --seq-1: #1e3a8a;
+    --seq-2: #1d4ed8;
+    --seq-3: #3b82f6;
+    --seq-4: #93c5fd;
+  }
+}
+
+:root[data-theme='dark'] {
+  --chart-1: #3987e5;
+  --chart-2: #d95926;
+  --chart-3: #199e70;
+  --chart-4: #c98500;
+  --chart-5: #d55181;
+  --chart-6: #008300;
+  --chart-7: #9085e9;
+  --chart-8: #e66767;
+
+  --seq-0: var(--line);
+  --seq-1: #1e3a8a;
+  --seq-2: #1d4ed8;
+  --seq-3: #3b82f6;
+  --seq-4: #93c5fd;
+}

package/tokens.css

@@ -0,0 +1,380 @@
+/* ─────────────────────────────────────────────────────────────────────────
+   tokens.css — the shared foundation for every brignano surface.
+
+   Consumers:
+     brignano.io   (Next / Tailwind v4)  — marketing tier
+     life          (Astro)               — tool tier
+     homelab, driftwood, future tools    — tool tier
+
+   ── ONE HUE, ONE MEANING ───────────────────────────────────────────────
+   Every colour here answers exactly one question, everywhere it appears,
+   on every surface. That is the whole design of this file.
+
+     NEUTRAL     the page. Most of every screen.
+     --i-*       "you can act on this"      cobalt
+     --success   "settled, confirmed, done" forest
+     --attention "this wants you"           larch amber
+     --danger    "this has gone wrong"      rust
+     --mark      identity — a drawn mark, not a UI colour
+
+   Two consequences worth stating out loud, because both were mistakes in
+   earlier drafts of this system:
+
+   1. ATTENTION IS ONE MEANING. A warning toast, the NEXT UP strip, and a
+      deposit closing in six days are the same message at different
+      volumes, so they are the same colour. There is no separate "warning"
+      hue and no separate "now/next" hue.
+
+   2. IDENTITY IS NOT A FILL. Amber used to be the brand colour AND the
+      warning colour, managed by a rule about scale. Rules enforced by
+      remembering get forgotten. So identity moved to the thing that was
+      always carrying it — the trail, the monogram, the type — and --mark
+      exists only to ink a graphic. It is never a button, chip, wash, or
+      border. The naming is the enforcement.
+
+   ── RULES THAT MAKE THIS FILE TRUSTWORTHY ──────────────────────────────
+   1. NEVER hardcode a hex outside this file. A literal survives a theme
+      change silently — that is how `life`'s status pills sat light grey in
+      dark mode for months.
+   2. Every colour is declared in BOTH theme scopes. CSS cannot share a
+      declaration block between a media query and a plain selector, so the
+      dark list is duplicated on purpose. Edit one, edit the other.
+   3. Ratios in the comments are MEASURED. Change a value, re-measure it.
+
+   See DESIGN.md for the rules that govern use, DECISIONS.md for why.
+   ───────────────────────────────────────────────────────────────────────── */
+
+:root {
+  color-scheme: light;
+
+  /* ── Neutral ramp ─────────────────────────────────────────────────────
+     Twelve steps, up from five. The gap that mattered most: there was no
+     hover or pressed background token, so every interactive surface in
+     both repos was improvising.
+
+     Deliberately COOL-leaning — a cool grey lets the warm mark and the
+     amber attention state read as warm, instead of muddying into them. */
+  --n-0: #ffffff;
+  --n-25: #fafafa;
+  --n-50: #f3f3f1;
+  --n-100: #ececea; /* hairline */
+  --n-200: #e2e2e0; /* hover surface */
+  --n-300: #cbcbce; /* strong border, pressed surface */
+  --n-400: #a9a9ae;
+  --n-500: #8a8a8f; /* muted label   3.44:1 — large text / UI marks only */
+  --n-600: #6b6b73; /*               5.28:1 */
+  --n-700: #52525b; /* secondary     7.73:1 */
+  --n-800: #33333a;
+  --n-900: #111111; /* primary      18.88:1 */
+
+  /* Semantic aliases. Components use THESE, not the raw steps. */
+  --bg: var(--n-25);
+  --card: var(--n-0);
+  --surface-hover: var(--n-100);
+  --surface-active: var(--n-200);
+  --ink: var(--n-900);
+  --ink-soft: var(--n-700);
+  --slate: var(--n-500);
+  --line: var(--n-100);
+  --line-soft: var(--n-50);
+  --line-strong: var(--n-300);
+  --on-dark: var(--n-25);
+
+  /* ── Interactive — cobalt ─────────────────────────────────────────────
+     Everything you can act on: links, buttons, focus, selection. Chosen to
+     be semantically INERT — it carries no inherited meaning the way amber,
+     green and red do — and complementary to the mark hue, so identity and
+     affordance never compete for the same attention.
+
+       --i          fill               5.17:1  (white label 5.17:1)
+       --i-ink      link/icon/focus    6.70:1  on #fff
+       --i-hover    hover fill        10.36:1
+       --i-pressed  pressed fill      12.65:1
+
+     DISABLED IS NEUTRAL, NEVER HUED — a greyed-out control must stop
+     signalling "click me". */
+  --i: #2563eb;
+  --i-ink: #1d4ed8;
+  --i-hover: #1e40af;
+  --i-pressed: #1e3a8a;
+  --i-surface: color-mix(in srgb, var(--i) 12%, transparent);
+  --i-line: color-mix(in srgb, var(--i) 32%, transparent);
+  --i-selection: color-mix(in srgb, var(--i) 26%, transparent);
+  --on-i: #ffffff;
+  --i-disabled-bg: var(--n-200);
+  --i-disabled-ink: var(--n-400);
+
+  /* ── State ────────────────────────────────────────────────────────────
+     Three hues, one meaning each, identical on every surface and both
+     tiers. Always shipped with an ICON AND A WORD — colour is never the
+     only signal.
+
+       --success    settled · confirmed · done · succeeded    6.29:1
+       --attention  now · next · warning · needs you          6.08:1
+       --danger     overdue · failed · invalid                6.10:1
+
+     `--info` is the interactive hue on purpose: an informational message
+     is the same "neutral, no action implied" register as a link.
+
+     `-ink` is the text-safe step; the bare token is for marks and fills.
+     `-surface` and `-line` are the wash and its edge. */
+  --success: #2f6b4f;
+  --success-ink: #245740;
+  --attention: #b4741f; /* 3.85:1 — mark/fill only, NOT text */
+  --attention-ink: #8a5714; /* 6.08:1 */
+  --danger: #a4442c;
+  --danger-ink: #8a3722;
+  --info: var(--i);
+  --info-ink: var(--i-ink);
+
+  --success-surface: color-mix(in srgb, var(--success) 12%, transparent);
+  --attention-surface: color-mix(in srgb, var(--attention) 12%, transparent);
+  --danger-surface: color-mix(in srgb, var(--danger) 12%, transparent);
+  --info-surface: var(--i-surface);
+  --success-line: color-mix(in srgb, var(--success) 32%, transparent);
+  --attention-line: color-mix(in srgb, var(--attention) 32%, transparent);
+  --danger-line: color-mix(in srgb, var(--danger) 32%, transparent);
+  --info-line: var(--i-line);
+
+  /* ── Mark — identity ──────────────────────────────────────────────────
+     Inks a GRAPHIC: the trail line, the A|B monogram, a hero rule. That is
+     the entire permitted use.
+
+     It is NOT a button, chip, badge, wash, border, or link. If you are
+     reaching for it to tint a UI element, the answer is a neutral or a
+     state colour — see DESIGN.md §3.
+
+     It shares larch amber with --attention deliberately: the identity and
+     the attention state are the same warmth, and because --mark never
+     appears as a UI surface the two can never be mistaken for each other
+     in the same context. */
+  --mark: #b4741f;
+  --mark-ink: #8a5714; /* when the mark carries a label, 6.08:1 */
+
+  /* ── Legacy aliases ───────────────────────────────────────────────────
+     Kept so existing `life` components keep compiling. Do not use in new
+     work — reach for the semantic tokens above.
+
+     --larch-deep is declared explicitly in BOTH themes rather than
+     aliased, because "deep" inverts: darker in light, BRIGHTER in dark. An
+     alias to either role silently changes one theme — it moved
+     .pill-active from #f0bd74 to #e0a44f before this was caught. */
+  --forest: var(--success);
+  --forest-deep: var(--success-ink);
+  --larch: var(--attention);
+  --larch-deep: #8a5714;
+  --rust: var(--danger);
+  --rust-deep: var(--danger-ink);
+  --gold: var(--slate);
+
+  /* ── Type ─────────────────────────────────────────────────────────────
+       --sans     Geist — body and headings, both tiers
+       --mono     IBM Plex Mono — data that must read precise
+       --display  Silkscreen — MARKETING TIER ONLY (monogram, hero eyebrows)
+
+     NOTE: Geist is not yet installed in `life` — only brignano.io
+     self-hosts it. Until added, the stack falls through to Inter and that
+     repo renders as before. Adding it is a deliberate separate change. */
+  --sans: 'Geist', 'Inter Variable', -apple-system, BlinkMacSystemFont, 'Segoe UI', sans-serif;
+  --mono: 'IBM Plex Mono', ui-monospace, SFMono-Regular, monospace;
+  --display: var(--sans);
+
+  /* ── Space ── 4px base. Tiers differ by which steps they reach for. */
+  --s1: 4px;  --s2: 8px;  --s3: 12px; --s4: 16px; --s5: 24px;
+  --s6: 32px; --s7: 48px; --s8: 64px; --s9: 96px;
+
+  /* ── Shape & elevation ────────────────────────────────────────────────
+     In LIGHT these are shadows; in DARK the surface lightens instead. */
+  --radius-sm: 6px;
+  --radius: 12px;
+  --radius-lg: 18px;
+  --shadow-1: 0 1px 2px rgba(17, 17, 17, 0.04);
+  --shadow-2: 0 2px 8px rgba(17, 17, 17, 0.07);
+  --shadow-3: 0 8px 24px rgba(17, 17, 17, 0.10);
+  --scrim: rgba(17, 17, 17, 0.55);
+  --shadow: var(--shadow-1); /* legacy alias */
+
+  /* ── Motion ───────────────────────────────────────────────────────────
+     Content is ALWAYS visible by default; motion is enhancement layered on
+     top, never the thing that makes content appear. brignano.io shipped a
+     homepage whose contact CTA was invisible on 100% of loads because an
+     animation library owned the visible state. See DESIGN.md §6. */
+  --ease: cubic-bezier(0.22, 1, 0.36, 1);
+  --dur-fast: 150ms;
+  --dur: 250ms;
+  --dur-slow: 600ms;
+}
+
+/* ── Dark ───────────────────────────────────────────────────────────────
+   Selected, not inverted:
+   1. Not pure black. #0d0d0f — pure black behind bright text causes
+      halation and is fatiguing at night, which is when a personal tool
+      actually gets opened.
+   2. Surfaces LIGHTEN with elevation instead of gaining borders.
+   3. Accents lift in luminance rather than shifting hue, and washes carry
+      a higher mix — 12% over #0d0d0f is invisible where it reads on white.
+
+   Declared twice: the media query is the default and no-JS fallback;
+   [data-theme] is the in-app toggle and must WIN over the system.
+   `:not([data-theme='light'])` lets the toggle force light under a dark OS. */
+@media (prefers-color-scheme: dark) {
+  :root:not([data-theme='light']) {
+    color-scheme: dark;
+
+    --n-0: #0d0d0f;
+    --n-25: #131316;
+    --n-50: #17171a;
+    --n-100: #202024;
+    --n-200: #2a2a2f;
+    --n-300: #3a3a41;
+    --n-400: #55555e;
+    --n-500: #8b8b93; /* 5.29:1 on card */
+    --n-600: #9c9ca4;
+    --n-700: #a8a8b0; /* 7.58:1 */
+    --n-800: #d0d0d2;
+    --n-900: #f2f2f0; /* 15.96:1 */
+
+    --bg: var(--n-0);
+    --card: var(--n-50);
+    --surface-hover: var(--n-100);
+    --surface-active: var(--n-200);
+    --on-dark: var(--n-0);
+
+    --i: #60a5fa; /* 7.04:1 */
+    --i-ink: #60a5fa;
+    --i-hover: #93c5fd;
+    --i-pressed: #bfdbfe;
+    --i-surface: color-mix(in srgb, var(--i) 20%, transparent);
+    --i-line: color-mix(in srgb, var(--i) 44%, transparent);
+    --i-selection: color-mix(in srgb, var(--i) 30%, transparent);
+    --on-i: #111111;
+
+    --success: #6fbf95;
+    --success-ink: #8fd4ae;
+    --attention: #e0a44f;
+    --attention-ink: #e0a44f; /* 8.17:1 — mark and label converge in dark */
+    --danger: #e07a5f;
+    --danger-ink: #ec9880;
+
+    --success-surface: color-mix(in srgb, var(--success) 20%, transparent);
+    --attention-surface: color-mix(in srgb, var(--attention) 20%, transparent);
+    --danger-surface: color-mix(in srgb, var(--danger) 20%, transparent);
+    --success-line: color-mix(in srgb, var(--success) 44%, transparent);
+    --attention-line: color-mix(in srgb, var(--attention) 44%, transparent);
+    --danger-line: color-mix(in srgb, var(--danger) 44%, transparent);
+
+    --mark: #e0a44f;
+    --mark-ink: #e0a44f;
+
+    --larch-deep: #f0bd74; /* brighter step in dark — see the light block */
+
+    --shadow-1: 0 1px 2px rgba(0, 0, 0, 0.45);
+    --shadow-2: 0 2px 10px rgba(0, 0, 0, 0.55);
+    --shadow-3: 0 10px 28px rgba(0, 0, 0, 0.65);
+    --scrim: rgba(0, 0, 0, 0.68);
+  }
+}
+
+:root[data-theme='dark'] {
+  color-scheme: dark;
+
+  --n-0: #0d0d0f;
+  --n-25: #131316;
+  --n-50: #17171a;
+  --n-100: #202024;
+  --n-200: #2a2a2f;
+  --n-300: #3a3a41;
+  --n-400: #55555e;
+  --n-500: #8b8b93;
+  --n-600: #9c9ca4;
+  --n-700: #a8a8b0;
+  --n-800: #d0d0d2;
+  --n-900: #f2f2f0;
+
+  --bg: var(--n-0);
+  --card: var(--n-50);
+  --surface-hover: var(--n-100);
+  --surface-active: var(--n-200);
+  --on-dark: var(--n-0);
+
+  --i: #60a5fa;
+  --i-ink: #60a5fa;
+  --i-hover: #93c5fd;
+  --i-pressed: #bfdbfe;
+  --i-surface: color-mix(in srgb, var(--i) 20%, transparent);
+  --i-line: color-mix(in srgb, var(--i) 44%, transparent);
+  --i-selection: color-mix(in srgb, var(--i) 30%, transparent);
+  --on-i: #111111;
+
+  --success: #6fbf95;
+  --success-ink: #8fd4ae;
+  --attention: #e0a44f;
+  --attention-ink: #e0a44f;
+  --danger: #e07a5f;
+  --danger-ink: #ec9880;
+
+  --success-surface: color-mix(in srgb, var(--success) 20%, transparent);
+  --attention-surface: color-mix(in srgb, var(--attention) 20%, transparent);
+  --danger-surface: color-mix(in srgb, var(--danger) 20%, transparent);
+  --success-line: color-mix(in srgb, var(--success) 44%, transparent);
+  --attention-line: color-mix(in srgb, var(--attention) 44%, transparent);
+  --danger-line: color-mix(in srgb, var(--danger) 44%, transparent);
+
+  --mark: #e0a44f;
+  --mark-ink: #e0a44f;
+
+  --larch-deep: #f0bd74;
+
+  --shadow-1: 0 1px 2px rgba(0, 0, 0, 0.45);
+  --shadow-2: 0 2px 10px rgba(0, 0, 0, 0.55);
+  --shadow-3: 0 10px 28px rgba(0, 0, 0, 0.65);
+  --scrim: rgba(0, 0, 0, 0.68);
+}
+
+/* ── Marketing tier ─────────────────────────────────────────────────────
+   `class="tier-marketing"` on <html> (brignano.io). Unlocks the display
+   face and opens the type scale. COLOUR IS IDENTICAL ACROSS TIERS — that
+   is the point of this file. Tool tier is the default. */
+.tier-marketing {
+  --display: 'Silkscreen', var(--mono);
+  --text-xs: 0.75rem;
+  --text-sm: 0.875rem;
+  --text-base: 1.0625rem;
+  --text-lg: 1.25rem;
+  --text-xl: 1.5rem;
+  --text-2xl: 2rem;
+  --text-3xl: 2.75rem;
+  --text-4xl: clamp(2.75rem, 6vw, 4rem);
+  --section-gap: var(--s9);
+  --measure: 68ch;
+}
+
+:root {
+  /* Tool-tier scale — compact, because scanning beats reading. */
+  --text-xs: 0.6875rem;
+  --text-sm: 0.8125rem;
+  --text-base: 0.9375rem;
+  --text-lg: 1.0625rem;
+  --text-xl: 1.25rem;
+  --text-2xl: 1.5rem;
+  --text-3xl: 1.875rem;
+  --text-4xl: 2.25rem;
+  --section-gap: var(--s6);
+  --measure: 780px;
+}
+
+::selection {
+  background: var(--i-selection);
+}
+
+/* Ships here so no surface can forget it. */
+@media (prefers-reduced-motion: reduce) {
+  *,
+  *::before,
+  *::after {
+    animation-duration: 0.01ms !important;
+    animation-iteration-count: 1 !important;
+    transition-duration: 0.01ms !important;
+    scroll-behavior: auto !important;
+  }
+}