mirror of
https://github.com/garrytan/gstack.git
synced 2026-09-09 14:38:59 +02:00
feat(review): generate review/design-checklist.md from the catalog
review/design-checklist.md was hand-written and its own header admitted it drifted from DESIGN_METHODOLOGY category 9. It is now rendered by scripts/resolvers/design-checklist.ts from lib/design-catalog.ts: category 1 lists every grep-detectable slop entry plus the legacy blacklist lines, sorted HIGH/MEDIUM/LOW, each with its heuristic and, where the detector knows the rule, its bracketed id (27 items, up from 6). The font blacklist renders from BANNED_FONTS. Categories 2-5, Instructions, Classification, Output Format, and Suppressions keep their prose. Title and slop heading are unchanged (test/skill-e2e-review.test.ts and hosts/opencode.ts key on them). gen-skill-docs writes the file for the Claude host only (a Claude-side runtime asset; other hosts copy or inline the render), honors --out-dir, and reports STALE/FRESH under --dry-run like sections do. test/design-checklist-sync.test.ts pins committed == generated, the host/out-dir scoping, and the dry-run freshness line. Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
This commit is contained in:
Garry Tan
co-authored by
Claude Fable 5.1
Claude Fable 5.1
parent
e34541c3bd
commit
11c2a33ae9
@@ -11,6 +11,7 @@
|
||||
|
||||
import { discoverTemplates, discoverSectionTemplates } from './discover-skills';
|
||||
import { writeLlmsTxt } from './gen-llms-txt';
|
||||
import { generateDesignChecklistMd } from './resolvers/design-checklist';
|
||||
import * as fs from 'fs';
|
||||
import * as path from 'path';
|
||||
import type { Host, TemplateContext } from './resolvers/types';
|
||||
@@ -1103,6 +1104,32 @@ for (const currentHost of hostsToRun) {
|
||||
});
|
||||
}
|
||||
|
||||
// ─── review/design-checklist.md (generated from lib/design-catalog.ts) ───
|
||||
// A Claude-side runtime asset: setup links it from review/ and the other
|
||||
// hosts copy or inline the Claude render (hosts/opencode.ts), so it is
|
||||
// written for the CLAUDE host only. Honors OUT_DIR (outputs-only rule) and
|
||||
// takes part in the DRY_RUN freshness gate exactly like sections above.
|
||||
if (currentHost === 'claude'
|
||||
&& !(currentHostConfig.generation.includeSkills?.length && !currentHostConfig.generation.includeSkills.includes('review'))
|
||||
&& !currentHostConfig.generation.skipSkills?.includes('review')) {
|
||||
const outputPath = path.join(OUT_DIR ?? ROOT, 'review', 'design-checklist.md');
|
||||
const relOutput = path.relative(OUT_DIR || ROOT, outputPath);
|
||||
const content = generateDesignChecklistMd();
|
||||
if (DRY_RUN) {
|
||||
const existing = fs.existsSync(outputPath) ? fs.readFileSync(outputPath, 'utf-8') : '';
|
||||
if (existing !== content) {
|
||||
console.log(`STALE: ${relOutput}`);
|
||||
hasChanges = true;
|
||||
} else {
|
||||
console.log(`FRESH: ${relOutput}`);
|
||||
}
|
||||
} else {
|
||||
if (OUT_DIR) fs.mkdirSync(path.dirname(outputPath), { recursive: true });
|
||||
fs.writeFileSync(outputPath, content);
|
||||
console.log(`GENERATED: ${relOutput}`);
|
||||
}
|
||||
}
|
||||
|
||||
// Generate the OpenClaw orchestrator-injection docs (gstack-lite / gstack-full /
|
||||
// gstack-plan CLAUDE.md snippets). Sources live in openclaw/templates/ —
|
||||
// plain markdown, no placeholder resolution — and are copied byte-for-byte
|
||||
|
||||
@@ -0,0 +1,182 @@
|
||||
/**
|
||||
* Design checklist resolver — renders review/design-checklist.md from the catalog.
|
||||
*
|
||||
* The checklist is the one artifact both /review (Review Army Design specialist)
|
||||
* and /ship (DESIGN_REVIEW_LITE) read at runtime. It used to be hand-written
|
||||
* and its own header admitted it drifted from DESIGN_METHODOLOGY category 9.
|
||||
* Now category 1 renders from lib/design-catalog.ts (the same entries category
|
||||
* 9 renders), the font blacklist renders from BANNED_FONTS, and everything else
|
||||
* is fixed prose kept here. gen-skill-docs writes the file for the Claude host
|
||||
* only (it is a Claude-side runtime asset; other hosts copy or inline the
|
||||
* Claude render), honors --out-dir, and reports STALE/FRESH under --dry-run.
|
||||
*
|
||||
* Derived in part from pbakaus/impeccable (Apache-2.0), modified. See NOTICE.md.
|
||||
*/
|
||||
import { DESIGN_SLOP_CATALOG, BANNED_FONTS, type DesignSlopEntry } from '../../lib/design-catalog';
|
||||
|
||||
export const DESIGN_CHECKLIST_HEADER =
|
||||
'<!-- GENERATED from lib/design-catalog.ts via scripts/resolvers/design-checklist.ts. Run: bun run gen:skill-docs -->';
|
||||
|
||||
/** Title and category heading are load-bearing: test/skill-e2e-review.test.ts and hosts/opencode.ts key on them. */
|
||||
export const DESIGN_CHECKLIST_TITLE = 'Design Review Checklist (Lite)';
|
||||
export const DESIGN_CHECKLIST_SLOP_HEADING = 'AI Slop Detection';
|
||||
|
||||
const TIER_ORDER: Record<DesignSlopEntry['confidence'], number> = { HIGH: 0, MEDIUM: 1, LOW: 2 };
|
||||
|
||||
/** Category 1: slop entries a code reader can grep for, plus the legacy blacklist lines. */
|
||||
export function checklistSlopEntries(): DesignSlopEntry[] {
|
||||
return DESIGN_SLOP_CATALOG
|
||||
.filter(e => e.kind === 'slop' && (e.detect.includes('grep') || e.legacyBlacklist))
|
||||
.map((e, i) => ({ e, i }))
|
||||
.sort((a, b) => (TIER_ORDER[a.e.confidence] - TIER_ORDER[b.e.confidence]) || (a.i - b.i))
|
||||
.map(x => x.e);
|
||||
}
|
||||
|
||||
function endsWithPunctuation(s: string): boolean {
|
||||
return /[.!?]$/.test(s.trim());
|
||||
}
|
||||
|
||||
function renderSlopItem(e: DesignSlopEntry): string {
|
||||
const id = e.impeccableId ? ` [${e.impeccableId}]` : '';
|
||||
const prose = endsWithPunctuation(e.prose) ? e.prose : `${e.prose}.`;
|
||||
const heuristic = e.heuristic ? ` ${e.heuristic}` : '';
|
||||
const values = e.values ? ` Faces: ${e.values.join(', ')}.` : '';
|
||||
return `- **[${e.confidence}]**${id} ${prose}${heuristic}${values}`;
|
||||
}
|
||||
|
||||
/** Font names without role qualifiers, for a grep. */
|
||||
function bannedFontNames(): string[] {
|
||||
return BANNED_FONTS.map(f => f.replace(/\s*\(.*\)$/, ''));
|
||||
}
|
||||
|
||||
export function generateDesignChecklistMd(): string {
|
||||
const slop = checklistSlopEntries();
|
||||
return `${DESIGN_CHECKLIST_HEADER}
|
||||
# ${DESIGN_CHECKLIST_TITLE}
|
||||
|
||||
> **Generated from the catalog.** Category 1 renders the grep-detectable slop entries of \`lib/design-catalog.ts\`, the same entries DESIGN_METHODOLOGY category 9 renders, so the two cannot drift. Edit the catalog, then run \`bun run gen:skill-docs\`.
|
||||
|
||||
## Instructions
|
||||
|
||||
This checklist applies to **source code in the diff** — not rendered output. Read each changed frontend file (full file, not just diff hunks) and flag anti-patterns.
|
||||
|
||||
**Trigger:** Only run this checklist if the diff touches frontend files. Use \`gstack-diff-scope\` to detect:
|
||||
|
||||
\`\`\`bash
|
||||
source <(~/.claude/skills/gstack/bin/gstack-diff-scope <base> 2>/dev/null)
|
||||
\`\`\`
|
||||
|
||||
If \`SCOPE_FRONTEND=false\`, skip the entire design review silently.
|
||||
|
||||
**DESIGN.md calibration:** If \`DESIGN.md\` or \`design-system.md\` exists in the repo root, read it first. All findings are calibrated against the project's stated design system. Patterns explicitly blessed in DESIGN.md are NOT flagged. If no DESIGN.md exists, use universal design principles.
|
||||
|
||||
---
|
||||
|
||||
## Confidence Tiers
|
||||
|
||||
Each item is tagged with a detection confidence level:
|
||||
|
||||
- **[HIGH]** — Reliably detectable via grep/pattern match. Definitive findings.
|
||||
- **[MEDIUM]** — Detectable via pattern aggregation or heuristic. Flag as findings but expect some noise.
|
||||
- **[LOW]** — Requires understanding visual intent. Present as: "Possible issue — verify visually or run /design-review."
|
||||
|
||||
A bracketed \`[rule-id]\` names the deterministic detector rule for the same pattern; a hit from the detector and a hit from this checklist at the same file:line are one finding.
|
||||
|
||||
---
|
||||
|
||||
## Classification
|
||||
|
||||
**AUTO-FIX** (mechanical CSS fixes only — HIGH confidence, no design judgment needed):
|
||||
- \`outline: none\` without replacement → add \`outline: revert\` or \`&:focus-visible { outline: 2px solid currentColor; }\`
|
||||
- \`!important\` in new CSS → remove and fix specificity
|
||||
- \`font-size\` < 16px on body text → bump to 16px
|
||||
|
||||
**ASK** (everything else — requires design judgment):
|
||||
- All AI slop findings, typography structure, spacing choices, interaction state gaps, DESIGN.md violations
|
||||
|
||||
**LOW confidence items** → present as "Possible: [description]. Verify visually or run /design-review." Never AUTO-FIX.
|
||||
|
||||
---
|
||||
|
||||
## Output Format
|
||||
|
||||
\`\`\`
|
||||
Design Review: N issues (X auto-fixable, Y need input, Z possible)
|
||||
|
||||
**AUTO-FIXED:**
|
||||
- [file:line] Problem → fix applied
|
||||
|
||||
**NEEDS INPUT:**
|
||||
- [file:line] Problem description
|
||||
Recommended fix: suggested fix
|
||||
|
||||
**POSSIBLE (verify visually):**
|
||||
- [file:line] Possible issue — verify with /design-review
|
||||
\`\`\`
|
||||
|
||||
Optional: \`test_stub\` — skeleton test code for this finding using the project's test framework.
|
||||
|
||||
If no issues found: \`Design Review: No issues found.\`
|
||||
|
||||
If no frontend files changed: skip silently, no output.
|
||||
|
||||
---
|
||||
|
||||
## Categories
|
||||
|
||||
### 1. ${DESIGN_CHECKLIST_SLOP_HEADING} (${slop.length} items) — highest priority
|
||||
|
||||
These are the telltale signs of AI-generated UI that no designer at a respected studio would ship.
|
||||
|
||||
${slop.map(renderSlopItem).join('\n\n')}
|
||||
|
||||
### 2. Typography (4 items)
|
||||
|
||||
- **[HIGH]** Body text \`font-size\` < 16px. Grep for \`font-size\` declarations on \`body\`, \`p\`, \`.text\`, or base styles. Values below 16px (or 1rem when base is 16px) are flagged.
|
||||
|
||||
- **[HIGH]** More than 3 font families introduced in the diff. Count distinct \`font-family\` declarations. Flag if >3 unique families appear across changed files.
|
||||
|
||||
- **[HIGH]** Heading hierarchy skipping levels: \`h1\` followed by \`h3\` without an \`h2\` in the same file/component. Check HTML/JSX for heading tags.
|
||||
|
||||
- **[HIGH]** Blacklisted fonts: ${bannedFontNames().join(', ')}. Grep \`font-family\` for these names.
|
||||
|
||||
### 3. Spacing & Layout (4 items)
|
||||
|
||||
- **[MEDIUM]** Arbitrary spacing values not on a 4px or 8px scale, when DESIGN.md specifies a spacing scale. Check \`margin\`, \`padding\`, \`gap\` values against the stated scale. Only flag when DESIGN.md defines a scale.
|
||||
|
||||
- **[MEDIUM]** Fixed widths without responsive handling: \`width: NNNpx\` on containers without \`max-width\` or \`@media\` breakpoints. Risk of horizontal scroll on mobile.
|
||||
|
||||
- **[MEDIUM]** Missing \`max-width\` on text containers: body text or paragraph containers with no \`max-width\` set, allowing lines >75 characters. Check for \`max-width\` on text wrappers.
|
||||
|
||||
- **[HIGH]** \`!important\` in new CSS rules. Grep for \`!important\` in added lines. Almost always a specificity escape hatch that should be fixed properly.
|
||||
|
||||
### 4. Interaction States (3 items)
|
||||
|
||||
- **[MEDIUM]** Interactive elements (buttons, links, inputs) missing hover/focus states. Check if \`:hover\` and \`:focus\` or \`:focus-visible\` pseudo-classes exist for new interactive element styles.
|
||||
|
||||
- **[HIGH]** \`outline: none\` or \`outline: 0\` without a replacement focus indicator. Grep for \`outline:\\s*none\` or \`outline:\\s*0\`. This removes keyboard accessibility.
|
||||
|
||||
- **[LOW]** Touch targets < 44px on interactive elements. Check \`min-height\`/\`min-width\`/\`padding\` on buttons and links. Requires computing effective size from multiple properties — low confidence from code alone.
|
||||
|
||||
### 5. DESIGN.md Violations (3 items, conditional)
|
||||
|
||||
Only apply if \`DESIGN.md\` or \`design-system.md\` exists:
|
||||
|
||||
- **[MEDIUM]** Colors not in the stated palette. Compare color values in changed CSS against the palette defined in DESIGN.md.
|
||||
|
||||
- **[MEDIUM]** Fonts not in the stated typography section. Compare \`font-family\` values against DESIGN.md's font list.
|
||||
|
||||
- **[MEDIUM]** Spacing values outside the stated scale. Compare \`margin\`/\`padding\`/\`gap\` values against DESIGN.md's spacing scale.
|
||||
|
||||
---
|
||||
|
||||
## Suppressions
|
||||
|
||||
Do NOT flag:
|
||||
- Patterns explicitly documented in DESIGN.md as intentional choices
|
||||
- Third-party/vendor CSS files (node_modules, vendor directories)
|
||||
- CSS resets or normalize stylesheets
|
||||
- Test fixture files
|
||||
- Generated/minified CSS
|
||||
`;
|
||||
}
|
||||
@@ -64,8 +64,9 @@ ${ctx.paths.binDir}/gstack-review-log '{"skill":"design-review-lite","timestamp"
|
||||
Substitute: TIMESTAMP = ISO 8601 datetime, STATUS = "clean" if 0 findings or "issues_found", N = total findings, M = auto-fixed count, COMMIT = output of \`git rev-parse --short HEAD\`.${codexBlock}`;
|
||||
}
|
||||
|
||||
// NOTE: design-checklist.md is a subset of this methodology for code-level detection.
|
||||
// When adding items here, also update review/design-checklist.md, and vice versa.
|
||||
// NOTE: review/design-checklist.md is GENERATED (scripts/resolvers/design-checklist.ts)
|
||||
// from lib/design-catalog.ts, the same catalog category 9 below renders. Edit the
|
||||
// catalog, never the checklist; gen-skill-docs rewrites it.
|
||||
export function generateDesignMethodology(_ctx: TemplateContext): string {
|
||||
return `## Modes
|
||||
|
||||
|
||||
Reference in New Issue
Block a user