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.