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'); +});