sheleg-design-skill 1.58.4 → 1.59.0

package/CHANGELOG.md

@@ -1,5 +1,49 @@
 ## [Unreleased]
 
+## [1.59.0] - 2026-09-03
+
+### Added
+
+- **`CREATIVE_DIRECTOR.md` — the decision layer, and it is now the skill's first
+  act.** Everything else in this bundle is a craft reference. This is what says
+  which craft, whose tools, and how anyone would know it worked. It exists because
+  the failure mode of an agent doing design is not ugliness but **plausibility**: a
+  page that looks like a design, answers no stated need, was built with whatever
+  skill happened to fire first, and cannot be argued with because nobody wrote down
+  what it was supposed to do.
+
+  Five acts. **Act 1** is a four-line brief whose fourth line is a **falsifier** —
+  what would prove this design failed, stated so it could actually happen — plus
+  the mode table, where a redesign enters at `verify` and `a11y` because you
+  measure the thing you are replacing before you take it away, and an update
+  changes a token rather than the components that read it. **Act 2** casts the
+  tools by MEASURING with `npx sshlg-skills pack design --lane <lane>` rather than
+  recalling, and prints the cast before starting. **Act 3** runs two variations in
+  parallel subagents with disjoint casts — under the rule that keeps it honest,
+  which is that **the rubric is written before either variation exists**; build two
+  and then decide what you were comparing and you have picked the one you liked and
+  written the justification backwards. It also names when NOT to fork, because two
+  variations of a spacing fix is theatre. **Act 4** grafts what the loser did
+  better and records which tool produced which trait, so the next casting decision
+  is better than this one. **Act 5** splits validation into alignment (does it
+  answer the brief) and quality (eight measurable checks, each producing a number a
+  second reader can reproduce) — and states the limit rather than implying it:
+  **taste is not on that table**, and where two directions both pass, that is a
+  person's decision and the honest output is the pair plus the trade-off.
+
+- The director is held by the validator like every other companion: it ships in the
+  bundle, is linked from `SKILL.md`, is mirrored into `.cursor/`, and carries a
+  derived `## Contents` list. **Its absence would otherwise be invisible** — the
+  craft references still read fine on their own, which is exactly why the layer
+  above them has to be held mechanically.
+
+- Three findings from this repository's own gate, all real: the bundle file list in
+  `install.sh` did not carry the new file, the derived contents list was missing,
+  and the draft cited a repository path (`docs/ux/…`) that dead-ends for every
+  reader who installed the bundle rather than cloning the repo. The last one is
+  reworded to point at `/ux` instead.
+
+
 ## [1.58.4] - 2026-09-03
 
 ### Fixed

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "sheleg-design-skill",
-  "version": "1.58.4",
+  "version": "1.59.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 thirty-nine locked style packs with ready-made design tokens — instrument-console, editorial-luxury, workbench, briefing-room, atrium, orchard, outrank, babylove, patchbay, nameplate, field-notes, cyclorama, showroom, blueprint, prism, maquette, scoreboard, datasheet, manpage, pigeonhole, roster, ora, tenor, paperclip, ledger, router, daylight, notation, almanac, vitrine, proscenium, awning, bulletin, rimlight, onionskin, deskmate, test-drive, surveyor and chorus. 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"

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

@@ -3,7 +3,7 @@
   "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), a motion doctrine that decides whether to animate before it decides how, and thirty-nine pluggable visual style packs, each with a ready-made token layer — instrument-console (near-black aerospace console; technical systems and infrastructure), editorial-luxury (cream and espresso; editorial, research, premium B2B), workbench (quiet light/dark UI; dashboards, admin, internal tools), briefing-room (dark 16:9 deck; investor and board presentations), atrium (cream daylight; consumer health and high-trust DTC), babylove (white with orange; SEO SaaS, long time-to-value, disconnected states), patchbay (black with mint-cyan; engines, buses, pipelines, OSS front doors), nameplate (cool slab with coral; press, certification and third-party trust), rimlight (white with blue light; studios, services and case studies), onionskin (white working sheet; developer and AI infrastructure), deskmate (warm beige with a dusk bleed; AI coworkers and chat-native agents), test-drive (warm paper with one coral; self-serve SaaS proven by the live product), surveyor (peach paper with teal and pink; visibility, monitoring and benchmark tools), chorus (warm paper under a crosshair grid, with a cut-corner bubble; AI-search visibility, brand monitoring and community marketing), outrank (white with violet; one brand across marketing and product), orchard (warm oat slabs; friendly biotech and wellness), field-notes (ruled green paper; auditable open-source developer tools), showroom (white gallery; product-led companies selling the app), blueprint (white technical stock; vector, storage and query infrastructure), prism (iridescent hard edge; command-first OSS infrastructure), maquette (near-black table; enterprise data infrastructure), cyclorama (looping pastel field; applied-AI consultancies), scoreboard (warm paper; growth, ads and accumulating metrics), datasheet (off-white specification; fraud, identity and device intelligence), manpage (cream manual; APIs, SDKs, CLIs and MCP servers), pigeonhole (filed white field; inbox, ticket and CRM triage), roster (faint square grid; platforms sold through who uses them), ora (warm coal; machine verdicts, audits and protocol traces), tenor (warm management paper; agent operations and autonomous back office), ledger (cream ruled console; analysts, BI and warehouse agents), paperclip (monochrome coal; orchestrators, schedulers and job runners), awning (white commerce forecourt; storefront, payroll and billing platforms), router (pale console with hairlines; dashboard, billing and inventory surfaces), daylight (bright portal with one shadow; client onboarding and service portals), notation (restrained technical hairlines; OSS, docs and developer workspaces), almanac (oatmeal editorial paper; manifestos and category-defining pages), vitrine (serif trust display; evaluated B2B, security and compliance), proscenium (white demo sequence; product tours and launch pages), bulletin (cheerful outlined bands; broad SMB and agency platforms). Ships the sheleg-design skill, the architecture reference, the motion doctrine, the Figma and Claude Design bridges, AI-surface patterns, the packs' token CSS, and the /sheleg-design command.",
-  "version": "1.58.4",
+  "version": "1.59.0",
   "author": {
     "name": "ssheleg",
     "url": "https://x.com/sshlg93"

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

@@ -0,0 +1,239 @@
+# Creative Director — the first act, before any pixel
+
+This is what `/sheleg-design` opens with. Everything else in this bundle is a
+craft reference; this is the decision layer that says **which craft, whose tools,
+and how you will know it worked**.
+
+It exists because the failure mode of an agent doing design is not ugliness. It
+is *plausibility*: a page that looks like a design, answers no stated need, was
+built with whatever skill happened to fire first, and cannot be argued with
+because nobody wrote down what it was supposed to do. Five acts, in order. Act 1
+and Act 5 are the two that are usually skipped, and they are the two that make
+the middle three worth doing.
+
+---
+
+## Contents
+
+- Act 1 — The brief, and the sentence that could falsify it
+- Act 2 — Cast the tools, by measuring rather than recalling
+- Act 3 — Fork, but only when the fork is real — and write the rubric first
+- Act 4 — Judge, then graft, then record what the cast produced
+- Act 5 — Validate: alignment first, then quality
+- The output the director owes
+
+## Act 1 — The brief, and the sentence that could falsify it
+
+**Nothing is designed until this exists in writing.** Four lines, and the fourth
+is the one that costs something:
+
+| | |
+|---|---|
+| **Surface** | landing / hero, product UI, mobile screen, agent interface, deck-as-page |
+| **Job** | what the person who lands here must be able to do, in their words |
+| **Constraint** | the thing that is not negotiable — a brand, a stack, a deadline, an existing system |
+| **Falsifier** | **what would prove this design failed**, stated so that it could actually happen |
+
+A falsifier is not "it looks bad". It is *"a first-time visitor cannot say what
+this product does after five seconds"*, *"the primary action is below the fold on
+a 13-inch laptop"*, *"the dashboard's densest table needs horizontal scrolling at
+1280px"*. If you cannot write one, the brief is a mood and the rest of this
+document cannot help you.
+
+**Where the brief comes from, in order of preference.** If `super-ux` is
+installed and the project keeps a UX scenario base — `/ux` reports whether it
+does and where — the Job line is **traced to a scenario id**, not invented, and a
+design that answers no scenario is the first finding, before any visual work. No
+scenario base: offer `/ux` once, then proceed with the brief written here and say
+plainly that it is unvalidated.
+
+**Mode changes where you enter, and it is not cosmetic.**
+
+| Mode | Enters at | Why |
+|---|---|---|
+| **New design** | `style` | there is nothing to measure yet; the direction is the first commitment |
+| **Redesign** | `verify` + `a11y` **first** | you are replacing something that works for somebody. Measure it before you take it away, or you will re-ship its defects and lose its accidents |
+| **Update** | `tokens` | change the token, not the components that read it. An update that edits components is a redesign wearing a smaller word |
+| **Audit** | `a11y` → `verify` → `speed` | nothing is redrawn until all three have spoken |
+
+The redesign row is the one people get wrong. **A redesign starts with a
+measurement of the thing being replaced** — contrast, keyboard path, what the
+current page actually does on the target viewport — because half of "the old one
+was bad" turns out to be "the old one handled a case I have not thought about".
+
+---
+
+## Act 2 — Cast the tools, by measuring rather than recalling
+
+The director does not choose from memory. On a typical machine this pack is a
+small fraction of what is installed, and most of it is invisible to a router that
+only knows its own roster.
+
+```bash
+npx sshlg-skills pack design --lane <style|brand-surface|product-surface|motion|tokens|figma|implement|mobile|verify|a11y|handoff>
+```
+
+That prints, for the lane you named: what is **present** here, what is
+**missing** with the exact install command, and which of them have been
+**measured and declined**. It reports and never installs.
+
+**Then print the cast before starting** — the skills you will use, one line each
+saying what for, and the lane each serves. Not for approval; so the operator can
+see the choice and correct it. A cast that is never printed cannot be corrected,
+and an agent that silently reached for the first skill that fired has made a
+decision nobody can audit.
+
+**The three lanes with no owner in this family are the ones to check hardest** —
+implementation, verification and **accessibility**. Nothing here asks whether the
+interface can be used at all; that lane is delegated, and delegation only works
+if somebody actually casts for it.
+
+**Ours versus theirs is not a loyalty question.** Where an outside skill answers
+the lane better, cast it. The one rule that does not bend: **this skill decides
+the route, and everything cast is a tool inside a lane — never a second entry
+point.** Some of them advertise themselves as one; a broad `user-invocable`
+design skill will fire on the same prompt you did. That is not a reason to avoid
+it. It is a reason to say, out loud, which one is directing.
+
+---
+
+## Act 3 — Fork, but only when the fork is real — and write the rubric first
+
+Two variations built by two subagents with **different casts** is the strongest
+move in this document and the easiest one to turn into theatre.
+
+### The rule that makes it honest
+
+**The rubric is written before either variation is made, and it is not touched
+afterwards.** If you build two and then decide what you were comparing, you have
+not run a comparison — you have picked the one you liked and written the
+justification backwards. Three to five criteria, each one *checkable by someone
+who did not build either variation*, and each one traceable to the brief's Job or
+Falsifier.
+
+A usable rubric line looks like *"the primary action is reachable without
+scrolling at 1280×800"* or *"the type scale uses at most five distinct sizes"* —
+not *"feels more premium"*.
+
+### When to fork
+
+Fork when **all three** hold:
+
+1. the lane has both a credible family answer and a credible outside one,
+2. the brief is genuinely under-determined — two defensible directions exist,
+3. the surface is worth it: a landing page, a hero, a product's main screen, a
+   visual language being set for the first time.
+
+### When NOT to fork
+
+A token change. A spacing fix. A bug. A surface with a locked design system,
+where the answer is *apply the system* and two variations are two ways of
+disobeying it. Anything where the brief already determines the answer — forking
+there does not explore a space, it manufactures a choice and then spends someone's
+attention resolving it.
+
+### How to run it
+
+Two subagents, launched together, each given:
+
+- the **same** brief from Act 1, verbatim,
+- the **same** rubric, verbatim,
+- **its own cast, declared and disjoint** — variation A on this pack's style pack
+  and doctrine; variation B on the outside skills cast in Act 2,
+- an instruction to produce a **working surface**, not a description of one,
+- **no knowledge of the other variation.** They must not read each other's output,
+  or the second one converges on the first and the comparison collapses.
+
+Name the casts in the output. *"A: workbench + MOTION_DOCTRINE. B: impeccable
+product mode + vercel-composition-patterns"* is a record that makes the next
+casting decision better; *"two options"* is not.
+
+---
+
+## Act 4 — Judge, then graft, then record what the cast produced
+
+Score both against the rubric written in Act 3. Then do the two things a bare
+verdict skips:
+
+**Graft.** Name the specific thing the losing variation did better and carry it
+into the winner. A fork that discards half its own output wasted half its cost.
+If the loser had nothing worth carrying, say so — that is a real finding about
+the cast, not a formality.
+
+**Record which tool produced which trait.** *"B's type scale was tighter and came
+from its font-pairing data; A's motion degraded correctly and B's did not"* is
+the sentence that makes the next run's Act 2 sharper. Without it, every fork
+starts from the same ignorance as the first one.
+
+**Where the two variations are equally defensible, say so and stop.** Two
+credible directions is a decision for a person, and a director that manufactures
+a preference to look decisive is worse than one that hands over a clean choice
+with the trade-off named.
+
+---
+
+## Act 5 — Validate: alignment first, then quality
+
+Two different questions, and passing one says nothing about the other.
+
+### Alignment — does this answer the brief?
+
+- Every element on the surface traces to the **Job**, or is deliberate decoration
+  and named as such. An element that traces to neither is the first thing to cut.
+- The **Falsifier** is checked, out loud. If it is now true, the design failed
+  and no amount of craft in the middle acts changes that.
+- Where scenarios exist, the surface is checked against them — `/ux-audit` does
+  this with `file:line` evidence, and it is the only alignment check here that is
+  mechanical.
+
+### Quality — the measurable half
+
+These are checks, not opinions. Each one produces a number or a yes/no that a
+second reader can reproduce:
+
+| Check | How it is measured |
+|---|---|
+| Contrast | every text/background pair against WCAG AA; body text ≥ 4.5:1, large ≥ 3:1 — a **computed ratio**, never a glance |
+| Colour is not the only signal | every status, link and error state carries a second cue — shape, icon, weight, text |
+| Keyboard path | every interactive element reachable and visibly focused, in DOM order |
+| One anchor per viewport | count what competes for first attention; more than one means none |
+| Type scale | count the distinct font sizes actually rendered — an ad-hoc scale shows up as a long tail |
+| Token discipline | `grep` for raw hex and raw px outside the token layer; a one-off value is a system leaking |
+| Motion, and its absence | every duration inside the doctrine's bands, and the surface fully usable under `prefers-reduced-motion: reduce` — checked by turning it on, not by reading the CSS |
+| Renders without JS | the content is present in the served HTML — matters for the reader who is a crawler as much as for the one on a slow connection |
+
+**Run them where the thing runs.** A screenshot in a browser at the target
+viewport beats reading the diff, every time; `webapp-testing` and the Chrome
+DevTools tooling exist for this, and the `verify` lane in Act 2 casts them. A
+quality claim made from source is a claim about source.
+
+### The limit, stated rather than implied
+
+**Taste is not on that table, and this document will not pretend otherwise.**
+These checks catch defects and enforce a system. They cannot tell you whether the
+result is *good* — and a director that reports "all gates green" as if it meant
+"this is good design" has substituted the measurable half for the whole. Say
+which half you checked. Where two directions both pass, that is the moment a
+person decides, and the honest output is the pair plus the trade-off, not a
+manufactured winner.
+
+---
+
+## The output the director owes
+
+One short record, every time, whether the work took ten minutes or a day:
+
+```
+Brief      surface / job / constraint / falsifier      (+ scenario id where one exists)
+Mode       new | redesign | update | audit             → entered at <lane>
+Cast       <skill> — <what for>, per lane              (measured with `pack design`)
+Fork       yes → rubric (written first), A: <cast>, B: <cast>, winner + what was grafted
+           no  → why not
+Alignment  falsifier checked: <result>
+Quality    the table above, with numbers
+Open       what a person still has to decide
+```
+
+**`Open` is not an admission of failure.** It is the line that separates a
+director from a generator: the generator returns something finished-looking with
+nothing left to decide, and every real design job has something left to decide.

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

@@ -4,7 +4,7 @@ description: Use when deciding how something LOOKS or MOVES — cinematic landin
 license: MIT
 compatibility: Optional siblings — dataviz, shadcn, migrate-radix-to-base; each has an in-text fallback when absent.
 metadata:
-  version: 1.58.4
+  version: 1.59.0
 ---
 
 # SHELEG Design
@@ -17,6 +17,19 @@ independently-degradable responses**. Centralize scroll into one store; layers
 read it per frame and react in their own language. Nothing crossfades — things
 *redeploy*. Every layer degrades to a calm static state.
 
+**READ FIRST, BEFORE ANY OF THE CRAFT BELOW:**
+[`CREATIVE_DIRECTOR.md`](./CREATIVE_DIRECTOR.md) — the decision layer. What the
+surface is for and **what would prove it failed**; which lane and which mode the
+task is in, because a redesign starts by measuring the thing it replaces and an
+update changes a token rather than the components that read it; which tools to
+cast, measured with `npx sshlg-skills pack design --lane <lane>` rather than
+recalled; when to build **two variations with two disjoint casts in parallel
+subagents** — and the rule that keeps that honest, which is that the rubric is
+written before either one exists; and the validation split that matters, where
+alignment to the brief and measurable quality are two different questions and
+neither implies the other. **The failure mode of an agent doing design is not
+ugliness, it is plausibility**, and that document is what refuses it.
+
 **REQUIRED REFERENCE — for the cinematic path:** read
 [`SHELEG_DESIGN.md`](./SHELEG_DESIGN.md) before implementing a scroll-driven page —
 architecture, morph math, the DOM↔WebGL bridge, the build recipe (§11), the file map.