sheleg-design-skill 1.9.0 → 1.10.0

package/CHANGELOG.md

@@ -4,6 +4,114 @@ 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.10.0] - 2026-08-10
+
+A fresh-eyes audit of the whole skill, and the finding is the green: at 1.9.0 all
+three gates passed — 1270 / 412 / 224 — while the skill told a reading agent
+there were six style packs, handed the chart layer a token ramp no pack defines,
+and stated thirteen contrast ratios that are wrong.
+
+Full report with every `file:line`, and the reproductions:
+[`docs/audit/2026-08-10-skill-audit.md`](./docs/audit/2026-08-10-skill-audit.md).
+
+### Fixed — what an agent was told that was not true
+
+- **The `dataviz` handoff named tokens no pack defines.** `SKILL.md` promised a
+  ramp `--accent-tint … --accent-deep`: `--accent-tint` exists in **one** pack of
+  twelve, `--accent-deep` in three, and **no pack has both**. It promised a
+  status set of `--good` / `--warning` / `--danger` that seven packs lack and
+  two have no version of at all. An undefined custom property does not error —
+  the declaration goes invalid at computed-value time and the property silently
+  inherits — so the agent follows the instruction exactly and the page is wrong.
+  The table is now written by role, and the non-uniform mappings are named.
+- **Thirteen stated contrast ratios, recomputed and corrected.** `blueprint`'s
+  ratio column is headed ``On `--bg` `` and every number in it was computed
+  against pure white (`--ink` 17.74 → **17.15**, `--accent` 7.53 → **7.28**,
+  pure black 21 → **20.31**). `prism` claimed ink "≥18:1 over all four stops"
+  three times; it is **15.85–16.82** — 18.95 is ink on plain white, carried onto
+  the wash. Also `showroom` 15.9 → **15.35** and 7.7 → **7.08**, `maquette` 5.0 →
+  **5.62** and 13.9 → **13.57**, `editorial-luxury` 6.1 → **6.93**, `workbench`
+  5.0 → **4.57**. None crossed a floor; all were presented as measured.
+- **Two packs justified one accent by a "symmetry" that is a mathematical
+  identity.** WCAG contrast is symmetric for every pair by definition. In
+  `showroom`, whose field is white, the sentence stated one measurement twice; in
+  `blueprint`, whose field is not, the two directions genuinely differ and the
+  pack asserted one number for both.
+- **`atrium` prescribed `transition: padding-top .2s` on a sticky header** — a
+  layout property, transitioned, on scroll: the exact form `MOTION_DOCTRINE.md`
+  forbids, shipped inside the bundle that ships the ban.
+- **`field-notes`' radius rule, its worked example and its token layer were three
+  different systems.** "Subtract the padding … `12 - 12 ≈ 7.2`" — subtraction
+  gives 0; the token layer uses `calc(var(--radius) * 0.6)`.
+- **`blueprint`'s Components and Hero instructed the violation its own Signature
+  element section names** (registration marks on both CTAs). `test/scenarios.md`
+  recorded this as "fixed in the same run"; only half of it had landed.
+- **`atrium` said three shadows exist**; its token layer defines four.
+- **The colour-blindness ban was copy-pasted into six packs**, asserting a
+  measurement across "several pairs" in packs owning one status colour or none —
+  and naming four states as if the pack supplied them, which is an invitation to
+  invent a hue. Rewritten for `orchard`, `editorial-luxury` and `briefing-room`.
+- **`MOTION_DOCTRINE.md` §5 over-banned**, forbidding everything outside four
+  properties while §2 prescribes an ease for colour changes. The ban is on
+  layout, which is what its own rationale says.
+- **ADR-0001 named a pack that never existed** (`lecture-hall`; the pack that
+  shipped from graphify.com is `field-notes`). The decision stands; the example
+  was written on a branch that never merged.
+
+### Added — the half-library nobody declared
+
+Six of twelve packs carry `## Components`, `## Hero`, `## Responsive` and
+`## Signature element`; six do not, and nothing said which. Every pack now
+declares **`Contract: core` or `Contract: widened`** above its Register, a core
+pack states what it leaves the reader to decide, the `SKILL.md` routing table
+marks it, and a check enforces the declaration against the headings present.
+
+### Added — six checks, each watched failing on a planted defect
+
+Counted claims (whitespace-normalised: the README's "six locked style packs" was
+split across a line break) · exhaustive pack enumerations in both manifests, the
+slash command, the CLI, the README and the Cursor rule · one name for the pack
+contract · the `Contract:` declaration · the core role vocabulary (`--bg`,
+`--ink`, and an accent role every pack resolves) · and **every stated contrast
+ratio, recomputed from the token layer**.
+
+The ratio check is scoped to claims whose base the document declares — a column
+headed ``On `--bg` ``, an `on/over --token` phrase, or an `--on-X` name. A first
+draft that inferred the partner produced 22 false positives out of 40.
+
+### Fixed — three gates that could not fail
+
+- **Deleting requirements made two gates quieter, and green.** Stripping a pack's
+  four widened headings took `validate.py` 1270 → 1269 and `sloplint.py` 224 →
+  223, both exit 0. **Ratchet floors** now live in `test/floors.json` and are
+  enforced by all three.
+- **One decoy comment disabled a slop-lint ban for a whole file, permanently.**
+  The check took the first match only and `continue`d past a nearby negation
+  word, so the counter fell and later occurrences went unexamined. Suppression is
+  now per occurrence, and ban-quoting sections are exempted by heading.
+- **`validate.py --self-test` printed OK for a self-test that did not exist** —
+  the same defect the 2026-08-05 retrospective recorded in `validate_palette.py`.
+  All three scripts now exit 2 on an unknown argument, and `validate.py` has a
+  real self-test: six planted defects, run against a copy of the tree.
+- **The slop lint read only fenced code blocks**, and no style pack contains one —
+  so all twelve packs, `SKILL.md`, both bridges and the AI patterns were never
+  linted. It now reads the inline CSS the packs prescribe in prose.
+- **`npm test` and both workflows now run every gate and every self-test.** The
+  release path was gated on one of three.
+
+### Fixed — stale counts and reach
+
+"six locked style packs" and "all six kits" (twelve), "T1–T7" (T1–T19), "Three
+packs extracted" (eight), the pack contract called nine / ten / thirteen in five
+places at once — one of which told an author to ship nine headings, which the
+gate then passed. `plugin.json`, `marketplace.json` and the `/sheleg-design`
+command named three packs of twelve, so nine could not be asked for by name.
+`MOTION_DOCTRINE.md`, marked REQUIRED, appeared on no install surface: it is now
+in the README table, the CLI help and banner, the slash command, and the Cursor
+rule — which gains the whole doctrine in condensed form.
+
+Gates: **1364 / 469 / 320**, from 1270 / 412 / 224.
+
 ## [1.9.0] - 2026-08-09
 
 Four style packs, taking the library from eight to twelve — and a fix to the

package/README.md

@@ -10,7 +10,8 @@ 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 **six locked style
+methodology** for cinematic, scroll-driven pages, **a motion doctrine** that
+decides whether to animate before it decides how, and **twelve locked style
 packs** with ready-made design tokens, so what it builds reads as one system
 instead of a pile of effects.
 
@@ -34,11 +35,13 @@ and collectively cinematic. One scroll "clock" feeds a WebGL particle field, a
 rail — each an independent, degrade-to-calm layer. Nothing crossfades; things
 *redeploy*.
 
-**Style packs** — the visual identity, pluggable per project. Two of them are
-meant to be used **standalone**, with none of the motion layer: `workbench`
-(quiet light/dark product UI for dashboards, admin panels, internal and dev
-tools) and `briefing-room` (a dark 16:9 presentation deck, where the presenter's
-voice is the timeline and slides therefore never animate).
+**Style packs** — the visual identity, pluggable per project. Three of them are
+meant to be used **standalone**: `workbench` (quiet light/dark product UI for
+dashboards, admin panels, internal and dev tools) and `briefing-room` (a dark
+16:9 presentation deck, where the presenter's voice is the timeline and slides
+therefore never animate) take none of the motion layer at all; `field-notes` is
+standalone by default — its reference carries no motion library — but may opt
+into the cinematic layer, and says so in its own *Motion flavor* section.
 
 | Pack | Look | Choose for |
 |---|---|---|
@@ -123,11 +126,12 @@ skills.
 |---|---|
 | `SKILL.md` | The agent-facing skill: discovery triggers, the principles, how to apply them, quick-reference rules, common mistakes |
 | `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 |
+| `MOTION_DOCTRINE.md` | Whether to animate at all, before how: the frequency table that kills motion on high-repetition paths, the easing tree and the `ease-in` ban, the duration ceiling, the forbidden forms, and the reduced-motion contract. `SKILL.md` marks it required before any animation |
 | `DESIGN_SYNC_BRIDGE.md` | The Claude Design contract: what a pack sends to claude.ai/design and in what shape, the rule for each of the four reference types, and the border motion does not cross |
 | `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 twelve 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/tokens/*.css` | The ready-made token layer per pack, copied verbatim instead of transcribed (`workbench` and `field-notes` each ship 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 |
 
 ## What you get out of it
@@ -197,7 +201,7 @@ cd ./ds-workbench && npm install && npm run build
 then `/design-sync` in that directory, from Claude Code. Three layers cross: the
 pack's **bans** as the design system's own README, `styles.css` built from
 `tokens/<pack>.css` verbatim, and the components — a six-name spine that is
-identical in all six kits, so switching packs swaps identity rather than API,
+identical in all twelve kits, so switching packs swaps identity rather than API,
 plus each pack's signature parts. **Motion does not cross**, exactly as it does
 not cross into Figma: a kit is the static half of a pack, and saying so is what
 stops an agent inventing motion to fill the silence.
@@ -224,16 +228,29 @@ repo. Entirely optional; without it the skill works from the pack alone.
 python3 test/validate.py   # or: npm test
 ```
 
-The validator is the repo's contract, not a formality — it checks manifests and
-four-way version sync, skill/command/rule front-matter and description canon,
-the full style-pack section contract, pack ↔ `SKILL.md` ↔ CLI-help agreement,
-the bundled template against `templates/`, both installers' file lists, the
-entire `.cursor/` mirror against the plugin copy, and every relative link. CI
-runs it on each push and PR alongside a negative self-test (the validator must
-fail on a corrupted version) and installs the bundle through **both** installers,
-diffing the result against the source.
+`npm test` is **four gates**, not one, and `validate.py` alone is about a third
+of the contract:
 
-`test/scenarios.md` (T1–T7) is the behavioral harness: fresh subagents given a
+| Gate | What it decides |
+|---|---|
+| `test/validate.py` | manifests and four-way version sync · skill/command/rule front-matter and the description canon · the pack section contract (nine always, the widened four all-or-nothing) and each pack's `Contract:` declaration · the core role vocabulary (`--bg`, `--ink`, and a resolvable accent) in every token layer · every counted claim (packs, kits, scenarios, headings) · exhaustive pack enumerations in the manifests, the command, the CLI, the README and the rule · one name for the pack contract · fork reciprocity · the eleven kit checks · `install.sh`'s file list, both directions · the whole `.cursor/` mirror · every relative link |
+| `test/validate_palette.py` | contrast floors and semantic separation per theme, including three simulated dichromacies · AI-default-cluster provenance · **every contrast ratio the docs state, recomputed from the token layer** |
+| `test/sloplint.py` | the bundle obeying its own bans, in token layers, fenced examples **and the inline CSS the packs prescribe in prose** · doctrine completeness · pack origin addressability |
+| `node --check bin/cli.js` | the installer parses |
+
+Each gate ships a `--self-test` that plants a defect it must catch (`npm run
+selftest`), rejects an unknown argument instead of silently running the normal
+pass, and enforces a **ratchet floor** from `test/floors.json` — a check count
+that falls means a requirement stopped being required, which is how stripping
+a pack's four widened sections used to make two gates *quieter* and still green.
+
+One honest limit: the npx installer is checked by asserting its runtime bundle
+walker exists, not by reading a file list — it has none by design. What proves
+it ships the right files is CI, which installs the bundle through **both**
+installers and `diff -r`s the result against the source, then builds all twelve
+kits.
+
+`test/scenarios.md` (T1–T19) is the behavioral harness: fresh subagents given a
 task, checking that the skill is discovered, applied and quoted correctly.
 Re-run the affected scenarios after any edit to `SKILL.md`, a pack or the
 reference.

package/bin/cli.js

@@ -228,7 +228,11 @@ ${c("bold", "Default")}
 ${c("bold", "What it installs")}
   SKILL.md             the agent-facing skill (discovery + principles)
   SHELEG_DESIGN.md     the full reference (architecture, recipes, why it works)
+  MOTION_DOCTRINE.md   whether to animate at all — frequency, easing, duration,
+                       forbidden forms, the reduced-motion contract
   FIGMA_BRIDGE.md      the design↔code contract (tokens ⇄ Figma variables)
+  DESIGN_SYNC_BRIDGE.md   the Claude Design contract (what a pack sends, and
+                       what does not cross)
   AI_PRODUCT_PATTERNS.md  chat / agent / streaming surfaces (honest state)
   styles/              twelve style packs — instrument-console (dark console),
                        editorial-luxury (warm editorial), workbench (light/dark
@@ -317,12 +321,13 @@ function main() {
   const rel = path.relative(cwd, targetDir) || ".";
   console.log(
     `\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 / atrium / orchard / field-notes / cyclorama / showroom / blueprint / prism / maquette)\n\n` +
+      `  ${c("dim", "SKILL.md")}            the agent skill\n` +
+      `  ${c("dim", "SHELEG_DESIGN.md")}    the full reference\n` +
+      `  ${c("dim", "MOTION_DOCTRINE.md")}  whether to animate at all — read before any animation\n` +
+      `  ${c("dim", "styles/")}             style packs + token CSS (instrument-console / editorial-luxury / workbench / briefing-room / atrium / orchard / field-notes / cyclorama / showroom / blueprint / prism / maquette)\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` +
+      `cinematic, scroll-driven pages — or style product UI (dashboards, admin,\n` +
+      `internal tools) from a standalone pack — on its principles.\n\n` +
       `${c("dim", "Docs: " + pkg.homepage)}\n`,
   );
 }

package/cursor/rules/sheleg-design.mdc

@@ -9,7 +9,8 @@ A page feels cinematic from a **single source of truth** (measured scroll
 position) driving **many cheap, layered, independently-degradable responses** —
 not from many animations. If the project has the full skill installed
 (`.cursor/skills/sheleg-design/`), read its `SKILL.md`, `SHELEG_DESIGN.md`,
-and the chosen style pack in `styles/` first (instrument-console — dark
+`MOTION_DOCTRINE.md` (before any animation) 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; briefing-room — dark 16:9 presentation deck, standalone, slides
@@ -29,6 +30,40 @@ static iridescent wash over mono body copy; maquette — enterprise data
 infrastructure as a cream axonometric model on a near-black table);
 otherwise follow the contract below (self-contained on purpose).
 
+## Whether to animate at all — before how
+
+Frequency decides before taste gets a vote. (Full doctrine:
+`MOTION_DOCTRINE.md` in the installed skill.)
+
+- Seen 100+ times a day — command palette, keyboard shortcut, tab switch:
+  **no animation, ever.** Never animate a keyboard-initiated action; it turns
+  instant into laggy and disconnects the result from the keypress.
+- Tens of times a day — hover, list navigation, inline toggles: remove it or
+  cut it to the floor. Occasional (modals, drawers, toasts): standard. Rare or
+  first-time (onboarding, empty-to-filled): delight is allowed.
+- Every animation answers "why does this move?" in one sentence — spatial
+  consistency, state indication, feedback, explanation, or preventing a jarring
+  cut. "It looked cool" is not an answer; if you cannot write the sentence,
+  delete the animation.
+- **`ease-in` is banned in UI.** It starts slow, in the exact moment the user is
+  watching hardest. Entering or leaving → `ease-out`; moving or morphing on
+  screen → `ease-in-out`; hover or colour change → `ease`; constant motion →
+  `linear`. Curves: `--ease-out: cubic-bezier(.23,1,.32,1)`,
+  `--ease-in-out: cubic-bezier(.77,0,.175,1)`,
+  `--ease-drawer: cubic-bezier(.32,.72,0,1)`.
+- **UI motion stays under 300 ms.** Button press 100–160ms · tooltip 125–200ms ·
+  dropdown 150–250ms · modal/drawer 200–500ms. Marketing and scrollytelling are
+  deliberately longer.
+- Never animate a property that triggers layout (`width`, `height`, `top`,
+  `left`, `padding`, `margin`, `gap`, `font-size`). Never a bare scroll
+  listener, never `requestAnimationFrame` writing component state, never
+  `backdrop-filter` or grain on a scrolling container, never a left-behind
+  `will-change`, never two marquees.
+- **Reduced motion is a contract, not a feature.** Anything beyond a colour
+  change honours `prefers-reduced-motion: reduce`; loops, parallax and springs
+  collapse to static or instant, never to "slower". Shipping an animation
+  without that branch is a bug, not a polish item.
+
 ## Five principles, in order
 
 1. **One clock.** All motion derives from one measured scroll state in one

package/kits/atrium/src/styles.css

@@ -119,7 +119,7 @@
   --track-mono: 0.1em;
   --track-mono-sm: 0.07em;
 
-  /* ---- Elevation: three shadows, one job each -------------------------- */
+  /* ---- Elevation: four shadows, one job each --------------------------- */
   --shadow-panel: 12px 32px 80px 0 rgba(42, 43, 47, 0.1); /* the hero panel */
   --shadow-lift: 0 4px 30px 0 rgba(0, 0, 0, 0.1); /* a card pulled forward */
   --shadow-cta: 0 2px 12px 0 rgba(0, 0, 0, 0.1); /* a button on photography */
@@ -175,7 +175,6 @@
     --marquee-cycle: 0s;
   }
 }
-
 /* ── components ── */
 
 /* Everything below consumes var(--…) only. Colour never appears as a literal:

package/kits/blueprint/src/styles.css

@@ -32,8 +32,8 @@
      quietly changes a value it claims to have measured is worse than one that
      changes it and says so. Pure black is 21:1 on the sheet; this is 17.74:1,
      and both are far above any floor that matters. */
-  --ink: #111827; /* 17.74:1 on --bg */
-  --ink-soft: #4b5563; /* 7.5:1 — secondary copy, safe as body */
+  --ink: #111827; /* 17.15:1 on --bg */
+  --ink-soft: #4b5563; /* 7.31:1 on --bg — secondary copy, safe as body */
   --ink-faint: #9ca3af; /* 2.5:1 — RULES AND MARKS ONLY, never text */
   --on-ink: #ffffff;
 

package/kits/editorial-luxury/src/styles.css

@@ -15,7 +15,7 @@
   --accent-deep: #2f5e47;
   --accent-weak: rgba(63, 125, 95, 0.12); /* tint fill (badges, wash) */
   --accent-med: rgba(63, 125, 95, 0.34); /* hairline / border tint */
-  --accent-ink: #fbf6ec; /* text ON the accent — 6.1:1 on --accent-deep; large text only on --accent */
+  --accent-ink: #fbf6ec; /* text ON the accent — 6.93:1 on --accent-deep; 4.52:1 on --accent, AA by 0.02, so large text only there */
   --accent-on-dark: #9fd9bc;
   --terra: #b5623f;
   --red: #a83a2b;
@@ -51,8 +51,11 @@
   background-color: var(--paper);
   color: var(--ink);
   color-scheme: light;
-}
 
+  /* Core role vocabulary — every pack resolves --bg, --ink and --accent, so a
+     cross-pack document can name them truthfully. Alias, never a new colour. */
+  --bg: var(--paper); /* role alias -> --paper, this pack's field */
+}
 /* ── components ── */
 
 /* Everything below consumes var(--…) only. The token block above is the whole

package/kits/field-notes/src/styles.css

@@ -231,6 +231,12 @@
 
   background-color: var(--bg);
   color: var(--ink);
+
+  /* Core role vocabulary — every pack resolves --bg, --ink and --accent, so a
+     cross-pack document can name them truthfully. Alias, never a new colour. */
+  /* @role accent: --brand — this pack's ONE functional accent. It is not
+     aliased to --accent because that would make it a status peer, and the
+     palette gate measures it 5.5 from --danger (hard floor 10). */
 }
 
 /* The dark twin. Warm, one family, and clean on contrast throughout —

package/kits/instrument-console/src/styles.css

@@ -41,8 +41,11 @@
   background-color: var(--base);
   color: var(--ink);
   color-scheme: dark;
-}
 
+  /* Core role vocabulary — every pack resolves --bg, --ink and --accent, so a
+     cross-pack document can name them truthfully. Alias, never a new colour. */
+  --bg: var(--base); /* role alias -> --base, this pack's field */
+}
 /* ── components ── */
 
 /* Everything below consumes var(--…) only. Colour never appears as a literal.

package/kits/maquette/src/styles.css

@@ -30,7 +30,7 @@
      warm object on a cold page. */
   --ink: #fff9f4; /* 17.49:1 on --bg */
   --ink-soft: #b3b5c1; /* 8.95:1 — secondary copy, comfortably AA */
-  --ink-faint: #8a8f98; /* 5.0:1 — captions and leader lines */
+  --ink-faint: #8a8f98; /* 5.62:1 on --bg — captions and leader lines */
   --on-ink: #151515;
 
   /* ---- Lines ------------------------------------------------------------ */

package/kits/orchard/src/styles.css

@@ -107,6 +107,12 @@
   background-color: var(--bg);
   color: var(--ink);
   color-scheme: light;
+
+  /* Core role vocabulary — every pack resolves --bg, --ink and --accent, so a
+     cross-pack document can name them truthfully. Alias, never a new colour. */
+  /* @role accent: --cta — this pack's ONE functional accent. It is not
+     aliased to --accent because that would make it a status peer, and the
+     palette gate measures it 5.5 from --danger (hard floor 10). */
 }
 
 /* The reference ships NO reduced-motion branch at all. This one is mandatory:
@@ -120,7 +126,6 @@
     --reveal-floor: 1;
   }
 }
-
 /* ── components ── */
 
 /* Everything below consumes var(--…) only. Colour never appears as a literal:

package/kits/showroom/src/styles.css

@@ -25,8 +25,8 @@
 
   /* ---- Ink -------------------------------------------------------------- */
   --ink: #1c1d1f; /* 16.87:1 on --bg */
-  --ink-2: #232529; /* 15.9:1 — secondary headings */
-  --ink-soft: #505967; /* 7.7:1 — captions that must actually be read */
+  --ink-2: #232529; /* 15.35:1 on --bg — secondary headings */
+  --ink-soft: #505967; /* 7.08:1 on --bg — captions that must actually be read */
   --on-ink: #ffffff;
 
   /* [CORRECTION] The reference names #a4adba "caption-foreground" and it

package/kits/workbench/src/styles.css

@@ -11,7 +11,7 @@
   --border-strong: #d7dce4;
   --accent: #2f6feb;
   --accent-weak: #eaf0fe;
-  --accent-ink: #ffffff; /* text ON the accent — 5.0:1 on --accent */
+  --accent-ink: #ffffff; /* text ON the accent — 4.57:1 on --accent */
   --ok: #1a7f37;
   --ok-weak: #e6f4ea;
   --warn: #9a6700;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "sheleg-design-skill",
-  "version": "1.9.0",
+  "version": "1.10.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 twelve locked style packs with ready-made design tokens — instrument-console, editorial-luxury, workbench, briefing-room, atrium, orchard, field-notes, cyclorama, showroom, blueprint, prism and maquette. Colour, slop and fork-reciprocity 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"
@@ -19,12 +19,12 @@
     "node": ">=16"
   },
   "scripts": {
-    "test": "python3 test/validate.py && python3 test/validate_palette.py && python3 test/sloplint.py && node --check bin/cli.js",
+    "test": "python3 test/validate.py && python3 test/validate_palette.py && python3 test/sloplint.py && node --check bin/cli.js && npm run selftest",
     "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"
+    "selftest": "python3 test/validate.py --self-test && python3 test/validate_palette.py --self-test && python3 test/sloplint.py --self-test"
   },
   "keywords": [
     "skill",

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

@@ -1,8 +1,8 @@
 {
   "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.9.0",
+  "description": "SHELEG Design methodology: cinematic scroll-driven landing pages (single scroll clock, layered degrade-to-calm motion, WebGL particle formations), a motion doctrine that decides whether to animate before it decides how, and twelve pluggable visual style packs — instrument-console (dark console), editorial-luxury (warm editorial), workbench (light/dark product UI for dashboards and tools), briefing-room (dark 16:9 deck), atrium (warm consumer health), orchard (friendly consumer biotech), field-notes (warm paper for dev tools sold on auditability), cyclorama (a pastel field on a 32s cycle), showroom (the product as the exhibit), blueprint (a drawing sheet, zero radius), prism (one iridescent wash over mono body), maquette (cream axonometric models on a dark table). Ships the sheleg-design skill, the architecture reference, the motion doctrine, the Figma and Claude Design bridges, AI-surface patterns, style packs with ready-made token CSS, and the /sheleg-design command.",
+  "version": "1.10.0",
   "author": {
     "name": "ssheleg",
     "url": "https://x.com/sshlg93"

package/plugins/sheleg-design/commands/sheleg-design.md

@@ -5,14 +5,30 @@ argument-hint: "[what to build or upgrade]"
 
 Invoke the `sheleg-design` skill and apply it to the current request.
 
-- Read the skill's SKILL.md, then its full reference `SHELEG_DESIGN.md`
-  (same directory) before designing anything.
-- Task: $ARGUMENTS — if empty, ask what page or section to build/upgrade,
-  then proceed per the skill's "How to Apply" order. If the arguments name
-  a style pack (instrument-console | editorial-luxury | workbench), use
-  that pack without re-asking; otherwise pick per the SKILL.md table.
+- Read the skill's `SKILL.md` first, then — **before designing anything** — its
+  full reference `SHELEG_DESIGN.md` and, **before any animation**,
+  `MOTION_DOCTRINE.md` (same directory). `SHELEG_DESIGN.md` says how motion is
+  built; the doctrine says whether to build it at all. Skipping the second is
+  how a keyboard path ends up animated.
+- Task: $ARGUMENTS — if empty, ask what page or section to build/upgrade.
+- **If the arguments name a style pack, use that pack without re-asking.** The
+  twelve are `instrument-console`, `editorial-luxury`, `workbench`,
+  `briefing-room`, `atrium`, `orchard`, `field-notes`, `cyclorama`, `showroom`,
+  `blueprint`, `prism`, `maquette`. Otherwise pick per the `SKILL.md` table,
+  and say which pack you picked and why before you build.
+- **Set the three dials out loud before any layout exists** — `DESIGN_VARIANCE`,
+  `MOTION_INTENSITY`, `VISUAL_DENSITY`, with one line of reasoning. The
+  `SKILL.md` "Reading them off the brief" table gives the starting values;
+  baseline is `7 / 5 / 4`. Announcing them and then drifting is the failure this
+  step exists to prevent.
+- Then proceed per the skill's "How to Apply" order.
 - Product UI (dashboard, admin, internal/dev tool, design tokens, theming):
-  apply `styles/workbench.md` and its token CSS standalone — no scroll
-  clock, no particle field, no cinematic motion.
+  apply a **standalone** pack and its token CSS — no scroll clock, no particle
+  field, no cinematic motion. `workbench` is the default; `field-notes` is the
+  fork for a developer product sold on auditability, and `briefing-room` for a
+  deck published as a page. The packs state the distinction; read it rather than
+  defaulting.
+- AI surfaces (chat, agent runs, streaming, generated content): read
+  `AI_PRODUCT_PATTERNS.md` as well.
 - Follow the skill's non-negotiables (Quick Reference table) and ship every
   layer's reduced-motion/fallback branch in the same commit.

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

@@ -91,12 +91,13 @@ hierarchy, content order. It never answers what it looks like.
 
 ## 5. Live-site extraction — the pack first, the sync second
 
-Three packs in this skill were extracted from production sites by reading their live
+Most packs in this skill were extracted from production sites by reading their live
 computed styles. That is a legitimate way to *make a pack* and never a way to make a
 kit.
 
-**The order is the rule:** extraction lands in a pack first — all nine headings and a
-`tokens/<pack>.css` — and only a pack syncs. A site's raw values never reach
+**The order is the rule:** extraction lands in a pack first — **the full thirteen
+headings** (plus `## Motion flavor` if it is cinematic) and a `tokens/<pack>.css` —
+and only a pack syncs. A site's raw values never reach
 claude.ai/design, because a kit assembled straight from a scrape carries that site's
 accidents, its dead ends and its one-off hexes, and the design agent will treat every
 one of them as a decision.

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

@@ -156,8 +156,16 @@ These are not stylistic preferences. Each one is a defect with a known failure.
 - **State for continuous input** — pointer position, scroll progress, magnetic
   hover, physics. Storing these in `useState` re-renders the tree on every
   movement and collapses on mobile.
-- **Animating anything but `transform`, `opacity`, `filter`, `clip-path`** —
-  `top`, `left`, `width`, `height`, `margin` trigger layout on every frame.
+- **Animating a property that triggers layout** — `top`, `left`, `width`,
+  `height`, `padding`, `margin`, `gap`, `font-size`. These re-lay-out the
+  document on every frame. Animate `transform` and `opacity`, which the
+  compositor handles alone; `filter` and `clip-path` are also safe. Paint-only
+  changes (`background-color`, `border-color`, `color`, `box-shadow`) are
+  cheaper than layout and are permitted — §2 gives them an ease and §9 treats a
+  colour change as the baseline everything else is measured against. The ban is
+  on **layout**, not on everything outside a list of four; an earlier wording
+  said "anything but `transform`, `opacity`, `filter`, `clip-path`", which
+  contradicted both of those sections.
 - **`backdrop-filter` on a scrolling container** — continuous GPU repaint. Blur
   belongs on fixed or sticky elements.
 - **Grain and noise on a scrolling container** — same reason. Put them on a

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

@@ -15,6 +15,15 @@ build new sites on the same principles and understand *why* each piece works.
 > Where a pack's motion tokens differ from the defaults in §10, **the pack
 > wins** — it is the visual contract.
 
+> **Every `**Reference file:**` path below belongs to the reference
+> implementation, not to your project.** `src/lib/motion/scroll-progress.ts` and
+> its siblings do not exist until you write them, and none of them ships with
+> this skill — nothing here is importable. Read the paths as *one file per idea*
+> (the split is the lesson; §13 is the full map) and name them however your
+> framework does. An agent that imports from these paths because the heading
+> looked authoritative will get a build error at best and a silently missing
+> module at worst.
+
 ---
 
 ## 0. The one-paragraph thesis
@@ -81,7 +90,7 @@ file with one responsibility, reading the same clock.
 
 ## 2. Layer 1 — The scroll store (the single clock)
 
-**File:** `src/lib/motion/scroll-progress.ts`
+**Reference file:** `src/lib/motion/scroll-progress.ts`
 
 This is the heart of the system. One `requestAnimationFrame` loop (scheduled on
 the native `scroll` event) measures the page and writes a plain `state` object.
@@ -161,7 +170,7 @@ to you" signal.
 
 ## 3. Layer 2 — Smooth scroll (one position per frame)
 
-**File:** `src/components/motion/SmoothScroll.tsx`
+**Reference file:** `src/components/motion/SmoothScroll.tsx`
 
 Lenis provides inertial scrolling, but the important move is **driving Lenis
 from the GSAP ticker** rather than its own rAF:
@@ -186,7 +195,7 @@ and keep native scroll. The store still runs, so the rail and nav stay in sync.
 
 ## 4. Layer 3 — The particle field (the scene-formation engine)
 
-**File:** `src/components/webgl/SignalField.tsx`
+**Reference file:** `src/components/webgl/SignalField.tsx`
 
 This is the showpiece: 936 points (a `24 × 13` grid × 3 depth layers — a count,
 not a scene index) that narrate the page section by section. It is a single `THREE.Points` cloud whose target positions change
@@ -195,7 +204,7 @@ with the brand accent.
 
 ### 4.1 The scene registry
 
-**File:** `src/lib/motion/scenes.ts`
+**Reference file:** `src/lib/motion/scenes.ts`
 
 Each section "owns" a scene; a scene is a `{ anchor, formation, focusX, energy }`
 record. The registry is the single place that maps DOM sections to particle
@@ -329,7 +338,7 @@ scrubbed scalar, scrolling back up rewinds the whole explosion frame-for-frame.
 
 ## 5. Layer 4 — The 2D fallback (SignalMesh)
 
-**File:** `src/components/atmosphere/SignalMesh.tsx`
+**Reference file:** `src/components/atmosphere/SignalMesh.tsx`
 
 Touch and no-WebGL clients get a canvas mesh: two depth layers of grid nodes
 with hairline links and traveling pulses, plus **stroke overlays** that fade in
@@ -346,7 +355,7 @@ fidelity. Only `prefers-reduced-motion` gets a single static frame.
 
 ## 6. Layer 5 — The projection bridge (fusing DOM and WebGL)
 
-**File:** `src/lib/motion/field-sync.ts`
+**Reference file:** `src/lib/motion/field-sync.ts`
 
 The hardest problem in mixing WebGL particles with DOM labels: the camera moves,
 so you cannot hard-code where a cluster appears on screen. The bridge solves it
@@ -423,7 +432,7 @@ React renders. Act markers deep-link to their anchor sections and use the coarse
 
 ## 8. Layer 7 — Reveal primitives (act-themed entrances)
 
-**File:** `src/components/design/Reveal.tsx`
+**Reference file:** `src/components/design/Reveal.tsx`
 
 Entrances are not generic. Each narrative act has a reveal whose *physics* match
 its meaning — this is Disney's "staging" applied to a scroll page: