sheleg-design-skill 1.3.4 → 1.6.0

package/CHANGELOG.md

@@ -4,6 +4,263 @@ All notable changes to this project are documented in this file. The format
 follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/); versions
 follow [SemVer](https://semver.org/spec/v2.0.0.html).
 
+## [1.6.0] - 2026-08-05
+
+The harvest of a 41-skill audit of the design skills installed on this machine.
+The finding was narrow and repeated everywhere: the skill specified *what a
+thing looks like* with real rigour and left *how much, how fast, and whether at
+all* to whoever happened to be typing. Three of those four are now numeric, and
+two of them are checked by a script.
+
+Landed on top of 1.5.0, which shipped the `field-notes` pack from a concurrent
+run in the same working copy. That pack was already written against the widened
+contract below, so the two runs converged rather than collided — it is the first
+and so far only pack on the thirteen-heading contract.
+
+### Added
+
+- **`MOTION_DOCTRINE.md`** — the missing half of the motion story.
+  `SHELEG_DESIGN.md` says how motion is built; this says whether to build it.
+  Frequency decides first, and it overrules taste: anything a user meets a
+  hundred times a day does not animate, ever. Then the easing tree with
+  `ease-in` banned in UI and the reason stated, three named curves, a duration
+  table with a 300 ms ceiling, springs in Apple's notation, and interruptibility
+  as the actual argument for reaching for one. Then the forms that are defects
+  rather than preferences — scroll listeners, continuous input held in component
+  state, blur and grain on scrolling containers, easing under `scrub`,
+  `useEffect` where `useGSAP` belongs, and layout transforms silently erased by
+  animated ones. Closes on anti-drift: the tokens are right and the built page is
+  generic anyway, which happens at application time and so is named there.
+
+- **Three calibration dials** — `DESIGN_VARIANCE`, `MOTION_INTENSITY`,
+  `VISUAL_DENSITY`, baseline `7 / 5 / 4`, read off the brief from a table. A
+  pack answers *which register*; it never answered *how far*, which is how a
+  regulated insurer and a design studio came out of one pack looking alike. The
+  dials are deliberately weak where the pack is strong: no dial invents a
+  colour, a face or a radius, and `MOTION_INTENSITY` sits **under** the
+  frequency table rather than over it.
+
+- **A widened pack contract — nine headings to thirteen.** `Components`,
+  `Hero`, `Responsive` and `Signature element`. The packs were precise about
+  colour and motion and then went quiet exactly where implementations drift:
+  per-component states, the opening viewport, collapse behaviour, and the one
+  element a page is remembered by. The skeleton also now teaches concentric
+  radius arithmetic, a `Not for` line in `Register`, and that an origin nobody
+  can re-read is decorative.
+
+- **`test/validate_palette.py`** — the colour part is computable, so it is
+  computed. Claimed contrast ratios are re-derived from the hex and compared,
+  WCAG floors are enforced, and semantic colours are checked for separation in
+  OKLab under protanopia, deuteranopia and tritanopia. A pack may sit under the
+  floor only if it states out loud that colour is never the only carrier.
+
+- **`test/sloplint.py`** — the skill is held to its own bans. The token layers
+  and every fenced example are read for `100vh`, scroll listeners, bare
+  `ease-in`, transitions on layout properties and pure black fields; and the
+  tables the docs promise are asserted by string, so a rule cannot be deleted
+  without failing the build. Both scripts ship a `--self-test` that watches every
+  check fail against a planted defect — a green from a check nobody has seen say
+  no is not evidence.
+
+- **A six-layer scene depth model**, a **parameter handoff to the built-in
+  `dataviz` skill** instead of duplicating it, and a **`?variant=` procedure**
+  for choosing between packs by mounting them on a populated page rather than
+  arguing about them.
+
+- **The three generated looks that are defaults rather than decisions** —
+  recorded so a page that lands on one has to say whether that was a measurement
+  or the default talking.
+
+### Changed
+
+- **The pack section gate is all-or-nothing.** The nine original headings stay
+  required; adopt one of the widened four and all four are owed. The six packs
+  that shipped before the widening stay valid on nine — backfilling them
+  honestly needs re-reading each live reference, and three record a product name
+  where an address belongs, so they cannot be re-read at all. Filling those
+  sections from the token layer instead would be inventing values with a
+  citation attached, which is the failure the pack layer exists to prevent. The
+  rule closes the gap either way: no pack can be half-widened, so a new pack
+  cannot copy the thirteen-heading skeleton, keep the cheap nine and pass.
+- `npm test` now runs three gates, not one. `npm run selftest` runs the planted
+  defects.
+- `package.json` described "three locked style packs" while six shipped.
+
+### Not shipped, deliberately
+
+- **An eighth `industrial-brutalist` pack.** The register is real and the set
+  lacks it, but the only description available carries a synthesised palette,
+  not one measured off a production site. Held rather than authored.
+- **A backfill of the six existing packs onto the widened contract.** Same
+  reason, from the other direction: three of them cannot be re-read.
+
+## [1.5.0] - 2026-08-04
+
+The register the skill was missing for its own audience: a developer tool that
+does not live on a dark console. Six packs could dress a landing page, a
+dashboard, a deck and two kinds of consumer health, and none of them had an
+answer for open-source software sold on *being checkable* — which is most of
+the software the people using this skill actually build.
+
+### Added
+
+- **Seventh style pack: `field-notes`** — extracted from **graphify.com**
+  (2026) by reading its live computed styles: 92 declared custom properties,
+  the served `@font-face` set, every authored rule pulled out of the CSSOM, and
+  a contrast pass over all 38 colour pairs in the system. Warm off-white paper
+  with a green cast (`#F8F7F0`), near-black green-cast ink (`#16211B`, 15.4:1),
+  one rust accent (`#9A3F28`), and a complete dark twin.
+
+  Its defining composition is what separates it from every warm pack already
+  here: **the page is one continuous sheet ruled by a `1px` hairline.** Ten of
+  the reference's sixteen sections are divided by nothing but that line; three
+  add a 40% wash. Where `orchard` stacks discrete slabs and `atrium` runs a
+  continuous field that changes layout, this one draws a rule and keeps going.
+
+  The hero is the other half of the idea: not a dark band but a **dawn** —
+  eight stops from `#062A22` to the exact paper colour, so the dark has no
+  edge. Over it, an inline `feTurbulence` grain at `baseFrequency 0.82`, a
+  radial vignette, and an ambient layer that is **notation rather than
+  particles**: mathematical glyphs at 14% opacity, one at a time flipping to
+  the verified hue.
+
+  It also carries the two devices most worth stealing. **The numbered eyebrow**
+  — `〉 HOW IT WORKS [03/09]`, built from `::before`/`::after` on a `data-n`
+  attribute — makes a marketing page into a document with a table of contents.
+  And **printer's crop marks** at the four corners: eight 1px gradient arms,
+  `inset: 14px`, ink at 30%, desktop only. Both cost nothing and both state the
+  thesis that the page is a printed record.
+
+  Elevation is a **ring** (`0 0 0 1px var(--line)`), not a shadow; radii are a
+  proportional ramp off one `--radius`, so a hardcoded `12px` is banned; and
+  motion is two eases doing two jobs — `.15s` `cubic-bezier(.4,0,.2,1)` for
+  control state, `.5s` `cubic-bezier(.22,1,.36,1)` for scroll entry — with one
+  rule on top: **only the verified hue ever animates colour.** The rust never
+  moves, because a brand that animates stops reading as an identity and starts
+  reading as a status.
+
+  Four corrections to the reference ship with it, each measured. Its hero
+  accent phrase — the single most prominent piece of text on the site — runs
+  the light brand over the gradient at **2.29:1** at the top and **1.41:1** in
+  the middle; the pack adds `--brand-on-dark` `#CF7A52` (**4.82:1**) and bans
+  the other. Its `--verify` green is 3.2:1 on paper and its own
+  `--verify-foreground: #fff` is 3.4:1 on the green, so both are fills and the
+  labels take `-ink`. It sets `color-scheme` nowhere despite a complete dark
+  theme — the same trap that bit `workbench`. And it paints three unrelated
+  dark palettes (warm-brown theme, forest bands, navy terminal) plus an app
+  layer whose neutrals drift browner than its page layer and whose ring is a
+  violet used nowhere else; the pack reconciles all of it to the forest family
+  and the page's own neutrals.
+
+  The pack ships that app layer deliberately, with a routing rule rather than a
+  turf war: `workbench` stays the default for neutral product UI, which should
+  disappear; `field-notes` is for a product whose console must read as the same
+  paper as its site.
+
+- **`AI_PRODUCT_PATTERNS.md` gains the provenance pattern** (§4), promoted out
+  of the pack because it is the reference's one genuinely transferable
+  invention and a direct extension of the file's existing *honest state* rule:
+  **label the part, not the whole.** A single confidence number on a mixed
+  answer hides exactly the clause the reader needed to check, so the pattern
+  attaches a small set of named states — `[EXTRACTED]` · `[INFERRED]` ·
+  `[AMBIGUOUS]` — inline to the span each one qualifies, with three tests for
+  whether it is honest: every state must be reachable, every label must derive
+  from something real, and if you cannot say which words a state covers you do
+  not know it well enough to show it. Any pack can implement it on three hues.
+
+- **Test scenario T13** — the developer register **and** the fork against
+  `instrument-console`, run as two prompts in separate contexts. The pack is
+  only worth its row if an agent can tell "this product has a source" from
+  "this product has a dial", so a pass requires both branches: one that must
+  select `field-notes`, one that must stay on the dark console.
+
+### Changed
+
+- `SKILL.md`, `README.md`, `bin/cli.js`, `install.sh` and the Cursor rule all
+  learn the seventh pack; the CLI's help and the README's file table stop
+  saying "six".
+
+## [1.4.0] - 2026-08-03
+
+Two packs for the warm consumer register, extracted from two production sites
+that solve the same brief in opposite ways — one premium and editorial, one
+friendly and modular. Between them they replace the reflex a generated wellness
+page falls into (a gradient, three cards, a stock photo of someone stretching).
+
+### Added
+
+- **Fifth style pack: `atrium`** — the warm consumer register, extracted from
+  **functionhealth.com** (2026) by reading its live token layer and computed
+  styles. The skill could already do dark-technical, editorial, product UI and
+  decks; it had no answer for *premium consumer health* — the page that has to
+  land a serious clinical claim without a sterile surface anywhere on it.
+
+  What it encodes: **one continuous cream field with no dark bands** (sections
+  are separated by a 48→99px rhythm and a change of layout, never by flipping
+  the background — the reflex that makes generated pages read as a stack of
+  slabs); a single terracotta accent `#B05A36`; a serif that ships **one
+  weight, 300**, set at `line-height: 0.9`, whose entire emphasis vocabulary is
+  *one italic accent phrase* per heading; a sans with only 300 and 600 in it;
+  mono reserved for exactly one component; a fully fluid `clamp()` scale keyed
+  to a single 23.5rem→90rem band, so the page resizes as one object; hairline
+  and cream-on-cream steps instead of shadows, with three shadows that each
+  have one job; and `999px` on everything clickable.
+
+  Its signature motif is the **fluted-glass hero**: a WebGL shader refracting
+  photography through reeded-glass ribs, shipped with the real numbers (82.8
+  ribs at `0.36rad`, amplitude `0.0255`, feather `0.63`, a 7.2s reveal cycle,
+  the ink scrim at 70%) over a still-image fallback. Its lifecycle is the pack's
+  most useful lesson: context-lost, tab-hidden, reduced-motion and no-WebGL are
+  four branches that ship in the same commit as the effect.
+
+  It also promotes something the reference does that most sites do not: **every
+  autonomous motion carries a visible `PAUSE MOTION` control**, and the pack
+  bans shipping one without it — `prefers-reduced-motion` alone does not
+  discharge the obligation.
+
+  Three measured contrast traps are carried as Gotchas rather than left for an
+  audit: the accent is AA on the field (4.6:1) but **fails on the cream surface**
+  (4.2:1); `--good`/`--info` are fills at 2.1:1 and 3.4:1 and may never be text;
+  and the hairline is 1.6:1 — decorative strength, not affordance strength, so
+  controls need `--line-strong`, `--line-ink` or `--accent` instead.
+- **Sixth style pack: `orchard`** — the same buyer, the opposite voice,
+  extracted from **gutgutgoose.com** (2026). Where `atrium` is one continuous
+  field, `orchard` is **a stack of rounded slabs**: every section is a card with
+  its own fill (oat, sage, cacao), no two adjacent slabs repeat, and the field
+  shows around all of them. Its whole layout rhythm is four numbers — `64px 24px`
+  slab padding, `44px` between blocks, `55px` between slabs, `36px` card padding.
+
+  Three colours with fixed jobs — oat is the paper, sage is the brand, candy
+  orange is the verb — and the pack's most useful rule is that **two of them are
+  not text colours**. A rounded geometric display at Medium carries all
+  hierarchy, so body weight never goes above 500; the price is deliberately set
+  in the body face, because a rounded display numeral reads as branding and a
+  price has to read as a fact.
+
+  Its signature material is **light, not shadow**: the "candy pill" is a flat
+  fill wearing two inset white hairlines (`.8` top, `.35` bottom) plus an
+  ambient glow **in the button's own hue** — the only real drop shadow in the
+  system. Its one cinematic move is a **word-by-word scrubbed headline** (opacity
+  only, ~12% of hero scroll per word) beside a sticky visual column, and that is
+  the entire motion budget.
+
+  The reference is strong on composition and weak on contrast, so the pack
+  carries the three measured failures with fixes from inside its own palette:
+  the CTA label is **2.8:1** (white on orange) and must use the cacao ink for
+  **5.6:1**; body copy on the sage slab is **3.4:1** — and oat on sage is
+  **2.96:1**, under even the large-text floor — so small text moves to
+  `--primary-deep` at **4.9:1**; and the 60% ink is **4.1:1** on oat, a caption
+  colour only. It also ships the `prefers-reduced-motion` branch the reference
+  has nowhere on the site.
+- `scenarios.md` gains T11 and T12 for the two consumer registers.
+
+### Changed
+
+- README, `SKILL.md`, `bin/cli.js`, `install.sh` and the standalone Cursor rule
+  route and ship both new packs; the stale "three style packs" counts in the
+  README are corrected to six, and the Cursor rule — which had listed only three
+  packs and never gained `briefing-room` — now names all six.
+
 ## [1.3.4] - 2026-07-30
 
 ### Added

package/README.md

@@ -10,7 +10,7 @@ nothing. Ask it for a dashboard and you get a different flavor of the same
 problem — invented colors, six accent hues, dark mode retrofitted later.
 
 This skill is the taste layer. It gives a coding agent **one motion
-methodology** for cinematic, scroll-driven pages and **three locked style
+methodology** for cinematic, scroll-driven pages and **six locked style
 packs** with ready-made design tokens, so what it builds reads as one system
 instead of a pile of effects.
 
@@ -46,6 +46,9 @@ voice is the timeline and slides therefore never animate).
 | `editorial-luxury` | warm cream + espresso ink, sage accent, Fraunces/Newsreader, dossier motifs | editorial / research / premium B2B |
 | `workbench` | neutral grays, borders as elevation, one blue accent, mono data, light + dark twins | dashboards, admin, internal & dev tools |
 | `briefing-room` | dark 16:9 deck: one blue hue top to bottom (OKLCH), mono slide furniture, 1-bit dithered art, claims as titles | investor & board decks, technical briefings, talks published as a page |
+| `atrium` | warm cream daylight field with no dark bands, one terracotta accent, light serif with italic asides, fluted-glass hero over photography | consumer health, longevity & diagnostics, wellness, premium care, high-trust DTC |
+| `orchard` | warm oat field of rounded slabs, sage brand + one candy-orange action, rounded geometric display, soft-3D pills built from inset light | friendly consumer biotech, DTC wellness, testing kits & supplements |
+| `field-notes` | warm green-cast paper ruled by hairlines, one rust accent, a hero that dissolves into the page instead of ending, numbered mono eyebrows, crop marks, colour that encodes how a claim is known | open-source & developer tools sold on auditability — code intelligence, provenance, evals, agent memory |
 
 Each pack locks palette, type, texture, motion tokens, signature motifs and
 bans — and ships a `tokens/<pack>.css` to copy verbatim, so the agent never
@@ -114,7 +117,7 @@ skills.
 | `SHELEG_DESIGN.md` | The full reference: architecture, layer-by-layer mechanics with code, the exact morph math, the DOM↔WebGL projection bridge, a build-from-scratch recipe, and why each piece works |
 | `FIGMA_BRIDGE.md` | The design↔code contract: how a pack's tokens map onto Figma variable collections and modes, how to implement a design without importing raw values, and what cannot cross the border |
 | `AI_PRODUCT_PATTERNS.md` | The surfaces a model drives: the five states of a call, streaming instead of spinners, latency, provenance and uncertainty, agent confirmations, and the bans that keep it honest |
-| `styles/*.md` | The three style packs — palette, type, texture, motion tokens, motifs, bans, and the traps each one carries |
+| `styles/*.md` | The seven style packs — palette, type, texture, motion tokens, motifs, bans, and the traps each one carries |
 | `styles/tokens/*.css` | The ready-made token layer per pack, copied verbatim instead of transcribed (workbench ships a light `:root` plus a `data-theme="dark"` twin) |
 | `styles/STYLE_PACK_TEMPLATE.md` | The pack contract as a skeleton, so a new style is authored against the same headings rather than improvised |
 
@@ -211,7 +214,7 @@ and the [Code of Conduct](./CODE_OF_CONDUCT.md). To report a vulnerability, see
 
 Built by ssheleg — [sshlg.me](https://sshlg.me)
 
-- X / Twitter — [@fuck_this_year](https://x.com/fuck_this_year)
+- X / Twitter — [@sshlg93](https://x.com/sshlg93)
 - Telegram — [@sshlg](https://t.me/sshlg)
 
 Part of the [ssheleg skill family](https://github.com/ssheleg/sshlg-skills):

package/bin/cli.js

@@ -115,10 +115,12 @@ ${c("bold", "What it installs")}
   SHELEG_DESIGN.md     the full reference (architecture, recipes, why it works)
   FIGMA_BRIDGE.md      the design↔code contract (tokens ⇄ Figma variables)
   AI_PRODUCT_PATTERNS.md  chat / agent / streaming surfaces (honest state)
-  styles/              four style packs — instrument-console (dark console),
+  styles/              seven style packs — instrument-console (dark console),
                        editorial-luxury (warm editorial), workbench (light/dark
-                       product UI), briefing-room (dark 16:9 presentation deck)
-                       — plus a ready-made token CSS per pack and
+                       product UI), briefing-room (dark 16:9 presentation deck),
+                       atrium (warm cream consumer health), orchard (friendly
+                       consumer biotech), field-notes (warm paper dev tools) —
+                       plus a ready-made token CSS per pack and
                        STYLE_PACK_TEMPLATE.md for authoring more
 `);
 }
@@ -192,7 +194,7 @@ function main() {
     `\n${c("green", "✓")} ${c("bold", "SHELEG Design")} installed to ${c("blue", rel + "/")}\n` +
       `  ${c("dim", "SKILL.md")}          the agent skill\n` +
       `  ${c("dim", "SHELEG_DESIGN.md")}  the full reference\n` +
-      `  ${c("dim", "styles/")}           style packs + token CSS (instrument-console / editorial-luxury / workbench / briefing-room)\n\n` +
+      `  ${c("dim", "styles/")}           style packs + token CSS (instrument-console / editorial-luxury / workbench / briefing-room / atrium / orchard / field-notes)\n\n` +
       `Your Cursor / Claude agent can now discover the skill and build\n` +
       `cinematic, scroll-driven pages — or style product UI (dashboards,\n` +
       `admin, internal tools) from the workbench pack — on its principles.\n\n` +

package/cursor/rules/sheleg-design.mdc

@@ -12,8 +12,13 @@ not from many animations. If the project has the full skill installed
 and the chosen style pack in `styles/` first (instrument-console — dark
 console; editorial-luxury — warm editorial; workbench — quiet light/dark
 product UI for dashboards and tools, used standalone without the cinematic
-motion layer); otherwise follow the contract below (self-contained on
-purpose).
+motion layer; briefing-room — dark 16:9 presentation deck, standalone, slides
+never animate; atrium — warm cream consumer-health field, one terracotta
+accent, fluted-glass hero; orchard — friendly consumer biotech, oat slabs,
+sage brand and one candy-orange action; field-notes — open-source developer
+tools on warm green-cast paper ruled by hairlines, one rust accent, a hero
+that dissolves into the page, and colour that encodes how a claim is known);
+otherwise follow the contract below (self-contained on purpose).
 
 ## Five principles, in order
 

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "sheleg-design-skill",
-  "version": "1.3.4",
-  "description": "Design taste as an installable agent skill. Cinematic scroll-driven landing pages built on one scroll clock and layered degrade-to-calm motion, plus three locked style packs with ready-made design tokens — instrument-console (dark), editorial-luxury (warm), workbench (light/dark product UI for dashboards, admin and dev tools). Works with Cursor, Claude Code and any agent that reads a SKILL.md.",
+  "version": "1.6.0",
+  "description": "Design taste as an installable agent skill. Cinematic scroll-driven landing pages built on one scroll clock and layered degrade-to-calm motion, a motion doctrine that decides whether to animate before it decides how, three calibration dials, and seven locked style packs with ready-made design tokens — instrument-console, editorial-luxury, workbench, briefing-room, atrium, orchard and field-notes. Colour and slop gates run as scripts, not opinions. Works with Cursor, Claude Code and any agent that reads a SKILL.md.",
   "bin": {
     "sheleg-design-skill": "bin/cli.js"
   },
@@ -18,9 +18,12 @@
     "node": ">=16"
   },
   "scripts": {
-    "test": "python3 test/validate.py && node --check bin/cli.js",
-    "validate": "python3 test/validate.py",
-    "smoke": "node bin/cli.js --help"
+    "test": "python3 test/validate.py && python3 test/validate_palette.py && python3 test/sloplint.py && node --check bin/cli.js",
+    "validate": "python3 test/validate.py && python3 test/validate_palette.py && python3 test/sloplint.py",
+    "smoke": "node bin/cli.js --help",
+    "palette": "python3 test/validate_palette.py",
+    "sloplint": "python3 test/sloplint.py",
+    "selftest": "python3 test/validate_palette.py --self-test && python3 test/sloplint.py --self-test"
   },
   "keywords": [
     "skill",
@@ -39,7 +42,10 @@
     "landing-page",
     "sheleg"
   ],
-  "author": "ssheleg",
+  "author": {
+    "name": "ssheleg",
+    "url": "https://x.com/sshlg93"
+  },
   "license": "MIT",
   "repository": {
     "type": "git",

package/plugins/sheleg-design/.claude-plugin/plugin.json

@@ -2,9 +2,10 @@
   "name": "sheleg-design",
   "displayName": "SHELEG Design",
   "description": "SHELEG Design methodology: cinematic scroll-driven landing pages (single scroll clock, layered degrade-to-calm motion, WebGL particle formations) plus pluggable visual style packs — instrument-console (dark console), editorial-luxury (warm editorial), workbench (light/dark product UI for dashboards and tools). Ships the sheleg-design skill, the architecture reference, style packs with ready-made token CSS, and the /sheleg-design command.",
-  "version": "1.3.4",
+  "version": "1.6.0",
   "author": {
-    "name": "ssheleg"
+    "name": "ssheleg",
+    "url": "https://x.com/sshlg93"
   },
   "homepage": "https://github.com/ssheleg/sheleg-design-skill",
   "repository": "https://github.com/ssheleg/sheleg-design-skill",

package/plugins/sheleg-design/skills/sheleg-design/AI_PRODUCT_PATTERNS.md

@@ -78,6 +78,44 @@ indeterminate indicator plus elapsed time beats an invented estimate.
   drafted reply, a synthesized summary of someone's words, a generated image of
   a real place. Not everywhere: labeling every pixel is noise.
 
+### The provenance tag — label the part, not the whole
+
+A single confidence number on a whole answer is the wrong unit. Answers are
+usually mixed: one clause was read straight out of a source, the next was
+derived, a third is the model's guess. Scoring the assembly hides exactly the
+part the reader needed to check.
+
+The working pattern is a **small set of named states, attached inline to the
+span each one qualifies**. Three is enough, and the names are verbs about
+knowing rather than adjectives about certainty:
+
+| State | Means | Colour role |
+|---|---|---|
+| `[EXTRACTED]` | lifted verbatim from a source the user can open | the *verified* hue |
+| `[INFERRED]` | derived by a step the system can name | the *brand* hue — the system's own voice |
+| `[AMBIGUOUS]` | the evidence supports more than one reading | the *unverified* hue |
+
+Shape, so it annotates instead of shouting: monospace at ~10px, positive
+tracking, a bracketed label, a transparent fill and a 1px border of the state's
+own colour at ~25% alpha, on a small radius. It sits **beside the claim**, never
+collected into a legend at the bottom — a legend makes the reader hold a mapping
+in their head, which is the cost the tag exists to remove.
+
+Three rules that decide whether it is honest:
+
+- **Every state must be reachable.** If nothing is ever `[AMBIGUOUS]`, the
+  vocabulary is decoration and the reader learns to ignore all of it.
+- **The label must be derivable from something real** — a retrieval hit, a
+  traversal path, a rule that fired. A tag assigned by a second model call
+  guessing at the first one is confidence theater with better typography.
+- **Tag the span, not the message.** If you cannot say which words a state
+  applies to, you do not yet know it well enough to display it.
+
+Any pack can implement this: it needs three hues, each with a text-safe ink and
+a wash. `field-notes` ships that set (`--verify` / `--witness` / `--brand`, each
+with `-ink` and `-soft`) because it was extracted from a product whose entire
+argument is provenance; `workbench` can carry it on its own semantic colours.
+
 ## 5. Agent actions: the confirm is the design
 
 The moment a model stops answering and starts *acting*, the interface's job