From fa59da566e9b5989abceac4018c518333bdb61aa Mon Sep 17 00:00:00 2001 From: Remon Panman <228601219+Tradebaas@users.noreply.github.com> Date: Fri, 7 Aug 2026 18:51:10 +0200 Subject: [PATCH] refactor(skills): design-guard stops judging what already has a judge The installed design method owns the making of a frontend, so design-guard stops carrying a second rulebook for one. It now routes before it checks: a web, iOS, Android or adaptive interface goes back to the method that built it, while documents, e-mails, exports, error strings, CLI and log output, and every platform the method does not carry (game engines, console, embedded and kiosk displays, TV, print) stay here, because nothing else judges those. The platforms are named rather than left implied, so nobody assumes coverage that does not exist. Nine visual rules that restated the craft floor are gone. What takes their place on the frontend route is a re-check rather than a second hunt: the direction contract kept, the FINISH line discharged, the finish verdict traveling with its open items under the reviewer's own word, the live-surface contract on a redesign, and DESIGN.md section 3 still mirroring the build. Scoring typography and spacing again is stated as the craft floor's job, not this skill's. Two floors sit above every route, because neither is stated anywhere else: the accessibility floor with its COMPLIANCE.md link, carried over unchanged and extended with reading order for a document and never-color-alone for any medium, and reduced motion, which decision 0020 moved to DESIGN.md principle 7 and which is exercised as a preference rather than read out of the CSS. The non-interface half was proven on this repo's own gate output rather than asserted: an empty-directory failure names what happened and what to do, uses a gate name rather than a bare code, and survives being piped with no escape sequences left behind. One finding stays unbuilt, "1 finding(s)" carrying a parenthetical plural, which is a wart and not a defect, so the intake freeze holds it out. verify's pointer follows the same split, and the AGENTS.md row says what this skill is now for. Traces-to: SC-8 --- .agents/skills/design-guard/SKILL.md | 141 +++++++++++------- .agents/skills/verify/SKILL.md | 4 +- AGENTS.md | 2 +- ...-design-guard-keeps-what-is-not-covered.md | 14 +- 4 files changed, 96 insertions(+), 65 deletions(-) diff --git a/.agents/skills/design-guard/SKILL.md b/.agents/skills/design-guard/SKILL.md index 8e1bcac..555394c 100644 --- a/.agents/skills/design-guard/SKILL.md +++ b/.agents/skills/design-guard/SKILL.md @@ -1,65 +1,94 @@ --- name: design-guard -description: Judgment check before delivering any UI or user-facing output: screens, components, documents, emails, error messages. Catches what no linter can - layout breakage, token bypass, off-voice copy, AI-default look. Run on what actually renders, not on the code. +description: Judgment check before delivering user-facing output the installed design method does not carry: generated documents, e-mails, exports, error and CLI output, and interfaces on platforms it has no guidance for (game engines, console, embedded, print). For a frontend it re-checks the render against its direction contract and the finish verdict instead of opening a second hunt. Run on what actually renders, not on the code. --- # design-guard: look at it before you ship it -Render the thing (screenshot, preview, generated document) and check *that*, not the source. -DESIGN.md and VOICE.md are the measuring stick; this catches what automation can't. - -Is it a frontend? Then the installed design method built it, its craft floor and its detector -already ran, and a finish reviewer already scored it. Start from that verdict: re-check the render -against the direction contract in the artifact's opening comment, and report what is still open -rather than opening a fresh hunt. - -## Visual - -1. **Tokens only.** Every color, size, radius, and space comes from the system: no raw values, - no palette bypass, no near-miss grays. One accent, used sparingly; status colors via opacity. -2. **No stock-AI look.** No default blue-to-purple palette and no gradient as a baseline (solid - fills, the project's own accent). No accent-colored border decoration: a tinted top stripe, - side bar, or edge segment on a card is a tell (card borders are the neutral line on every side; - accent on a border only as functional state). Default to Lucide icons, one consistent set, never emoji as - UI icons, wordmark is text unless a real logo exists. Buttons are text-only or icon-only, - never text plus a decorative icon (a disclosure chevron is the only exception). Strak and - minimal with generous whitespace: nothing cramped, cards/labels/text never flush against each - other, unless the owner deliberately chose otherwise. -3. **No stock-AI layout.** Four tells survive a corrected palette, so look for them in the shape - of the thing: cards nested inside cards (one bordered surface per region, and the grouping - inside it is plain), blurred gradient orbs left to do the decorating (DESIGN.md principle 10 - allows one deliberate owner-approved wash; a field of them, or one carrying a page nothing - else carries, is the tell), monospace worn as atmosphere on prose and labels instead of - carrying code, paths and IDs, and the row of exactly four big numbers that exists because the - template had four slots. A stat earns its place when someone measured it and would act on it; - otherwise the row goes, not just its weakest number. -4. **Locks hold page-wide.** One accent used identically in every section, one theme (no - section flipping to inverted mode mid-scroll), one corner-radius system, one icon family. - On persuasion pages also: eyebrow labels rationed (at most 1 per 3 sections), no layout - family repeated, no CTA label wrapping and one CTA label per intent, real images instead of - div-built fake screenshots, every animation motivated and reduced-motion safe. -5. **Typography discipline.** Scale steps only; label and value share size and weight - (distinction by color only); no banned weights; line lengths readable. -6. **Spacing ladder.** Air comes from consistent ladder steps, not ad-hoc gaps. Related things - closer than unrelated things: check it actually reads that way. -7. **Layout truth.** No text over text, no wrapping button labels or prices, equal heights in - card rows, reserved space for optional badges, sensible behavior at narrow width and with - long content. Check the ugly states: empty, loading, error, overflow. -8. **States exist.** Hover, focus (visible!), disabled, loading, empty, error: designed, not - browser defaults. -9. **Accessibility floor**: contrast, focus order, labels on inputs and icons, keyboard path - through the flow. (Legal baseline: see COMPLIANCE.md.) - -## Voice - -10. **Reads like VOICE.md**: register, wording table respected, direct and calm; no exclamation - inflation, no em-dash tells, no filler ("simply", "just", "please note"). -11. **Errors follow the pattern**: what happened, what the user can do: no codes without words, - no blame, no false cheer. -12. **Every value has a label**, every screen answers "what is this and what do I do here?" +Render the thing (screenshot, preview, generated document, a real run of the command) and check +*that*, not the source. DESIGN.md and VOICE.md are the measuring stick; this catches what +automation cannot. + +Impeccable, the installed design method, owns the making of a frontend: its craft floor, its +detector and its finish reviewer are the rulebook for one, and this skill does not carry a second +copy of it. Route first, then check. + +| What you are about to deliver | Who judges it | +|---|---| +| A web, iOS, Android or adaptive interface | The method built it. Section 2: re-check, never re-hunt | +| A generated document, e-mail, export, error message, CLI or log output, notification | This skill. Section 3 | +| An interface on a platform the method does not carry: Unity, Godot and other game engines, console UIs, embedded and kiosk displays, TV, print | This skill. Section 3, and the verdict says no design method covered it | + +## 1. The floors, on every route + +Neither of these is negotiable by a direction, a template, or a medium, and neither is stated in +the method's own guidance, so they are checked here whatever route you took. + +- **Accessibility floor**: contrast, focus order, labels on inputs and icons, keyboard path + through the flow. (Legal baseline: see COMPLIANCE.md.) On a document: reading order and tagged + structure. In any medium: never color alone carrying the meaning. +- **Reduced motion** (DESIGN.md principle 7): anything that moves collapses to static under the + user's `prefers-reduced-motion: reduce`, with the content still readable. Exercise the + preference, do not read the CSS for it. + +## 2. A frontend: re-check against what was committed + +The craft floor already ran, the detector already ran, and a reviewer that never saw the build +thread already scored the result. Start from those, and report what is still open. + +1. **The direction contract was kept.** It is the opening comment in the artifact (THESIS, + OWN-WORLD, STORY, FIRST VIEWPORT, FORM). Read it beside the render: a block describing + something the page does not do is the finding. A contract the production build erased is its + own finding, because nothing can be audited against it. +2. **The FINISH line is discharged.** The contract closes with the run's exit condition. A page + that looks complete with the finish review never run is abandoned, not done. +3. **The finish verdict travels as it stands.** Its open items stay open until they are fixed, + under the reviewer's own disposition word. Never summarized into a pass. +4. **The live-surface contract, on a redesign** (`design` step 3): URLs and slugs, page titles + and structured data, navigation labels, form field names and their order, analytics names, the + wordmark, legal and consent copy. Anything on that list that moved without the owner saying so + is a finding, and what does move ships with redirects. +5. **DESIGN.md section 3 still mirrors the built world.** It is written from the build after the + finish review; code is the source of truth, so tokens that moved since leave a stale mirror. + +Scoring typography, spacing, palette or layout tells again is not this skill's job: that ground +belongs to the craft floor and the detector, which already ran. If something there is genuinely +wrong, the answer is another round of the method, not a private list here. + +## 3. Output the method does not carry + +Nothing else judges these, so judge them fully. On a platform the method has no guidance for, the +platform's own published guidelines are the missing rulebook: read them, check against them, and +name the gap in the verdict rather than implying coverage that does not exist. + +**Visual** + +1. **Tokens only.** Every color, size, radius and space comes from DESIGN.md section 3 and the + code that owns them: no raw values, no palette bypass, no near-miss grays. A generator that + ships its library's default blue is a finding, not a detail. +2. **The medium's own constraints are honored.** An e-mail renders without web fonts and without + the CSS its clients strip. A document paginates: headers, page numbers, no heading orphaned at + a page foot, tables that survive a break. A CLI survives being piped to a file, with no escape + sequences left in it, and stays readable where the terminal wraps it. +3. **Layout truth on the real content.** No text over text, no wrapping labels or prices, equal + heights in a row, reserved space for what is optional. Check the ugly cases: empty, error, + overflow, the longest value your data actually contains. +4. **No stock-AI look.** DESIGN.md principles 9 and 10 bind here too: a template's stock palette, + a grab-bag of icons and an emoji standing in for one reach a document and an e-mail as easily + as a screen, and no detector is watching this medium. + +**Voice** + +5. **Reads like VOICE.md**: register, wording table respected, direct and calm. Its banned-phrasing + list is explicitly judgment rather than mechanical, and this is the check that catches it. +6. **Errors follow the pattern**: what happened, what the user can do; no codes without words, no + blame, no false cheer. This is the rule that leaks furthest: a string in an API response, a log + line or a toast is user-facing text and is judged here. +7. **Every value has a label**, and the output answers "what is this and what do I do with it". ## Verdict -Report findings as one line each (`: → `), most severe first, then -fix them before delivering. Nothing to report? Say "clean" and ship. If a finding recurs across -sessions, it wants a token, a component, or a mechanical check. Propose that once, in INTAKE. ⚓ +Report findings as one line each (`: → `), most severe first, then fix +them before delivering. Name the route you took, so the reader knows what was judged and by whom. +Nothing to report? Say "clean" and ship. If a finding recurs across sessions, it wants a token, a +component, or a mechanical check. Propose that once, in INTAKE. ⚓ diff --git a/.agents/skills/verify/SKILL.md b/.agents/skills/verify/SKILL.md index 4909920..50ce8d5 100644 --- a/.agents/skills/verify/SKILL.md +++ b/.agents/skills/verify/SKILL.md @@ -24,7 +24,9 @@ Run the full chain and paste real results, not summaries of results: explained and traced to a rule before the criterion counts as met. - Probe the edges the criteria imply: empty input, wrong input, unauthorized user, the second run (idempotency), the slow path. The first bug is usually one step off the happy path. -- UI change → also run `design-guard` on what appeared on screen. +- User-facing output → also run `design-guard` on what rendered. A built interface gets re-checked + against its direction contract and the finish verdict; a document, e-mail, export or error + string gets judged there in full, because the design method does not carry those. - Bug fix → reproduce the bug first on the old behavior (or its regression test), then show it gone. A fix you never saw fail is a guess. Cause unknown, or a fix attempt already failed? Run the `debug` skill's loop before trying again. diff --git a/AGENTS.md b/AGENTS.md index 6ac57ac..9e58378 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -106,7 +106,7 @@ trigger applies. The library: | `architect` | System design before building: boundaries, data, contracts, threats | | `design` | Standing up the project's design & voice system | | `scope-guard` | Before calling work done or proposing a commit | -| `design-guard` | Before delivering any UI or user-facing output | +| `design-guard` | Before delivering documents, e-mails, exports or error text, and to re-check a built interface | | `verify` | Verifying a change actually works, end to end | | `debug` | A bug, crash or failing test with no obvious cause; a fix attempt that did not work | | `code-review` | After `verify`, before committing substantial work: fresh-eyes review of the diff by independent axes | diff --git a/docs/specs/011-design-on-impeccable/tickets/04-design-guard-keeps-what-is-not-covered.md b/docs/specs/011-design-on-impeccable/tickets/04-design-guard-keeps-what-is-not-covered.md index 5937906..07a5e85 100644 --- a/docs/specs/011-design-on-impeccable/tickets/04-design-guard-keeps-what-is-not-covered.md +++ b/docs/specs/011-design-on-impeccable/tickets/04-design-guard-keeps-what-is-not-covered.md @@ -1,7 +1,7 @@ # 04: design-guard judges what impeccable does not - **Blocked by:** 03-retire-taste.md -- **Status:** ready +- **Status:** done - **Traces to:** BRIEF SC-8 **What to build:** One judgment check before delivering user-facing output, with no duplicated @@ -15,12 +15,12 @@ already closed. **Acceptance:** -- [ ] `design-guard` no longer restates rules that impeccable's craft floor owns; what remains is +- [x] `design-guard` no longer restates rules that impeccable's craft floor owns; what remains is what it alone covers, plus the render check against the direction contract. -- [ ] Output that is not an interface (a generated document, an e-mail, an error message) is still +- [x] Output that is not an interface (a generated document, an e-mail, an error message) is still fully covered, proven on a real example. -- [ ] Platforms impeccable does not carry (game engines, console and embedded interfaces) are named +- [x] Platforms impeccable does not carry (game engines, console and embedded interfaces) are named as this skill's ground, so nobody assumes coverage that does not exist. -- [ ] `verify` still routes a UI change to the right check, and its pointer is correct. -- [ ] The accessibility floor and its link to COMPLIANCE.md survive the edit unchanged. -- [ ] `node checks/check.mjs` and the self-test suites stay green. +- [x] `verify` still routes a UI change to the right check, and its pointer is correct. +- [x] The accessibility floor and its link to COMPLIANCE.md survive the edit unchanged. +- [x] `node checks/check.mjs` and the self-test suites stay green.