sheleg-design-skill 1.61.2 → 1.62.0

package/CHANGELOG.md

@@ -1,3 +1,107 @@
+## 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.
+`CREATIVE_DIRECTOR.md` had refused impeccable's fixed style bans, rightly, because a
+ban that cannot lose an argument contradicts "an explicit user requirement beats the
+baseline"; what it left was no floor at all. Two private production codebases read
+on 2026-10-07 carried emoji standing in for icons, overshoot curves, a side-stripe
+alert card and layout-property transitions, all found by audits after the fact.
+
+- **`SLOP_MARKERS.md`, the visual floor (catalogue version 2026-10-07).** 49 markers
+  `V001`–`V049` in eight groups (color, type, layout, icon-decor, content, motion,
+  mobile, platform), each with severity S1–S3, the tell, why it reads as a default,
+  what a designer does instead, how it is checked, the exception under which it is
+  not slop, and a commit-pinned or dated source. The floor holds with `Style pack:
+  none`; a pack may tighten it and never loosen it; a brief that asks for a marked
+  pattern wins once the director record names the marker. The three default looks
+  are markers V012, V013 and V026, and the `SHELEG_DESIGN.md` section now points
+  there. Copy tells stay with `copywriting`; no punctuation rule is adopted (in
+  Russian the em dash is normative).
+- **`npx sheleg-design-skill --lint <dir> [--json] [--ratchet <budget.json>]
+  [--include-tests]`.** Twenty rules, one per `lint:` row: purple gradients,
+  gradient text, decorative glass, glows, the side stripe, grid and stripe
+  backgrounds, grey on colour, uniform card chrome, raw colour (under `--ratchet`),
+  default faces, emoji as icons (in markup and in data such as `icon: "📊"`, never
+  in prose), sparkles, fade-in on every section, overshoot curves, `transition:
+  all`, layout-property animation, `scale(0)`, `ease-in` and a missing reduced-motion
+  path. Exit 0 no S1, 1 an S1 or a file over its budget, 2 a usage error; S2 and S3
+  print and never block. Tests, dependencies, build output, hidden directories,
+  comments and a copied pack token layer's measured tokens are not reported. A
+  recorded exception is `sheleg-lint-allow: V0NN <reason>`, and a bare id waives
+  nothing. Written in Node like the installer, so it runs wherever `npx` does.
+- **D9, decided.** `CREATIVE_DIRECTOR.md` records markers-not-bans in place of the
+  old refusal, and the director's record gains a `Markers` line (the lint run and
+  each waived marker with the line that earned it).
+- **The lane references follow the umbrella's design pack.** A new design enters at
+  `references`; a redesign at `verify` + `visual-qa` + `a11y`; an update at
+  `tokens`, then `visual-qa`; an audit runs `a11y → verify → visual-qa → speed`; the
+  `--lane` list names `references`, `critique`, `visual-qa` and `speed`.
+- **Provenance, 16 → 20 rows**, all `derived`: impeccable's detector catalogue,
+  craft floor and motion reference at `12b25ae`, and `anthropics/skills`
+  `frontend-design` at `41bbe19`. Nothing was copied.
+- **Gates.** `validate_slop_markers()` holds the catalogue's shape and required
+  markers, and rule, id and severity in both directions between `bin/lint.js` and the
+  catalogue, with three plants; `test/lint_test.js` runs the real CLI on throwaway
+  trees (every S1 rule blocking, every quiet case quiet, the ratchet, the exit
+  contract); `--self-test` plants a defect and a clean twin for every rule.
+
+Calibrated on the two private codebases (read-only): 107 S1 / 18 S2 and 83 S1 / 5 S2,
+every listed defect found, the two test-fixture hits impeccable's detector reported
+absent by default and present under `--include-tests`. One false-positive class found
+there (a bare `"back"` string read as an ease) was fixed with a regression case. The
+same run over this repository's kits found two layout transitions of its own (B-140).
+The `SKILL.md` body is 4742/4750 tokens. Whether models produce fewer markers with the
+floor loaded was not measured (plan task D8).
+
+## 1.61.3 — every borrowed rule names its source, and the motion tools agree with the doctrine
+
+`MOTION_DOCTRINE.md` §1–4 is Emil Kowalski's animation doctrine almost word for word
+(the frequency table with its Raycast example, the easing tree, the three curves with
+their comments, the duration rows, both spring notations), and `KNOWLEDGE_PROVENANCE.md`
+had no row for `emilkowalski/skills`. The same was true of the three calibration dials
+(`Leonxlnx/taste-skill`) and the "three default looks" paragraph (`anthropics/skills`
+`frontend-design`), while row 6 pointed at `julianoczkowski/designer-skills`, whose file
+carries none of those looks. The file's own rule is "a source path, a SHA and a
+permalink, or it is not adopted"; it was not being kept.
+
+- **Provenance, 6 → 16 rows.** Rows 1–5 re-pinned to `pbakaus/impeccable@12b25ae` (only
+  `SKILL.md` changed bytes); row 6 kept and re-verified, with a note on what it did and
+  did not inform; rows 7–9 for the impeccable type, layout and finish-review files
+  `CREATIVE_DIRECTOR.md` already cited (now linked at the same commit); rows 10–14 for
+  `emilkowalski/skills@e8a175d`; row 15 for `taste-skill@e3c9203`; row 16 for
+  `anthropics/skills@2235be7`, the version installed when the looks section was
+  written. Three rows are `adapted`, so the MIT notices (Emil Kowalski, Leonxlnx) and an
+  Apache-2.0 notice now travel in the file, and each adapted passage names its source
+  where it sits, the condensed Cursor rule included.
+- **Emil's skills are tools inside the lanes, not a second entry point.**
+  `MOTION_DOCTRINE.md` §11 names `review-animations`, `improve-animations`,
+  `find-animation-opportunities`, `animate`, `animate-expo` and `apple-design`, and says
+  that `emil-design-eng` loads by itself; `MOBILE_SURFACES.md` names `mobile-native` and
+  `animate-expo`; `VISUAL_REVIEW.md` names `break-ui` for worst-case data before a
+  populated capture; `MOTION_PRODUCTION.md` says none of them reads a render timeline.
+- **Eleven rules reconciled, one value each** (table in `KNOWLEDGE_PROVENANCE.md`). The
+  doctrine changes four: no `ease-in` exit exception; the default spring is
+  `duration 0.4, bounce 0` with bounce only after a flick; `transition: all` and
+  entrances from `scale(0)` are banned; under reduced motion an opacity or colour change
+  that carries state may stay. It keeps its modal and drawer ceiling (200–300 ms;
+  500 ms only for a mobile sheet) against the tool's 200–500 ms, which contradicts the
+  tool's own under-300 rule, and the Cursor rule's stale `200–500ms` line is corrected
+  to match. `MOBILE_SURFACES.md` rule 1 now gives a hero `100svh` and an app shell
+  `100dvh`; the 28 packs that write `100dvh` are B-139.
+- **D7 text defects.** A bold lead sentence in `SKILL.md` said twice in a row, and the
+  "Three looks" section of `SHELEG_DESIGN.md` pasted twice with two Contents lines, the
+  second copy linking to itself. One copy of each is kept.
+- **The class, not only the instances.** `scripts/gen_contents.py` refuses a repeated
+  `## ` heading (a derived list derives the duplicate too, so drift never saw it), with a
+  validator plant; `test/sloplint.py` refuses the same sentence twice in a row, watched
+  failing on the pre-fix `SKILL.md`, and requires the `transition: all`, `scale(0)` and
+  "never a second entry point" text; `test/audit_regressions/xd-01.01.py` adds four
+  checks (permalink agrees with its row, adapted rows carry a notice, the reconciliation
+  is recorded, the looks name their source), three watched failing on the pre-fix files.
+
+The `SKILL.md` body is 4746/4750 tokens after the edit (house auditor at `5ca5c36`).
+Whether models follow the reconciled values was not measured.
+
 ## 1.61.2 — rendered copy is part of visual review
 
 Visual review now inspects headings, hero fragments, captions and labels against

package/README.md

@@ -175,6 +175,7 @@ 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 |
 | `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` |
 | `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 |
@@ -184,6 +185,29 @@ skills.
 | `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 |
 
+### Check a project against the floor
+
+```bash
+npx sheleg-design-skill --lint ./src            # human report, exit 1 on any S1
+npx sheleg-design-skill --lint ./src --json     # [{id, rule, severity, file, line, snippet}]
+npx sheleg-design-skill --lint ./src --ratchet sloplint-budget.json   # per-file budgets that only fall
+```
+
+The linter reads `html`, `css`, `scss`, `js`, `jsx`, `ts`, `tsx`, `vue`, `svelte`
+and `astro`, skips dependencies, build output, hidden directories and tests
+(`--include-tests` reads them), and checks the `lint:` rows of
+[`SLOP_MARKERS.md`](plugins/sheleg-design/skills/sheleg-design/SLOP_MARKERS.md):
+emoji used as icons (in markup and in data such as `icon: "📊"`), purple
+gradients, gradient text, a default face with no declared reason, decorative
+glass, the side stripe, glows, grid backgrounds, grey on colour, `transition: all`,
+layout-property animation, `scale(0)`, `ease-in`, overshoot curves and a missing
+`prefers-reduced-motion` path. Exit 0 means no S1 finding, 1 an S1 finding or a
+file over its budget, 2 a usage error; S2 and S3 print and never block. A
+recorded exception is a comment, `sheleg-lint-allow: V015 <reason>`, and the
+reason is required. `--self-test` plants a defect for every rule. It is a pattern
+reader, not a renderer: the catalogue's `review` rows stay with the render
+critique.
+
 ## What you get out of it
 
 - **A motion methodology, not a component dump.** Scroll-linked animation,
@@ -282,8 +306,8 @@ These run **in a clone of this repository**. The published npm package ships no
 python3 test/validate.py   # or: npm test
 ```
 
-`npm test` is **four gates**, not one, and `validate.py` alone is about a third
-of the contract:
+`npm test` is **several gates**, not one, and `validate.py` alone is about a
+third of the contract:
 
 | Gate | What it decides |
 |---|---|
@@ -291,6 +315,8 @@ of the contract:
 | `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 |
+| `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 |
 
 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

@@ -155,10 +155,17 @@ function parseArgs(argv) {
     version: false,
     kit: null, // --kit <pack>: materialize a reference kit instead of installing
     out: null, // --out <path>: where the kit goes
+    lint: null, // --lint <dir>: run the project linter (bin/lint.js) on a tree
+    json: false, // --json: lint findings as a JSON array
+    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
     error: null, // set → print help and exit non-zero
   };
+  const seen = [];
   for (let i = 0; i < argv.length; i++) {
     const a = argv[i];
+    seen.push(a.split("=")[0]);
     if (a === "--help" || a === "-h") opts.help = true;
     else if (a === "--version" || a === "-v") opts.version = true;
     else if (a === "--force" || a === "-f") opts.force = true;
@@ -190,10 +197,38 @@ function parseArgs(argv) {
       const value = a.slice("--out=".length);
       if (!value) opts.error = "--out needs a path";
       else opts.out = value;
-    } else {
+    } else if (a === "--lint" || a.startsWith("--lint=")) {
+      const value = a === "--lint" ? argv[++i] : a.slice("--lint=".length);
+      if (!value || value.startsWith("-")) opts.error = "--lint needs a directory";
+      else opts.lint = value;
+    } else if (a === "--ratchet" || a.startsWith("--ratchet=")) {
+      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 === "--json") opts.json = true;
+    else if (a === "--include-tests") opts.includeTests = true;
+    else if (a === "--self-test") opts.selfTest = true;
+    else {
       opts.error = `unknown argument: ${a}`;
     }
   }
+  if (opts.error) return opts;
+  // The linter reads a tree and writes nothing, so any install or kit flag beside
+  // it is a request for two different things at once.
+  const LINT_ONLY = ["--json", "--ratchet", "--include-tests"];
+  const OTHERS = ["--cursor", "--claude", "--dir", "--force", "-f", "--kit", "--out"];
+  if (opts.selfTest && seen.some((x) => x !== "--self-test")) {
+    opts.error = "--self-test runs on its own";
+    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;
+  }
+  if (opts.lint && seen.some((x) => OTHERS.includes(x))) {
+    opts.error = `--lint reads a project and installs nothing — ${seen.find((x) => OTHERS.includes(x))} does not combine with it`;
+    return opts;
+  }
   if (opts.flavor && opts.target) {
     opts.error = "--dir cannot be combined with --cursor / --claude";
   }
@@ -284,6 +319,20 @@ ${c("bold", "Claude Design")} ${c("dim", "(Claude Code only)")}
   come out only when asked for by name. Then: npm install && npm run build,
   and run /design-sync in that directory.
 
+${c("bold", "Project linter")}
+  --lint <dir>          Check a project against the visual floor in
+                        SLOP_MARKERS.md (emoji icons, purple gradients, default
+                        faces, banned motion forms and the rest of the lint: rows)
+  --json                Findings as [{id, rule, severity, file, line, snippet}]
+  --ratchet <budget>    Per-file budgets ({"<file>": count}) that may only fall;
+                        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
+
+  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", "Default")}
   Auto-detects: uses .cursor/ if present, else .claude/ if present,
   otherwise creates .cursor/skills/${SKILL_SLUG}/.
@@ -540,6 +589,18 @@ function main() {
     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,
+        );
+    return;
+  }
+
   const cwd = process.cwd();
 
   if (opts.kit) {