sheleg-design-skill 1.62.0 → 1.63.0

package/CHANGELOG.md

@@ -1,3 +1,96 @@
+## 1.63.0 — the director record is a file with a validator, and a flagship is scored on a rubric that says where it came from
+
+The director's output was a prose block at the end of `CREATIVE_DIRECTOR.md`: nothing
+held it, so a brief with no falsifier, a taste of "modern, clean", a fork judged by a
+rubric written afterwards and a `Markers` line nobody ran all passed as a record. The
+plan's pipeline (contracts K3, K6, K7) needs a record the next stage can check, and a
+quality bar for flagship surfaces that is more than the measurable table.
+
+- **D3 — `templates/director-record.md` and `npx sheleg-design-skill --check-record
+  <file> [--json]`.** A header with `surface_class` (`flagship`, `product`,
+  `internal`, `ad`) and sixteen `## <Field>` headings: Brief, Mode, Taste, References,
+  Cast, Fork, Rubric, Critique, Markers, Alignment, Quality, Signature, Surfaces,
+  Haptics, ADA, Open. A flagship owes all sixteen; a product screen Brief, Mode,
+  References, Markers, Open; an internal tool Brief, Mode, Markers, Open; an ad Brief,
+  Mode, Taste, References, Markers, Signature, ADA, Open. Each owed field is held to
+  its rule: Brief needs Surface, Job, Constraint and Falsifier; Taste needs `Take:` and
+  `Ban:` lines with something other than generic words (English and Russian); References
+  needs five real-product URLs each with `take:`, or `none found` with `Searched:`;
+  `Fork: yes` needs a Rubric section it names, `A:`/`B:` and a `Winner:`; Rubric three
+  criteria; Critique region → defect → change triples or `clean render`; Markers a
+  `--lint` run with its revision and counts, and no S1; Signature exactly one moment
+  with What/Where/Why; ADA the class profile, every G item passing, at most two J FAIL
+  on a flagship, no J PASS without a `Labelled set:`, safe zones on an ad. Guidance
+  lives in HTML comments, so a copied template fails until it is filled. `Mode:
+  declined` with its reason passes on its own. Exit 0 valid, 1 violations as
+  `<Field>: <problem>`, 2 usage. `bin/record.js`, Node, no dependencies; its rules
+  join `--self-test`. The prose block in `CREATIVE_DIRECTOR.md` is replaced by a
+  pointer to both, keeping the doctrine on `Open`.
+- **K6 — `ADA_RUBRIC.md`.** R1–R25, each binary, typed G (a gate no judge outvotes),
+  J (a judge on a per-task checklist) or H (the human on the contact sheet), with
+  applicability and how to verify (tool → artifact). Profiles: flagship all 25, every
+  G PASS and at most two J FAIL with reasons; product the G items R1, R3–R5, R8, R9,
+  R12–R17, R19, R20, R22; ad R7, R8, R10, R11, R14, R18, R21, R22 plus safe zones. The
+  judge: a checklist per task, pairwise only against an approved reference in both
+  orders, three samples, disagreement `uncertain` to the human, J items NOT_ASSESSED
+  until a labelled set exists, never above a G-FAIL, and never the agent that
+  rendered the surface. Every FAIL is a triple. **The file says plainly that the
+  rubric is derived and Apple publishes none**, and cites Apple's award pages with
+  the date they were read. Linked from Act 5 and `SKILL.md`.
+- **D4 — the reference sweep is mandatory** for a new design and a redesign of a brand
+  or flagship surface (Act 2, `APPLYING.md`, `SKILL.md`), through whichever reference
+  servers the session exposes — Refero, Lazyweb, Mobbin where authorized — with an
+  empty result recorded as `none found` and where it looked.
+- **First time right**, a new section of `CREATIVE_DIRECTOR.md`: decisions before
+  pixels in the record; the forbidden list loaded into context and the linter run;
+  one key screen in one state first; feedback only external and specific; a
+  re-render budget of one, at most two, then `unresolved` to the person; the
+  generator is not the judge.
+- **D5 — `MOTION_DOCTRINE.md` §12, reviewing motion:** a frame strip and a run video,
+  timings judged by one `DUR-*` row each, reduced motion turned on and captured again,
+  one moment per viewport; `npx hyperframes snapshot` / `compare` as the evidence for a
+  rendered file (compare is a review surface, not a gate); `review-animations` by name.
+  It feeds the record's Quality and Critique.
+- **D6 — `FIGMA_BRIDGE.md` §3 re-drawn.** "Motion stays in code — Figma has no easing
+  variable type" was no longer true: the official Figma plugin (2.2.120) documents
+  TIMING and EASING variables, keyframes, animation styles and `get_motion_context`
+  snippets. Durations and curves can now be published; motion read back is held to
+  the doctrine (Figma's `EASE_IN`, `…_BACK` and `BOUNCY` are banned forms in UI); the
+  scroll clock, scrubbed motion and the reduced-motion branch stay in code. Read from
+  the plugin's documentation, not confirmed by a call (B-144). New §5: a frame is
+  critiqued — `get_screenshot`, the record's rubric, triples, `get_variable_defs` —
+  before anyone approves it; and one Figma file per surface (App / Web / ASO). README,
+  the Cursor rule and `DESIGN_SYNC_BRIDGE.md` follow.
+- **D10 — the taste profile** is the record's `Taste` field and a guide in the template
+  (what we take, what we ban, anti-patterns, the three dials); Act 1 writes it beside
+  the brief. A profile of "modern / clean" is empty. A personal profile's content stays
+  with its owner.
+- **`MOBILE_SURFACES.md`, the axes matrix:** states × viewport × theme × text size ×
+  locale, pairwise coverage plus the mandatory pairs dark × largest text and RTL ×
+  narrowest viewport, a capture record per cell, the commands that set each axis; the
+  native state matrix is its native case, and a web render still proves no native cell.
+- **D8 — `evals/render/`:** four fixed briefs (landing hero with motion, mobile
+  onboarding, product dashboard, paywall) and a runner that counts linter findings by
+  severity, validates each director record, and scores the G items source can decide
+  (R8, R20, R24), reporting the rest NOT_RUN; `--write` appends a dated row to
+  `test/evals/RESULTS.md`, whose new section states the method. The model generation
+  step is NOT_RUN in CI; the harness row on the hand-written sample is recorded as
+  such (B-142).
+- **B-140 — the kits obey their own floor.** `workbench`'s progress fill slides by a
+  translate instead of transitioning `width`, `paperclip`'s lane mark grows by a scale
+  instead of `width`/`height`, both rendered before and after with the same geometry;
+  `deskmate`'s gradient word carries its waiver and reason. `node bin/cli.js --lint
+  kits` runs in `npm test` and in CI: 0 S1.
+- **Provenance:** a new table for sources with no commit to pin — Apple's award pages,
+  the judge papers, the Figma plugin's motion skills and the HyperFrames CLI skill,
+  each `derived`, dated, with SHA256 where a file was read.
+- **Gates:** `test/record_test.js` (49 cases through the real CLI, every rule watched
+  failing on one planted defect before `bin/record.js` existed); `validate_director_record()`
+  and `validate_ada_rubric()` with three plants; `test/render_eval_test.js` on the sample.
+
+The `SKILL.md` body is 4747/4750 tokens: the new load-on-demand line was paid for by
+tightening the READ FIRST paragraph and the references section.
+
 ## 1.62.0 — a visual floor with reasons and exceptions, and a linter that reads a project against it
 
 Generated design kept shipping through reviews that had nothing to point at.

package/README.md

@@ -176,6 +176,8 @@ 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 |
 | `SURFACE_COMPOSITION.md` | Two decisions the pack layer does not make: the six depth layers of a scene, read before writing CSS for a cinematic page; and the handoff to `dataviz`, read before drawing a chart in any pack — token names are not uniform across the thirteen and an undefined custom property fails silently |
 | `SLOP_MARKERS.md` | The visual floor: 49 markers of generated design (purple gradients, emoji as icons, default faces, the side stripe, the three default looks, banned motion forms…), each with severity, reason, what to do instead and the exception under which it is not slop. Holds with or without a pack; twenty of them are checked by `--lint` |
+| `ADA_RUBRIC.md` | 25 binary checks derived from the Apple Design Awards categories (Apple publishes no rubric; the file says so and cites the pages it read), each typed as a deterministic gate, a judged item or a human one, with profiles for flagship, product and ad surfaces and the rules that keep a model judge honest |
+| `templates/director-record.md` | The director record: one `## <Field>` per decision — brief, taste, references, fork and rubric, critique, markers, signature moment, ADA verdict, what is left open — filled before the first render and checked by `--check-record` |
 | `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 |
 | `MOTION_PRODUCTION.md` | What changes when motion leaves the page as a file: the four things a rendered asset gives up, the two programmatic-video tools measured side by side with the licence threshold and the pre-1.0 risk stated, which one this library recommends and the three conditions that reverse it, how a pack's token layer crosses the render seam, and where the reduced-motion obligation lands once there is no user to read a media query |
 | `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 |
@@ -208,6 +210,25 @@ reason is required. `--self-test` plants a defect for every rule. It is a patter
 reader, not a renderer: the catalogue's `review` rows stay with the render
 critique.
 
+### Check a director record
+
+```bash
+npx sheleg-design-skill --check-record docs/design/pricing/director-record.md
+npx sheleg-design-skill --check-record docs/design/pricing/director-record.md --json
+```
+
+A design's decisions live in a record before the first pixel: a header with
+`surface_class` (`flagship`, `product`, `internal` or `ad`) and one `## <Field>`
+per decision, from the template in the installed skill. The class decides which
+fields are owed — a flagship all sixteen, a product screen Brief, Mode,
+References, Markers and Open — and each owed field is held to its rule, not just
+its presence: a taste profile of "modern, clean" is empty, five references on
+placeholder hosts are none, `Fork: yes` with no rubric compared nothing,
+`Markers` must cite a `--lint` run with its revision and counts, and a flagship's
+ADA verdict fails on any G item. A refusal is a record too: `Mode: declined` with
+its reason passes. Exit 0 valid, 1 with each violation as `<Field>: <problem>`,
+2 a usage error.
+
 ## What you get out of it
 
 - **A motion methodology, not a component dump.** Scroll-linked animation,
@@ -255,9 +276,10 @@ values *onto* the pack's tokens instead of inlining hexes.
 The bridge is specific because the traps are: `workbench`'s light and dark are
 two **modes of one collection**, while `editorial-luxury`'s espresso sections
 are surfaces and not a mode at all; Figma colors are 0..1 floats, not hex; and
-motion never crosses — Figma has no easing variable type, so the ease, durations
-and stagger stay code-only, and shadows are effect styles whose parts bind to
-variables. A value in a file with no matching token is either a gap in the pack
+motion crosses only in part — durations and curves publish as Figma's TIMING and
+EASING variables, but the scroll clock, scrubbed motion and the reduced-motion branch
+stay code-only, and motion read back from a file is held to the doctrine — and
+shadows are effect styles whose parts bind to variables. A value in a file with no matching token is either a gap in the pack
 or drift in the file — the one thing it is never is a literal in a component.
 
 ## Claude Design, in one direction
@@ -283,18 +305,22 @@ stops an agent inventing motion to fill the silence.
 The kits are not part of the install. `--kit` fetches one on demand, which is how
 the skill stays documentation while still having real components to hand.
 
-## Optional: Lazyweb MCP
+## Reference sweeps (Refero, Lazyweb, Mobbin)
 
 A style pack locks *how it looks*. It says nothing about what a good version of
-the screen you're about to build actually **contains**. If the
-[Lazyweb](https://www.lazyweb.com) MCP server is connected, the skill sweeps
-real-world references for the target screen (signup, onboarding, paywall,
-pricing, checkout, dashboard, settings) before laying anything out.
+the screen you're about to build actually **contains**. For a new design or a
+redesign of a brand or flagship surface the sweep is not optional: through
+whichever reference servers are connected — Refero, [Lazyweb](https://www.lazyweb.com),
+Mobbin where the account is authorized — the skill looks at five or more shipped
+products for the target screen (signup, onboarding, paywall, pricing, checkout,
+dashboard, settings) before laying anything out, and records what it takes from
+each. An empty sweep is recorded as `none found` with where it looked.
 
 The division of labor keeps the result one system: references inform **layout,
 hierarchy and content order**; palette, type and motion stay the pack's. Setup
 is a Streamable HTTP MCP server plus a per-user token — keep it out of your
-repo. Entirely optional; without it the skill works from the pack alone.
+repo. Without any reference server the sweep runs on the open web, and the
+record says the servers were absent.
 
 ## Development
 
@@ -317,6 +343,9 @@ third of the contract:
 | `node --check bin/cli.js` | the installer parses |
 | `node test/installer_test.js` | both installers against throwaway HOMEs, above all the refusal to shadow an installed plugin |
 | `node test/lint_test.js` | the project linter end to end: every S1 rule blocks on its plant, every quiet case stays quiet, the ratchet and the exit contract; `--self-test` checks the catalogue against the rules |
+| `node test/record_test.js` | the director-record validator end to end: a valid record for every surface class and a declined one pass; one planted defect per rule fails, each on its own field |
+| `node test/render_eval_test.js` | the render eval runner (`evals/render/`) on the committed hand-written sample: every count it must report |
+| `node bin/cli.js --lint kits` | the reference kits obey the floor they ship with: no S1 marker in any kit |
 
 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

package/bin/cli.js

@@ -160,6 +160,7 @@ function parseArgs(argv) {
     ratchet: null, // --ratchet <budget.json>: per-file budgets that only fall
     includeTests: false, // --include-tests: lint test files and fixtures too
     selfTest: false, // --self-test: every lint rule against its planted defect
+    checkRecord: null, // --check-record <file>: validate a director record (bin/record.js)
     error: null, // set → print help and exit non-zero
   };
   const seen = [];
@@ -205,6 +206,10 @@ function parseArgs(argv) {
       const value = a === "--ratchet" ? argv[++i] : a.slice("--ratchet=".length);
       if (!value || value.startsWith("-")) opts.error = "--ratchet needs a budget file";
       else opts.ratchet = value;
+    } else if (a === "--check-record" || a.startsWith("--check-record=")) {
+      const value = a === "--check-record" ? argv[++i] : a.slice("--check-record=".length);
+      if (!value || value.startsWith("-")) opts.error = "--check-record needs a director-record file";
+      else opts.checkRecord = value;
     } else if (a === "--json") opts.json = true;
     else if (a === "--include-tests") opts.includeTests = true;
     else if (a === "--self-test") opts.selfTest = true;
@@ -221,6 +226,16 @@ function parseArgs(argv) {
     opts.error = "--self-test runs on its own";
     return opts;
   }
+  // The record validator reads one file and writes nothing; --json is the only
+  // flag it takes, and it does not run beside the linter or an install.
+  if (opts.checkRecord) {
+    const other = seen.find((x) => x !== "--check-record" && x !== "--json");
+    if (other) {
+      opts.error = `--check-record reads one record and takes only --json — ${other} does not combine with it`;
+      return opts;
+    }
+    return opts;
+  }
   if (!opts.lint && seen.some((x) => LINT_ONLY.includes(x))) {
     opts.error = `${seen.find((x) => LINT_ONLY.includes(x))} is only meaningful with --lint <dir>`;
     return opts;
@@ -328,11 +343,20 @@ ${c("bold", "Project linter")}
                         also counts raw palette classes and hex outside tokens
   --include-tests       Read tests and fixtures too (skipped by default)
   --self-test           Every rule against its planted defect, and the
-                        catalogue against the rules
+                        catalogue against the rules (the record rules too)
 
   Exit: 0 no S1 finding, 1 an S1 finding or a file over budget, 2 usage error.
   S2 and S3 findings print and do not change the exit code.
 
+${c("bold", "Director record")}
+  --check-record <file> Validate a director record (templates/director-record.md
+                        in the installed skill): the fields its surface_class
+                        owes are present and filled by their rules
+  --json                The verdict as {valid, surface_class, violations[]}
+
+  Exit: 0 valid (a declined record with its reason included), 1 violations,
+  each listed as <Field>: <problem>, 2 usage error.
+
 ${c("bold", "Default")}
   Auto-detects: uses .cursor/ if present, else .claude/ if present,
   otherwise creates .cursor/skills/${SKILL_SLUG}/.
@@ -589,15 +613,28 @@ function main() {
     return;
   }
 
+  if (opts.checkRecord) {
+    const record = require("./record.js");
+    const io = { out: (l) => console.log(l), err: (l) => console.error(l) };
+    process.exitCode = record.runCheckRecord({ file: opts.checkRecord, json: opts.json }, io);
+    return;
+  }
+
   if (opts.selfTest || opts.lint) {
     const lint = require("./lint.js");
     const io = { out: (l) => console.log(l), err: (l) => console.error(l) };
-    process.exitCode = opts.selfTest
-      ? lint.selfTest(io.out)
-      : lint.runLint(
-          { dir: opts.lint, json: opts.json, ratchet: opts.ratchet, includeTests: opts.includeTests },
-          io,
-        );
+    if (opts.selfTest) {
+      // Both validators answer for themselves; either failing fails the run.
+      const record = require("./record.js");
+      const a = lint.selfTest(io.out);
+      const b = record.selfTest(io.out);
+      process.exitCode = a || b ? 1 : 0;
+    } else {
+      process.exitCode = lint.runLint(
+        { dir: opts.lint, json: opts.json, ratchet: opts.ratchet, includeTests: opts.includeTests },
+        io,
+      );
+    }
     return;
   }