From e32cbe5fca8fe770df36404b5b915500dade0709 Mon Sep 17 00:00:00 2001 From: garrytan Date: Thu, 8 Oct 2026 14:55:18 +0000 Subject: [PATCH] design-review: capture code tokens before universal principles /design-review read only DESIGN.md and otherwise fell back to universal principles, so a project whose system lives in CSS custom properties, tailwind.config or a theme file got audited and mocked up against an invented aesthetic. The skill now reads code tokens before falling back, and the target-mockup brief reuses the captured colors, fonts, radii and spacing, changing layout only. The contributor's optional microcopy checks (domain vocabulary, human register) are not adopted here. Co-authored-by: Tom Lam Co-authored-by: capy-ai[bot] <230910855+capy-ai[bot]@users.noreply.github.com> --- design-review/SKILL.md | 8 ++++---- design-review/SKILL.md.tmpl | 6 +++--- scripts/resolvers/design.ts | 2 +- test/review-entry-and-design-clarity-au.test.ts | 12 +++++++++++- 4 files changed, 19 insertions(+), 9 deletions(-) diff --git a/design-review/SKILL.md b/design-review/SKILL.md index d4dac091a..48dc45843 100644 --- a/design-review/SKILL.md +++ b/design-review/SKILL.md @@ -403,9 +403,9 @@ You are a senior product designer AND a frontend engineer. Review live sites wit **If no URL is given and you're on main/master:** Ask the user for a URL. -**Check for DESIGN.md:** +**Capture the project's design system:** -Look for `DESIGN.md`, `design-system.md`, or similar in the repo root. If found, read it — all design decisions must be calibrated against it. Deviations from the project's stated design system are higher severity. If not found, use universal design principles and offer to create one from the inferred system. +Look for `DESIGN.md`, `design-system.md`, or similar in the repo root, then for the tokens the code ships: `:root` CSS custom properties, `tailwind.config.*`, and theme or tokens files. Read what exists; Phase 2 adds what the page renders. All design decisions are calibrated against this system, and deviations from it are higher severity. Use universal design principles only when the project has neither a design doc nor code tokens, and offer to create a DESIGN.md from the inferred system. **DESIGN.md format:** @@ -413,7 +413,7 @@ Look for `DESIGN.md`, `design-system.md`, or similar in the repo root. If found, bun --no-env-file run $HOME/.claude/skills/gstack/bin/gstack-design-md.ts check DESIGN.md ``` -`DESIGN_MD_FORMAT: spec`: the front matter is normative. Run `bun --no-env-file run $HOME/.claude/skills/gstack/bin/gstack-design-md.ts tokens DESIGN.md` and calibrate against the flat token map: a value present there is never a finding, and a finding that departs from a token names the token. `legacy` or `unknown`: read the file as prose. The `DESIGN_MD_MARKER` line is the user's persisted format choice; respect it and never offer a conversion here (that is /design-consultation's question). `missing`: universal principles. +`DESIGN_MD_FORMAT: spec`: the front matter is normative. Run `bun --no-env-file run $HOME/.claude/skills/gstack/bin/gstack-design-md.ts tokens DESIGN.md` and calibrate against the flat token map: a value present there is never a finding, and a finding that departs from a token names the token. `legacy` or `unknown`: read the file as prose. The `DESIGN_MD_MARKER` line is the user's persisted format choice; respect it and never offer a conversion here (that is /design-consultation's question). `missing`: calibrate against the code tokens captured above, or universal principles when there are none. **Check for clean working tree:** @@ -1764,7 +1764,7 @@ For each fixable finding, in impact order: ### 8a.5. Target Mockup (if DESIGN_READY) -If the gstack designer is available and the finding involves visual layout, hierarchy, or spacing (not just a CSS value fix like wrong color or font-size), generate a target mockup showing what the corrected version should look like. Write the description of the page or component with the finding fixed, referencing DESIGN.md constraints, into a private file: +If the gstack designer is available and the finding involves visual layout, hierarchy, or spacing (not just a CSS value fix like wrong color or font-size), generate a target mockup showing what the corrected version should look like. Write the description of the page or component with the finding fixed into a private file. The brief reuses the captured system verbatim (the same colors, fonts, radii and spacing scale) and changes layout or structure only; never introduce a new palette or typeface for a product that already has one: ```bash _GT="$(git rev-parse --show-toplevel 2>/dev/null || pwd)/.gstack/tmp" diff --git a/design-review/SKILL.md.tmpl b/design-review/SKILL.md.tmpl index 896e8cc17..4e7960250 100644 --- a/design-review/SKILL.md.tmpl +++ b/design-review/SKILL.md.tmpl @@ -48,9 +48,9 @@ You are a senior product designer AND a frontend engineer. Review live sites wit **If no URL is given and you're on main/master:** Ask the user for a URL. -**Check for DESIGN.md:** +**Capture the project's design system:** -Look for `DESIGN.md`, `design-system.md`, or similar in the repo root. If found, read it — all design decisions must be calibrated against it. Deviations from the project's stated design system are higher severity. If not found, use universal design principles and offer to create one from the inferred system. +Look for `DESIGN.md`, `design-system.md`, or similar in the repo root, then for the tokens the code ships: `:root` CSS custom properties, `tailwind.config.*`, and theme or tokens files. Read what exists; Phase 2 adds what the page renders. All design decisions are calibrated against this system, and deviations from it are higher severity. Use universal design principles only when the project has neither a design doc nor code tokens, and offer to create a DESIGN.md from the inferred system. {{DESIGN_MD_CHECK:calibrate}} @@ -176,7 +176,7 @@ For each fixable finding, in impact order: ### 8a.5. Target Mockup (if DESIGN_READY) -If the gstack designer is available and the finding involves visual layout, hierarchy, or spacing (not just a CSS value fix like wrong color or font-size), generate a target mockup showing what the corrected version should look like. Write the description of the page or component with the finding fixed, referencing DESIGN.md constraints, into a private file: +If the gstack designer is available and the finding involves visual layout, hierarchy, or spacing (not just a CSS value fix like wrong color or font-size), generate a target mockup showing what the corrected version should look like. Write the description of the page or component with the finding fixed into a private file. The brief reuses the captured system verbatim (the same colors, fonts, radii and spacing scale) and changes layout or structure only; never introduce a new palette or typeface for a product that already has one: {{FREE_TEXT_FILE:BRIEF_FILE=brief}} diff --git a/scripts/resolvers/design.ts b/scripts/resolvers/design.ts index 32d90d871..be1e68ba6 100644 --- a/scripts/resolvers/design.ts +++ b/scripts/resolvers/design.ts @@ -982,7 +982,7 @@ ${bin} check DESIGN.md ${check} -\`${SENTINEL.DESIGN_MD_FORMAT}: spec\`: the front matter is normative. Run \`${bin} tokens DESIGN.md\` and calibrate against the flat token map: a value present there is never a finding, and a finding that departs from a token names the token. \`legacy\` or \`unknown\`: read the file as prose. The \`DESIGN_MD_MARKER\` line is the user's persisted format choice; respect it and never offer a conversion here (that is /design-consultation's question). \`missing\`: universal principles.`; +\`${SENTINEL.DESIGN_MD_FORMAT}: spec\`: the front matter is normative. Run \`${bin} tokens DESIGN.md\` and calibrate against the flat token map: a value present there is never a finding, and a finding that departs from a token names the token. \`legacy\` or \`unknown\`: read the file as prose. The \`DESIGN_MD_MARKER\` line is the user's persisted format choice; respect it and never offer a conversion here (that is /design-consultation's question). \`missing\`: calibrate against the code tokens captured above, or universal principles when there are none.`; } return `**Update-only gate:** Only **Update** with DESIGN.md enters this block (command and all result branches). **Start fresh**, **No existing file**, or a lone design-system.md: skip to **Gather product context from the codebase**. **Cancel** has already stopped the skill. diff --git a/test/review-entry-and-design-clarity-au.test.ts b/test/review-entry-and-design-clarity-au.test.ts index ca5093b77..2dfc25ab5 100644 --- a/test/review-entry-and-design-clarity-au.test.ts +++ b/test/review-entry-and-design-clarity-au.test.ts @@ -8,7 +8,7 @@ import {generatePreambleBash} from '../scripts/resolvers/preamble/generate-pream import {generatePlanModeInfo} from '../scripts/resolvers/preamble/generate-completion-status'; import {generateDesignHardRules} from '../scripts/resolvers/design'; import {E2E_TOUCHFILES, LLM_JUDGE_TOUCHFILES, selectTests} from './helpers/touchfiles'; -import { expectMentions } from './helpers/prompt-structure'; +import { between, compact, expectMentions, expectTokens } from './helpers/prompt-structure'; const root = path.resolve(import.meta.dir, '..'); const announcement = 'Scope gate: plan mode — auto-selected B (reviewing ).'; @@ -105,3 +105,13 @@ test('new regression and changed preamble sources select all Design and Eng owne } } }); + +test('design-review captures code tokens before universal principles and reuses them in target mockups', () => { + const skill = fs.readFileSync(path.join(root, 'design-review/SKILL.md'), 'utf8'); + const capture = between(skill, '**Capture the project\'s design system:**', '## Phase 1'); + expectTokens(capture, ['`tailwind.config.*`', '`:root`'], 'design-system capture'); + expectMentions(compact(capture), [['universal', 'only', 'neither', 'code tokens']], 'design-system capture'); + const mockup = compact(between(skill, '### 8a.5. Target Mockup', '### 8b.')); + expectMentions(mockup, [['brief', 'reuses', 'captured', 'colors', 'fonts']], 'target mockup'); + expectMentions(mockup, [['never', 'new palette', 'already has one']], 'target mockup'); +});