@brignano/design 0.1.1 → 0.2.0

package/DECISIONS.md

@@ -215,3 +215,36 @@ with it; `--mark` does not.
   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.
+
+---
+
+## ADR-0005 — Diagrams are not charts: neutral nodes, colour for state only
+
+**Status:** accepted · 2026-10-13
+
+### Context
+
+`driftwood` draws architecture diagrams and was the first consumer to need them.
+Its first pass on these tokens took the chart exception (§8, ADR-0002) and tinted
+each node by family (edge, compute, data, messaging…) with `--chart-1…6`. On a
+real 46-resource platform that put six hues on screen before anything was wrong,
+and the database that was down was one more tinted box among them.
+
+### Decision
+
+A diagram follows the restraint rule. The chart exception exists because a chart
+has nothing *but* colour to tell series apart; a diagram node has an icon, a name
+and a kind label, so family is already carried three times. Nodes are neutral.
+Colour is reserved for state: health (`--danger`, `--attention`) and what a change
+did, via three new aliases — `--diff-added`, `--diff-changed`, `--diff-removed` —
+over the existing state hues. No new hue enters the system.
+
+### Consequences
+
+- On a healthy, unchanged system the diagram is grey, and that is correct:
+  nothing is asking for you.
+- `--diff-changed` shares cobalt with links. Context separates them (a node edge
+  with a `~ changed` tag is not underlined text), the same way feedback and domain
+  status share hues in ADR-0004.
+- Standalone exports (SVG files, Mermaid in a pull request) take the light theme's
+  values, resolved from `tokens.css` by the consumer at build time.

package/DESIGN.md

@@ -159,7 +159,44 @@ rationale in [`tokens.chart.css`](./tokens.chart.css). The short version:
 - Text wears text tokens, never the series colour.
 - **Never a dual-axis chart.** Two measures of different scale → two charts.
 
-## 9. Accessibility floor
+## 9. Diagrams and diffs
+
+An architecture diagram (`driftwood`, `homelab`) is a picture of a system, read to
+answer "what changed, and what is broken". It follows the restraint rule, **not**
+the chart exception: node *type* is a category like event type, and is carried by
+an icon and a label, never a hue. A diagram where every node is tinted by family
+is thirty coloured things, and the one that is down disappears among them.
+
+- **Nodes are neutral.** `--card` fill, `--line-strong` edge, `--radius` corners,
+  an icon in `--ink-soft`, the name in `--ink`, the kind in `--mono` at
+  `--text-xs` in `--ink-soft`. Grouping is a zone: `--line` hairline, no fill or
+  a faint one, a `--mono` eyebrow label.
+- **Edges are `--slate`.** They are UI marks (3:1), never text.
+- **Only state gets colour**, and always as a tag with a symbol and a word as well:
+
+  | Token | Means | Tag |
+  |---|---|---|
+  | `--diff-added` | this change created it | `+ added` |
+  | `--diff-changed` | this change modified it | `~ changed` |
+  | `--diff-removed` | this change removes it — dashed, struck through | `− removed` |
+  | `--danger` | it is down | `✕ down` |
+  | `--attention` | degraded, or differs from the design | `▲ degraded` |
+
+  The diff tokens alias the state hues on purpose (added is *settled*, a change is
+  *informational*, a removal is the change that can lose data), so a diff adds no
+  hue to the system. Health wins the fill (`-surface`); a diff only takes the edge.
+- **Selection** is the focus treatment: a 2px `--i-ink` outline, offset. Asking
+  "what depends on this?" dims everything unrelated to ~30% opacity and inks the
+  connecting edges in `--ink`; it never introduces a colour.
+- **Lead with the verdict.** A page about a deploy opens with one sentence saying
+  what happened and what needs you, then the pills that back it up, then the
+  picture.
+- **Diagrams follow the theme.** On a page they use the tokens like everything
+  else. A diagram exported as a standalone file (an SVG, a Mermaid block in a pull
+  request) cannot use `var()`; it takes the **light** theme's values, resolved from
+  this file at build time, never typed in.
+
+## 10. Accessibility floor
 
 Non-negotiable in both themes:
 
@@ -171,7 +208,7 @@ Non-negotiable in both themes:
 - Measured ratios sit next to their values in `tokens.css`. Changing a value means
   re-measuring it.
 
-## 10. Integrating with a Tailwind consumer
+## 11. 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
@@ -200,7 +237,7 @@ Import order matters — Tailwind first, then tokens, then the bridge:
 @import "@brignano/design/tailwind.css";
 ```
 
-## 11. The one rule that keeps this true
+## 12. The one rule that keeps this true
 
 **Never hardcode a hex outside `tokens.css`.**
 

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Anthony Brignano
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -9,6 +9,7 @@ The shared design system for every brignano surface — `brignano.io`, `life`,
 | [`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. |
+| [`previews/`](./previews) | Live swatches. Open one in a browser to see the tokens render. |
 
 ## The shape of it
 
@@ -35,6 +36,31 @@ 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.
 
+## Previews
+
+`previews/` holds a page per area — colour, type, elevation, controls, feedback, diagrams,
+status. Each renders its subject twice, once in the viewer's theme and once on a
+forced-dark ground, so drift between the two shows up without toggling anything.
+No build step: open the file.
+
+Every preview opens with a card marker:
+
+```html
+<!-- @dsCard group="Foundations" -->
+```
+
+That first line is what a [claude.ai/design][ds] design-system project reads to
+build its card index — `group` becomes the section heading in the Design System
+pane. The markers are comments, so they cost nothing when the page is opened
+locally.
+
+**A sync to such a project keeps this layout** — `tokens.css` at the project
+root, `previews/` one level below it. `_preview.css` reaches it with
+`@import '../tokens.css'` rather than carrying its own copy, because a second
+copy of the tokens is the drift this repo exists to prevent. The trade is that
+the parent reference is load-bearing: flatten the uploaded bundle and every
+preview renders unstyled.
+
 ## For agents
 
 Read `DESIGN.md` before styling anything. Use the tokens. **Never hardcode a hex
@@ -55,7 +81,7 @@ something actually looks different.
 
 ## Releasing
 
-The tag is the trigger. `.github/workflows/release.yml` publishes to npm on any
+The tag is the trigger. `.github/workflows/publish.yml` publishes to npm on any
 `v*` tag, after checking the tag agrees with `package.json` — npm versions are
 immutable, so a mismatch is caught before it's permanent.
 
@@ -69,4 +95,20 @@ this repo and there should never be one — the runner exchanges its OIDC identi
 for a short-lived credential via npm [trusted publishing][tp], which is also what
 produces the provenance attestation. A laptop has no such identity.
 
+**The workflow is called `publish.yml` in every repo that publishes a package,
+and that is not cosmetic.** npm's Trusted Publisher form takes the workflow
+filename as part of the OIDC claim, and offers `publish.yml` as its example. Any
+other name is a value you have to remember correctly, from the GitHub side, while
+filling in a form on the npm side. Getting it wrong fails as `ENEEDAUTH` — npm
+declines the exchange, `npm publish` falls back to token auth, and there is no
+token — which names neither the workflow nor the mismatch. Matching the tool's
+default is cheaper than being right every time.
+
+Setting up a new package: create `.github/workflows/publish.yml` from this one,
+then add the Trusted Publisher on npmjs.com — publisher GitHub Actions, the org
+and repo, workflow filename `publish.yml`, and **environment name blank**, since
+these workflows declare no `environment:`. Configure it before the first tag, or
+the first publish fails the way this one did.
+
+[ds]: https://claude.ai/design
 [tp]: https://docs.npmjs.com/trusted-publishers/

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@brignano/design",
-  "version": "0.1.1",
-  "description": "Shared design system for brignano surfaces \u2014 colour, type, space, shape, motion.",
+  "version": "0.2.0",
+  "description": "Shared design system for brignano surfaces — colour, type, space, shape, motion.",
   "license": "MIT",
   "repository": {
     "type": "git",

package/tokens.css

@@ -136,6 +136,26 @@
   --danger-line: color-mix(in srgb, var(--danger) 32%, transparent);
   --info-line: var(--i-line);
 
+  /* ── Diff ─────────────────────────────────────────────────────────────
+     What a change did to a thing: a deploy, a plan, a pull request. Aliases
+     of the state hues, so a diff adds no hue of its own (DESIGN.md §9):
+
+       --diff-added    created by this change      success — settled
+       --diff-changed  modified by this change     interactive — informational
+       --diff-removed  removed by this change      danger — can lose data
+
+     Always with a symbol and a word (+ added, ~ changed, − removed). Aliased
+     in this block only: these resolve against whichever theme block wins. */
+  --diff-added: var(--success);
+  --diff-added-ink: var(--success-ink);
+  --diff-added-surface: var(--success-surface);
+  --diff-changed: var(--i);
+  --diff-changed-ink: var(--i-ink);
+  --diff-changed-surface: var(--i-surface);
+  --diff-removed: var(--danger);
+  --diff-removed-ink: var(--danger-ink);
+  --diff-removed-surface: var(--danger-surface);
+
   /* ── Mark — identity ──────────────────────────────────────────────────
      Inks a GRAPHIC: the trail line, the A|B monogram, a hero rule. That is
      the entire permitted use.
@@ -331,6 +351,23 @@
   --scrim: rgba(0, 0, 0, 0.68);
 }
 
+:root {
+  /* Tool-tier scale — compact, because scanning beats reading.
+     Declared BEFORE the marketing tier on purpose: `:root` and
+     `.tier-marketing` have the same specificity, so on <html> whichever
+     comes later wins. With this block last, the class did nothing. */
+  --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;
+}
+
 /* ── Marketing tier ─────────────────────────────────────────────────────
    `class="tier-marketing"` on <html> (brignano.io). Unlocks the display
    face and opens the type scale. COLOUR IS IDENTICAL ACROSS TIERS — that
@@ -349,20 +386,6 @@
   --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);
 }