tiny-spec 0.3.0__tar.gz → 0.4.0__tar.gz

{tiny_spec-0.3.0 → tiny_spec-0.4.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: tiny-spec
-Version: 0.3.0
+Version: 0.4.0
 Summary: A tiny, opinionated take on spec-driven development.
 Project-URL: Homepage, https://github.com/GrayMa77er/tiny-spec
 Project-URL: Source, https://github.com/GrayMa77er/tiny-spec
@@ -121,6 +121,11 @@ Or collapse the three planning steps into one and go straight to building:
 **stops before `tiny-spec-build`** — that's where you actually review the work — and
 it writes nothing itself, it only delegates.
 
+**Building from a mockup?** There is no design flag to pass. Commit your exports to
+`design/` before the run and `tiny-spec-create` — whether you invoke it directly or
+reach it through `tiny-spec-run` — reads what's there and asks which screens this
+ticket covers. [Designs, if you have them](#designs-if-you-have-them) walks through it.
+
 Re-run `install` any time to update; `tiny-spec uninstall` removes only what it
 installed. Each skill is copied (not symlinked) so every install is
 self-contained.
@@ -161,25 +166,164 @@ stale, since they were reviewed against a document that wasn't there.
 
 ### Designs, if you have them
 
-Drop your exported wireframes in a `design/` directory and `tiny-spec-create` will
-look at them — actually look, they are read as images. From all of them together it
-proposes one coherent **design system** (spacing scale, type scale, color roles) for
-your approval and writes it into the constitution, then describes each screen as a
-`D<n>` entry in `SPEC.md`: its layout, its elements with a selector each, and the
-states it must render — all in those token names.
-
-The point is what happens at build time. Tag a task with `design: D1` and the
-reviewer renders that surface, measures the selectors the entry names, and **fails the
-task** on a value that isn't on your scale, an element that never got built, or a
-state the design calls for and the code doesn't render. It measures numbers rather
-than diffing screenshots, because pixel diffs go flaky and get muted. Tasks without a
-`design:` tag are graded exactly as before.
-
-No Figma token, no plugin, no design SaaS — a view-only Figma works fine, since the
-committed export is what the agents read and the `source:` link keeps the trail back.
-Change an export and its recorded hash stops matching, which marks the spec stale the
-same way editing a requirement does. Skip the whole thing for a CLI or a library; the
-constitution simply has no design section.
+Wireframes usually get read once and forgotten. tiny-spec turns them into two durable
+things — a project-wide token system in the constitution, and a per-screen entry in
+the spec — so "does this look right?" becomes something the reviewer can fail a task
+on. Skip all of it for a CLI or a library; the constitution simply has no design
+section.
+
+**Designs enter by convention, not by argument.** No skill takes a design flag or a
+path parameter. `tiny-spec-create` reads every file in `design/` at your project root —
+directly, or when `tiny-spec-run` reaches it — and asks which screens this ticket
+covers; you can also just hand it paths during the interview. Change an export later and
+re-running `create` (or `run`) re-hashes it, marking the spec stale exactly like editing
+a requirement.
+
+**1. Commit your exports.** Any format an agent can read — a Figma export, an HTML
+mockup, an Excalidraw file, a photo of a whiteboard.
+
+```
+your-project/
+  design/
+    signup.png
+    dashboard.png
+```
+
+**2. `tiny-spec-create` looks at them and proposes a design system.** Actually looks —
+they are read as images. It infers *one* coherent scale across all of them rather than
+measuring each screen separately, tells you what it rounded ("your wireframes had 19px
+and 21px — proposing `space.5`=20px for both"), and on your approval writes it into
+`.spec/constitution.md`:
+
+```markdown
+## Design system
+- color:  `color.surface.base` #FFFFFF · `color.text.default` #111111
+          `color.text.muted` #6B7280 · `color.text.danger` #B91C1C
+- space:  `space.1`=4px · `space.2`=8px · `space.4`=16px · `space.6`=24px
+- type:   `type.heading.lg` 24px/600/1.25 · `type.body` 16px/400/1.5
+          `type.caption` 13px/400/1.4
+- states: every interactive surface defines default, focus, disabled, loading, empty, error
+```
+
+Since it is project-wide, every screen from here on speaks this vocabulary — and a
+redesign edits this one table instead of every file.
+
+**3. Each screen becomes a `D<n>` in `SPEC.md`**, written in those token names:
+
+```markdown
+## Design
+
+- D1 — Signup form
+  - source: figma.com/file/abc#node-12:34 (view-only)
+  - export: design/signup.png
+  - sha256: d21d6330648c504edeb924b5398bf7fb6485d3a4c1907e43d800970f39622a1d
+  - layout: single centered column, max 420px; title → field → error → submit
+  - elements:
+    - card    `[data-testid="signup-card"]`   → space.6 padding, color.surface.base
+    - title   `[data-testid="signup-title"]`  → type.heading.lg, space.4 below
+    - field   `[data-testid="signup-email"]`  → type.body, space.2 below
+    - error   `[data-testid="signup-error"]`  → type.caption, color.text.danger
+  - states: error (caption under the field), loading (spinner replaces button label)
+```
+
+The selectors are a **contract**, not a hint — the reviewer measures exactly these, so
+your markup carries them verbatim. Prefer test ids over CSS classes: classes get
+renamed by refactors and mangled by CSS-in-JS, and a selector that silently stops
+matching is the failure this exists to prevent.
+
+**4. Tag the tasks that build the surface** — and only those, not the API call behind
+it. This is your blast radius:
+
+```
+- [ ] T4 — Build the signup form
+  - acceptance: submitting a valid email advances to the verify step
+  - design: D1
+```
+
+**5. The reviewer measures it, then looks at it, and fails on both:**
+
+```
+DESIGN: D1 — Signup form
+  [data-testid="signup-card"]  padding 19px — not on the space.* scale (4/8/16/24)
+  [data-testid="signup-email"] MISSING FROM DOM — never built, or renamed
+  [data-testid="signup-error"] rgb(204,0,0) — color.text.danger is #B91C1C
+  state "loading" never renders: button label stays "Continue", no spinner
+  judge: read states default, error — compared against design/signup.png
+    state "error": signup-error sits behind the card — every token right, and the
+      user sees nothing where the export shows the red caption
+    state "default": submit label "Create account" truncates to "Create acco…"
+FINDINGS:
+- flag: title/field gap feels tight (on-scale — does not fail the task)
+```
+
+Numbers first, and never a screenshot diff — pixel comparison goes flaky on font
+antialiasing and teams end up muting it. But no measurement catches an element that is
+present, on-token, and still not on screen — occluded, clipped, truncated, or the same
+color as what's behind it. So the last step reads a screenshot of each state next to
+your export and grades presence, legibility, and correspondence. **Where a number
+already settled the question the eye may only flag** — on-scale-but-cramped is never a
+fail — which keeps the two halves from contradicting each other. Measurable or visible
+violations fail; taste comes back as `flag:` notes so a bounded fix loop can't thrash. A
+task with no `design:` tag is graded exactly as before.
+
+<details>
+<summary>The <code>visual:</code> command (you write this once)</summary>
+
+tiny-spec ships no script — it can't know your stack. Write one, put it in the
+constitution's **Verification commands**, and the reviewer runs it:
+
+```
+## Verification commands
+- test:   `npm test`
+- visual: `node visual.mjs`
+```
+
+```js
+// visual.mjs — node visual.mjs '<selector>' ['<selector>'...]
+import { chromium } from 'playwright';
+
+const b = await chromium.launch({ channel: 'chrome' });   // your Chrome, no download
+const p = await b.newPage({ viewport: { width: 900, height: 700 } });
+await p.goto('http://localhost:3000/signup');             // your dev server + route
+
+for (const sel of process.argv.slice(2)) {
+  const el = await p.$(sel);
+  if (!el) { console.log(`${sel}\n  MISSING FROM DOM`); continue; }   // required
+  console.log(sel, JSON.stringify(await el.evaluate(n => {
+    const c = getComputedStyle(n), r = n.getBoundingClientRect();
+    return { padding: c.padding, margin: c.margin, fontSize: c.fontSize,
+             fontWeight: c.fontWeight, lineHeight: c.lineHeight, color: c.color,
+             background: c.backgroundColor, border: c.border,
+             opacity: c.opacity, visibility: c.visibility,
+             top: Math.round(r.top), w: Math.round(r.width), h: Math.round(r.height) };
+  })));
+}
+
+const state = process.env.STATE ?? 'default';      // however you drive states
+const shot = `/tmp/visual-${state}.png`;
+await p.screenshot({ path: shot, fullPage: true });
+console.log('SCREENSHOT', state, shot);            // this line arms the judge
+
+await b.close();
+```
+
+The missing-selector branch **must print something** — that is what turns a renamed
+element into a failure instead of a silent skip. `top` is what the layout-order check
+reads, and `opacity`/`visibility` are worth printing because they turn the cheapest kind
+of invisible element into a numeric failure. The `SCREENSHOT` line is what the reviewer
+reads back to look at the render and catch the rest — occlusion, clipping, truncation,
+same-color-on-same-color — none of which any single property reports. Drop it and the
+numeric half still gates exactly as before, with the reviewer reporting `judge: not run`
+rather than quietly skipping it. Without a `visual:` command at all, a task tagged
+`design:` raises a blocker rather than passing quietly.
+
+</details>
+
+**No Figma token, plugin, or design SaaS.** A view-only account works fine: the
+committed export is what the agents read, and `source:` keeps the trail back. Change
+an export and its recorded `sha256` stops matching, which marks the spec stale exactly
+like editing a requirement — so a design that moved under finished work can't pass
+unnoticed.
 
 `tiny-spec-build` walks the task list top to bottom. Each task runs through one loop:
 

{tiny_spec-0.3.0 → tiny_spec-0.4.0}/README.md

@@ -84,6 +84,11 @@ Or collapse the three planning steps into one and go straight to building:
 **stops before `tiny-spec-build`** — that's where you actually review the work — and
 it writes nothing itself, it only delegates.
 
+**Building from a mockup?** There is no design flag to pass. Commit your exports to
+`design/` before the run and `tiny-spec-create` — whether you invoke it directly or
+reach it through `tiny-spec-run` — reads what's there and asks which screens this
+ticket covers. [Designs, if you have them](#designs-if-you-have-them) walks through it.
+
 Re-run `install` any time to update; `tiny-spec uninstall` removes only what it
 installed. Each skill is copied (not symlinked) so every install is
 self-contained.
@@ -124,25 +129,164 @@ stale, since they were reviewed against a document that wasn't there.
 
 ### Designs, if you have them
 
-Drop your exported wireframes in a `design/` directory and `tiny-spec-create` will
-look at them — actually look, they are read as images. From all of them together it
-proposes one coherent **design system** (spacing scale, type scale, color roles) for
-your approval and writes it into the constitution, then describes each screen as a
-`D<n>` entry in `SPEC.md`: its layout, its elements with a selector each, and the
-states it must render — all in those token names.
-
-The point is what happens at build time. Tag a task with `design: D1` and the
-reviewer renders that surface, measures the selectors the entry names, and **fails the
-task** on a value that isn't on your scale, an element that never got built, or a
-state the design calls for and the code doesn't render. It measures numbers rather
-than diffing screenshots, because pixel diffs go flaky and get muted. Tasks without a
-`design:` tag are graded exactly as before.
-
-No Figma token, no plugin, no design SaaS — a view-only Figma works fine, since the
-committed export is what the agents read and the `source:` link keeps the trail back.
-Change an export and its recorded hash stops matching, which marks the spec stale the
-same way editing a requirement does. Skip the whole thing for a CLI or a library; the
-constitution simply has no design section.
+Wireframes usually get read once and forgotten. tiny-spec turns them into two durable
+things — a project-wide token system in the constitution, and a per-screen entry in
+the spec — so "does this look right?" becomes something the reviewer can fail a task
+on. Skip all of it for a CLI or a library; the constitution simply has no design
+section.
+
+**Designs enter by convention, not by argument.** No skill takes a design flag or a
+path parameter. `tiny-spec-create` reads every file in `design/` at your project root —
+directly, or when `tiny-spec-run` reaches it — and asks which screens this ticket
+covers; you can also just hand it paths during the interview. Change an export later and
+re-running `create` (or `run`) re-hashes it, marking the spec stale exactly like editing
+a requirement.
+
+**1. Commit your exports.** Any format an agent can read — a Figma export, an HTML
+mockup, an Excalidraw file, a photo of a whiteboard.
+
+```
+your-project/
+  design/
+    signup.png
+    dashboard.png
+```
+
+**2. `tiny-spec-create` looks at them and proposes a design system.** Actually looks —
+they are read as images. It infers *one* coherent scale across all of them rather than
+measuring each screen separately, tells you what it rounded ("your wireframes had 19px
+and 21px — proposing `space.5`=20px for both"), and on your approval writes it into
+`.spec/constitution.md`:
+
+```markdown
+## Design system
+- color:  `color.surface.base` #FFFFFF · `color.text.default` #111111
+          `color.text.muted` #6B7280 · `color.text.danger` #B91C1C
+- space:  `space.1`=4px · `space.2`=8px · `space.4`=16px · `space.6`=24px
+- type:   `type.heading.lg` 24px/600/1.25 · `type.body` 16px/400/1.5
+          `type.caption` 13px/400/1.4
+- states: every interactive surface defines default, focus, disabled, loading, empty, error
+```
+
+Since it is project-wide, every screen from here on speaks this vocabulary — and a
+redesign edits this one table instead of every file.
+
+**3. Each screen becomes a `D<n>` in `SPEC.md`**, written in those token names:
+
+```markdown
+## Design
+
+- D1 — Signup form
+  - source: figma.com/file/abc#node-12:34 (view-only)
+  - export: design/signup.png
+  - sha256: d21d6330648c504edeb924b5398bf7fb6485d3a4c1907e43d800970f39622a1d
+  - layout: single centered column, max 420px; title → field → error → submit
+  - elements:
+    - card    `[data-testid="signup-card"]`   → space.6 padding, color.surface.base
+    - title   `[data-testid="signup-title"]`  → type.heading.lg, space.4 below
+    - field   `[data-testid="signup-email"]`  → type.body, space.2 below
+    - error   `[data-testid="signup-error"]`  → type.caption, color.text.danger
+  - states: error (caption under the field), loading (spinner replaces button label)
+```
+
+The selectors are a **contract**, not a hint — the reviewer measures exactly these, so
+your markup carries them verbatim. Prefer test ids over CSS classes: classes get
+renamed by refactors and mangled by CSS-in-JS, and a selector that silently stops
+matching is the failure this exists to prevent.
+
+**4. Tag the tasks that build the surface** — and only those, not the API call behind
+it. This is your blast radius:
+
+```
+- [ ] T4 — Build the signup form
+  - acceptance: submitting a valid email advances to the verify step
+  - design: D1
+```
+
+**5. The reviewer measures it, then looks at it, and fails on both:**
+
+```
+DESIGN: D1 — Signup form
+  [data-testid="signup-card"]  padding 19px — not on the space.* scale (4/8/16/24)
+  [data-testid="signup-email"] MISSING FROM DOM — never built, or renamed
+  [data-testid="signup-error"] rgb(204,0,0) — color.text.danger is #B91C1C
+  state "loading" never renders: button label stays "Continue", no spinner
+  judge: read states default, error — compared against design/signup.png
+    state "error": signup-error sits behind the card — every token right, and the
+      user sees nothing where the export shows the red caption
+    state "default": submit label "Create account" truncates to "Create acco…"
+FINDINGS:
+- flag: title/field gap feels tight (on-scale — does not fail the task)
+```
+
+Numbers first, and never a screenshot diff — pixel comparison goes flaky on font
+antialiasing and teams end up muting it. But no measurement catches an element that is
+present, on-token, and still not on screen — occluded, clipped, truncated, or the same
+color as what's behind it. So the last step reads a screenshot of each state next to
+your export and grades presence, legibility, and correspondence. **Where a number
+already settled the question the eye may only flag** — on-scale-but-cramped is never a
+fail — which keeps the two halves from contradicting each other. Measurable or visible
+violations fail; taste comes back as `flag:` notes so a bounded fix loop can't thrash. A
+task with no `design:` tag is graded exactly as before.
+
+<details>
+<summary>The <code>visual:</code> command (you write this once)</summary>
+
+tiny-spec ships no script — it can't know your stack. Write one, put it in the
+constitution's **Verification commands**, and the reviewer runs it:
+
+```
+## Verification commands
+- test:   `npm test`
+- visual: `node visual.mjs`
+```
+
+```js
+// visual.mjs — node visual.mjs '<selector>' ['<selector>'...]
+import { chromium } from 'playwright';
+
+const b = await chromium.launch({ channel: 'chrome' });   // your Chrome, no download
+const p = await b.newPage({ viewport: { width: 900, height: 700 } });
+await p.goto('http://localhost:3000/signup');             // your dev server + route
+
+for (const sel of process.argv.slice(2)) {
+  const el = await p.$(sel);
+  if (!el) { console.log(`${sel}\n  MISSING FROM DOM`); continue; }   // required
+  console.log(sel, JSON.stringify(await el.evaluate(n => {
+    const c = getComputedStyle(n), r = n.getBoundingClientRect();
+    return { padding: c.padding, margin: c.margin, fontSize: c.fontSize,
+             fontWeight: c.fontWeight, lineHeight: c.lineHeight, color: c.color,
+             background: c.backgroundColor, border: c.border,
+             opacity: c.opacity, visibility: c.visibility,
+             top: Math.round(r.top), w: Math.round(r.width), h: Math.round(r.height) };
+  })));
+}
+
+const state = process.env.STATE ?? 'default';      // however you drive states
+const shot = `/tmp/visual-${state}.png`;
+await p.screenshot({ path: shot, fullPage: true });
+console.log('SCREENSHOT', state, shot);            // this line arms the judge
+
+await b.close();
+```
+
+The missing-selector branch **must print something** — that is what turns a renamed
+element into a failure instead of a silent skip. `top` is what the layout-order check
+reads, and `opacity`/`visibility` are worth printing because they turn the cheapest kind
+of invisible element into a numeric failure. The `SCREENSHOT` line is what the reviewer
+reads back to look at the render and catch the rest — occlusion, clipping, truncation,
+same-color-on-same-color — none of which any single property reports. Drop it and the
+numeric half still gates exactly as before, with the reviewer reporting `judge: not run`
+rather than quietly skipping it. Without a `visual:` command at all, a task tagged
+`design:` raises a blocker rather than passing quietly.
+
+</details>
+
+**No Figma token, plugin, or design SaaS.** A view-only account works fine: the
+committed export is what the agents read, and `source:` keeps the trail back. Change
+an export and its recorded `sha256` stops matching, which marks the spec stale exactly
+like editing a requirement — so a design that moved under finished work can't pass
+unnoticed.
 
 `tiny-spec-build` walks the task list top to bottom. Each task runs through one loop:
 

{tiny_spec-0.3.0 → tiny_spec-0.4.0}/agents/tiny-spec-build-reviewer.md

@@ -73,15 +73,50 @@ acceptance and the constitution — verified, not inferred?**
      source is not evidence**, and it false-passes routinely (a comment saying the
      loading state is missing contains "loading"). A surface that renders its happy
      path and nothing else is a fail, not a nit.
-   - Finally, `Read` the export image as a cross-check for what numbers can't catch
-     (a missing element, wrong order, wrong hierarchy).
+   - Finally, **judge the render against the export.** Everything above proves the
+     numbers are right. None of it can see an element that is present, on-token, and
+     invisible — so now look. `Read` each `SCREENSHOT <state> <path>` the `visual:`
+     command printed, `Read` the `D<n>`'s `export:` image, and grade **every state you
+     have a screenshot for**, not just the happy path, on four lines:
+
+     1. **Presence** — is every `elements:` row actually *visible* in the render? At
+        `opacity: 0`, zero height, clipped out of view, hidden behind a sibling, or the
+        same color as its background, an element passes every measurement above and is
+        not there. **FAIL** — this is why the step exists.
+     2. **Legibility & occlusion** — text clipped, truncated mid-word, overlapping
+        another element, or on a background it can't be read against. **FAIL.**
+     3. **Correspondence** — does the render show the same screen as the export: the
+        same regions, in the reading order `layout:` names? A whole region missing is a
+        **FAIL**; a stylistic difference is a **flag**.
+     4. **Hierarchy & polish** — emphasis, balance, crowding, alignment. **Always a
+        flag**, never a fail.
+
+     Three rules bound it:
+
+     - **The numbers beat your eye on anything they already measured.** Padding that is
+       on the `space.*` scale but looks cramped is a `flag:`. A color that is exactly
+       its token but looks washed out is a `flag:`. You may fail only on what
+       measurement *cannot* see. Contradicting your own numbers sends the executor a
+       task it cannot fix, and the loop is bounded at two attempts.
+     - **This is still not a pixel diff.** The export is usually a wireframe — judge
+       structure and legibility, never visual identity.
+     - **Cite what you saw.** Name the state whose screenshot the finding came from and
+       what was in it ("state `error`: caption present in DOM but renders at opacity 0").
+       An uncited visual claim reads as an opinion and gets ignored.
+
+     **If the command printed no `SCREENSHOT` line**, do not run this sub-step and do
+     not eyeball a substitute. Grade on steps 1–3 above, write `judge: not run — visual:
+     emitted no SCREENSHOT line` in your `DESIGN:` section, and add a `flag:` saying the
+     command should screenshot each state it drives and print `SCREENSHOT <state>
+     <path>`. This is **not** a fail — unlike a missing `visual:` command, the gate did
+     run; only its last cross-check was unavailable.
 
 ## Verdict rules
 
 - **`PASS`** — the gate is green AND you exercised the acceptance end-to-end with
   real input AND the observed effect matches AND no invariant/DoD violation — AND,
-  on a task carrying `design:`, step 4 ran and found nothing measurable wrong. Only
-  this is a pass.
+  on a task carrying `design:`, step 4 ran and found nothing measurable *or visible*
+  wrong. Only this is a pass.
 - **`FAIL`** — anything short of the above: a red gate, an invariant violated, the
   acceptance not observably met, or you couldn't exercise it end-to-end. When torn,
   **fail** — never round up. List concrete, actionable findings so the executor
@@ -95,10 +130,19 @@ carrying `design:`:
   color/spacing where a token exists, an order or arrangement that contradicts
   `layout:`, or a state the `D<n>` entry names that doesn't render. These are
   objective and an executor can fix them from your numbers.
+- **`FAIL` on what you saw** in a screenshot and could not have measured: an element
+  that renders invisibly (opacity 0, zero height, clipped, occluded, same color as its
+  background), text that clips or overlaps, or a region the export has that the render
+  lacks. Equally objective — name the state, and the executor can fix it from your
+  description.
 - **Flag, don't fail, on taste.** "The hierarchy feels off", "spacing looks cramped
   but is on-scale" — put it in `FINDINGS` prefixed `flag:` and pass if everything
   measurable is green. The fix loop is bounded at two attempts; burning it on a
   subjective disagreement means the task blocks on something no executor can resolve.
+- **Where the numbers already answered the question, your eye may only flag.** This is
+  the line between the two fail lists above: measurement wins on values it took, sight
+  wins on what measurement can't reach. A finding that contradicts your own numbers is
+  a `flag:`, never a `FAIL`.
 - The "when torn, fail" rule still governs steps 1–3 unchanged. It does **not** apply
   to a subjective visual impression.
 
@@ -119,6 +163,8 @@ ACCEPTANCE: <how you exercised it + the observed effect, or why you couldn't>
 DESIGN: <omit unless the task carried `design:`. The D<n> checked, the measurements
   you read back vs the tokens they should match, and which states you exercised —
   or "blocker: no `visual:` command in the constitution">
+  judge: <the states whose screenshots you read and what you saw in each — or
+    "not run — visual: emitted no SCREENSHOT line">
 FINDINGS:
 - <each invariant/DoD/acceptance problem, concrete and actionable> (omit if PASS)
 - flag: <subjective visual note — does not fail the task> (only with a DESIGN section)

{tiny_spec-0.3.0 → tiny_spec-0.4.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "tiny-spec"
-version = "0.3.0"
+version = "0.4.0"
 description = "A tiny, opinionated take on spec-driven development."
 readme = "README.md"
 requires-python = ">=3.9"

{tiny_spec-0.3.0 → tiny_spec-0.4.0}/tiny-spec-build/SKILL.md

@@ -79,8 +79,10 @@ It runs the real gate end-to-end, checks the code against the constitution's
 **Definition of Done** and **invariants**, confirms the **acceptance** actually
 holds (exercised, not inferred), and returns `VERDICT: PASS | FAIL` + findings.
 On a `design:` task it also runs the constitution's `visual:` command, measures the
-selectors the `D<n>` names against the Design system tokens, and exercises the states
-it names — failing on measurable deviations and merely flagging subjective ones.
+selectors the `D<n>` names against the Design system tokens, exercises the states it
+names, and finally **looks at the render beside the design export** — catching what
+numbers can't reach, like an element that measures perfectly and shows up invisible.
+It fails on what it measured or saw, and merely flags what is taste.
 
 > Why independent: unit-green ≠ working, and the author is the worst judge of its
 > own blind spots. The reviewer running the gate from a clean state is the

{tiny_spec-0.3.0 → tiny_spec-0.4.0}/tiny-spec-create/SKILL.md

@@ -215,7 +215,11 @@ If `.spec/` does not exist:
    - visual:  `...`   # optional; only if there is a Design system above. The command
      that boots the UI so the reviewer can read back computed styles and geometry
      (e.g. a Playwright script that navigates to a route and prints
-     getComputedStyle/getBoundingClientRect for the selectors it is given). Required
+     getComputedStyle/getBoundingClientRect for the selectors it is given). It also
+     saves a screenshot of each state it drives and prints `SCREENSHOT <state> <path>`
+     for each — that line is what lets the reviewer look at the render next to the
+     design export and catch what numbers can't (an element that is on-token but
+     invisible, clipped text). Scratch files, gitignored. Required
      before any task may carry a `design:` reference — a task that names one with no
      `visual:` command here is a blocker, not a silent pass.
    >
@@ -249,6 +253,13 @@ in `SPEC.md`. Skip the whole section for a CLI, library, or headless service.
    computed styles (a Playwright script, a dev-server URL plus a snippet). Record it
    in **Verification commands**. Without it no task can carry a `design:` reference.
 
+   Ask that it **also screenshot each state it drives** and print
+   `SCREENSHOT <state> <path>` — one `page.screenshot({ path })` call next to the
+   measuring it already does, not a second script. That line is what lets the reviewer
+   look at the render beside the export, which is the only way to catch an element that
+   measures perfectly and renders invisibly. If the user says no, that's fine: the gate
+   still works on numbers alone and the reviewer reports the judge as not run.
+
 4. **Write one `D<n>` entry per screen this ticket touches**, with the source link,
    the committed export path, and its `sha256` (`shasum -a 256 <file>` — this is the
    staleness signal, so compute it, never invent it). Describe layout, elements, and

{tiny_spec-0.3.0 → tiny_spec-0.4.0}/tiny-spec-plan/SKILL.md

@@ -65,6 +65,10 @@ a scale from the wireframes; your job is to make it enforceable:
 - **Confirm the `visual:` command actually runs.** It is the gate for every task
   carrying `design:`; an aspirational command means the visual gate silently never
   fires. If it doesn't work from a clean checkout, fix it or drop the `design:` refs.
+  **Check it prints a `SCREENSHOT <state> <path>` line per state it drives** — that is
+  what lets the reviewer judge the render against the design export, and a constitution
+  written before that existed won't have it. Add the `page.screenshot({ path })` call;
+  it is one line, and without it the reviewer grades on numbers alone and says so.
 - Add the scale as a **guiding invariant** where it matters ("no raw color or spacing
   values in UI code — reference a token"), since that is the line a reviewer fails on.
 

{tiny_spec-0.3.0 → tiny_spec-0.4.0}/tiny_spec/__init__.py

@@ -5,4 +5,4 @@ into your Claude Code config directory (``~/.claude/`` by default). It adds no
 runtime behavior to the suite itself.
 """
 
-__version__ = "0.3.0"
+__version__ = "0.4.0"