From 3a1265b81181c78363660c082384f707b15e467d Mon Sep 17 00:00:00 2001 From: Garry Tan Date: Sun, 22 Mar 2026 19:18:05 -0700 Subject: [PATCH] feat(design skills): add outside voices + hard rules to all design templates Insert {{DESIGN_OUTSIDE_VOICES}} in plan-design-review (between Step 0D and Pass 1), design-review (between Phase 6 and Phase 7), and design-consultation (between Phase 2 and Phase 3). Insert {{DESIGN_HARD_RULES}} in plan-design-review Pass 4 and design-review Phase 3 checklist. DESIGN_REVIEW_LITE in /ship and /review now includes a Codex design voice block with litmus checks. DESIGN_SKETCH in /office-hours now includes outside voices opt-in after wireframe approval. Regenerated all SKILL.md files (both Claude and Codex hosts). Co-Authored-By: Claude Opus 4.6 (1M context) --- .../gstack-design-consultation/SKILL.md | 2 + .agents/skills/gstack-design-review/SKILL.md | 71 +++++++ .agents/skills/gstack-office-hours/SKILL.md | 29 +++ .../skills/gstack-plan-design-review/SKILL.md | 71 +++++++ design-consultation/SKILL.md | 65 +++++++ design-consultation/SKILL.md.tmpl | 2 + design-review/SKILL.md | 150 +++++++++++++++ design-review/SKILL.md.tmpl | 4 + office-hours/SKILL.md | 29 +++ plan-design-review/SKILL.md | 176 ++++++++++++++++++ plan-design-review/SKILL.md.tmpl | 4 + review/SKILL.md | 22 +++ ship/SKILL.md | 22 +++ 13 files changed, 647 insertions(+) diff --git a/.agents/skills/gstack-design-consultation/SKILL.md b/.agents/skills/gstack-design-consultation/SKILL.md index 88394a31..1ea0f75a 100644 --- a/.agents/skills/gstack-design-consultation/SKILL.md +++ b/.agents/skills/gstack-design-consultation/SKILL.md @@ -413,6 +413,8 @@ If the user said no research, skip entirely and proceed to Phase 3 using your bu --- + + ## Phase 3: The Complete Proposal This is the soul of the skill. Propose EVERYTHING as one coherent package. diff --git a/.agents/skills/gstack-design-review/SKILL.md b/.agents/skills/gstack-design-review/SKILL.md index 1cd8409a..8a91aadc 100644 --- a/.agents/skills/gstack-design-review/SKILL.md +++ b/.agents/skills/gstack-design-review/SKILL.md @@ -846,6 +846,75 @@ Tie everything to user goals and product objectives. Always suggest specific imp 10. **Depth over breadth.** 5-10 well-documented findings with screenshots and specific suggestions > 20 vague observations. 11. **Show screenshots to the user.** After every `$B screenshot`, `$B snapshot -a -o`, or `$B responsive` command, use the Read tool on the output file(s) so the user can see them inline. For `responsive` (3 files), Read all three. This is critical — without it, screenshots are invisible to the user. +### Design Hard Rules + +**Classifier — determine rule set before evaluating:** +- **MARKETING/LANDING PAGE** (hero-driven, brand-forward, conversion-focused) → apply Landing Page Rules +- **APP UI** (workspace-driven, data-dense, task-focused: dashboards, admin, settings) → apply App UI Rules +- **HYBRID** (marketing shell with app-like sections) → apply Landing Page Rules to hero/marketing sections, App UI Rules to functional sections + +**Hard rejection criteria** (instant-fail patterns — flag if ANY apply): +1. Generic SaaS card grid as first impression +2. Beautiful image with weak brand +3. Strong headline with no clear action +4. Busy imagery behind text +5. Sections repeating same mood statement +6. Carousel with no narrative purpose +7. App UI made of stacked cards instead of layout + +**Litmus checks** (answer YES/NO for each — used for cross-model consensus scoring): +1. Brand/product unmistakable in first screen? +2. One strong visual anchor present? +3. Page understandable by scanning headlines only? +4. Each section has one job? +5. Are cards actually necessary? +6. Does motion improve hierarchy or atmosphere? +7. Would design feel premium with all decorative shadows removed? + +**Landing page rules** (apply when classifier = MARKETING/LANDING): +- First viewport reads as one composition, not a dashboard +- Brand-first hierarchy: brand > headline > body > CTA +- Typography: expressive, purposeful — no default stacks (Inter, Roboto, Arial, system) +- No flat single-color backgrounds — use gradients, images, subtle patterns +- Hero: full-bleed, edge-to-edge, no inset/tiled/rounded variants +- Hero budget: brand, one headline, one supporting sentence, one CTA group, one image +- No cards in hero. Cards only when card IS the interaction +- One job per section: one purpose, one headline, one short supporting sentence +- Motion: 2-3 intentional motions minimum (entrance, scroll-linked, hover/reveal) +- Color: define CSS variables, avoid purple-on-white defaults, one accent color default +- Copy: product language not design commentary. "If deleting 30% improves it, keep deleting" +- Beautiful defaults: composition-first, brand as loudest text, two typefaces max, cardless by default, first viewport as poster not document + +**App UI rules** (apply when classifier = APP UI): +- Calm surface hierarchy, strong typography, few colors +- Dense but readable, minimal chrome +- Organize: primary workspace, navigation, secondary context, one accent +- Avoid: dashboard-card mosaics, thick borders, decorative gradients, ornamental icons +- Copy: utility language — orientation, status, action. Not mood/brand/aspiration +- Cards only when card IS the interaction +- Section headings state what area is or what user can do ("Selected KPIs", "Plan status") + +**Universal rules** (apply to ALL types): +- Define CSS variables for color system +- No default font stacks (Inter, Roboto, Arial, system) +- One job per section +- "If deleting 30% of the copy improves it, keep deleting" +- Cards earn their existence — no decorative card grids + +**AI Slop blacklist** (the 10 patterns that scream "AI-generated"): +1. Purple/violet/indigo gradient backgrounds or blue-to-purple color schemes +2. **The 3-column feature grid:** icon-in-colored-circle + bold title + 2-line description, repeated 3x symmetrically. THE most recognizable AI layout. +3. Icons in colored circles as section decoration (SaaS starter template look) +4. Centered everything (`text-align: center` on all headings, descriptions, cards) +5. Uniform bubbly border-radius on every element (same large radius on everything) +6. Decorative blobs, floating circles, wavy SVG dividers (if a section feels empty, it needs better content, not decoration) +7. Emoji as design elements (rockets in headings, emoji as bullet points) +8. Colored left-border on cards (`border-left: 3px solid `) +9. Generic hero copy ("Welcome to [X]", "Unlock the power of...", "Your all-in-one solution for...") +10. Cookie-cutter section rhythm (hero → 3 features → testimonials → pricing → CTA, every section same height) + +Source: [OpenAI "Designing Delightful Frontends with GPT-5.4"](https://developers.openai.com/blog/designing-delightful-frontends-with-gpt-5-4) (Mar 2026) + gstack design methodology. + Record baseline design score and AI slop score at end of Phase 6. --- @@ -869,6 +938,8 @@ Record baseline design score and AI slop score at end of Phase 6. --- + + ## Phase 7: Triage Sort all discovered findings by impact, then decide which to fix: diff --git a/.agents/skills/gstack-office-hours/SKILL.md b/.agents/skills/gstack-office-hours/SKILL.md index a614c6e5..8f9560d3 100644 --- a/.agents/skills/gstack-office-hours/SKILL.md +++ b/.agents/skills/gstack-office-hours/SKILL.md @@ -721,6 +721,35 @@ Reference the wireframe screenshot in the design doc's "Recommended Approach" se The screenshot file at `/tmp/gstack-sketch.png` can be referenced by downstream skills (`/plan-design-review`, `/design-review`) to see what was originally envisioned. +**Step 6: Outside design voices** (optional) + +After the wireframe is approved, offer outside design perspectives: + +```bash +which codex 2>/dev/null && echo "CODEX_AVAILABLE" || echo "CODEX_NOT_AVAILABLE" +``` + +If Codex is available, use AskUserQuestion: +> "Want outside design perspectives on the chosen approach? Codex proposes a visual thesis, content plan, and interaction ideas. A Claude subagent proposes an alternative aesthetic direction." +> +> A) Yes — get outside design voices +> B) No — proceed without + +If user chooses A, launch both voices simultaneously: + +1. **Codex** (via Bash, `model_reasoning_effort="medium"`): +```bash +TMPERR_SKETCH=$(mktemp /tmp/codex-sketch-XXXXXXXX) +codex exec "For this product approach, provide: a visual thesis (one sentence — mood, material, energy), a content plan (hero → support → detail → CTA), and 2 interaction ideas that change page feel. Apply beautiful defaults: composition-first, brand-first, cardless, poster not document. Be opinionated." -s read-only -c 'model_reasoning_effort="medium"' --enable web_search_cached 2>"$TMPERR_SKETCH" +``` +Use a 5-minute timeout (`timeout: 300000`). After completion: `cat "$TMPERR_SKETCH" && rm -f "$TMPERR_SKETCH"` + +2. **Claude subagent** (via Agent tool): +"For this product approach, what design direction would you recommend? What aesthetic, typography, and interaction patterns fit? What would make this approach feel inevitable to the user? Be specific — font names, hex colors, spacing values." + +Present Codex output under `CODEX SAYS (design sketch):` and subagent output under `CLAUDE SUBAGENT (design direction):`. +Error handling: all non-blocking. On failure, skip and continue. + --- ## Phase 4.5: Founder Signal Synthesis diff --git a/.agents/skills/gstack-plan-design-review/SKILL.md b/.agents/skills/gstack-plan-design-review/SKILL.md index a36599b0..e6abfd81 100644 --- a/.agents/skills/gstack-plan-design-review/SKILL.md +++ b/.agents/skills/gstack-plan-design-review/SKILL.md @@ -412,6 +412,8 @@ AskUserQuestion: "I've rated this plan {N}/10 on design completeness. The bigges **STOP.** Do NOT proceed until user responds. + + ## The 0-10 Rating Method For each design section, rate the plan 0-10 on that dimension. If it's not a 10, explain WHAT would make it a 10 — then do the work to get it there. @@ -460,6 +462,75 @@ Apply time-horizon design: 5-sec visceral, 5-min behavioral, 5-year reflective. ### Pass 4: AI Slop Risk Rate 0-10: Does the plan describe specific, intentional UI — or generic patterns? FIX TO 10: Rewrite vague UI descriptions with specific alternatives. + +### Design Hard Rules + +**Classifier — determine rule set before evaluating:** +- **MARKETING/LANDING PAGE** (hero-driven, brand-forward, conversion-focused) → apply Landing Page Rules +- **APP UI** (workspace-driven, data-dense, task-focused: dashboards, admin, settings) → apply App UI Rules +- **HYBRID** (marketing shell with app-like sections) → apply Landing Page Rules to hero/marketing sections, App UI Rules to functional sections + +**Hard rejection criteria** (instant-fail patterns — flag if ANY apply): +1. Generic SaaS card grid as first impression +2. Beautiful image with weak brand +3. Strong headline with no clear action +4. Busy imagery behind text +5. Sections repeating same mood statement +6. Carousel with no narrative purpose +7. App UI made of stacked cards instead of layout + +**Litmus checks** (answer YES/NO for each — used for cross-model consensus scoring): +1. Brand/product unmistakable in first screen? +2. One strong visual anchor present? +3. Page understandable by scanning headlines only? +4. Each section has one job? +5. Are cards actually necessary? +6. Does motion improve hierarchy or atmosphere? +7. Would design feel premium with all decorative shadows removed? + +**Landing page rules** (apply when classifier = MARKETING/LANDING): +- First viewport reads as one composition, not a dashboard +- Brand-first hierarchy: brand > headline > body > CTA +- Typography: expressive, purposeful — no default stacks (Inter, Roboto, Arial, system) +- No flat single-color backgrounds — use gradients, images, subtle patterns +- Hero: full-bleed, edge-to-edge, no inset/tiled/rounded variants +- Hero budget: brand, one headline, one supporting sentence, one CTA group, one image +- No cards in hero. Cards only when card IS the interaction +- One job per section: one purpose, one headline, one short supporting sentence +- Motion: 2-3 intentional motions minimum (entrance, scroll-linked, hover/reveal) +- Color: define CSS variables, avoid purple-on-white defaults, one accent color default +- Copy: product language not design commentary. "If deleting 30% improves it, keep deleting" +- Beautiful defaults: composition-first, brand as loudest text, two typefaces max, cardless by default, first viewport as poster not document + +**App UI rules** (apply when classifier = APP UI): +- Calm surface hierarchy, strong typography, few colors +- Dense but readable, minimal chrome +- Organize: primary workspace, navigation, secondary context, one accent +- Avoid: dashboard-card mosaics, thick borders, decorative gradients, ornamental icons +- Copy: utility language — orientation, status, action. Not mood/brand/aspiration +- Cards only when card IS the interaction +- Section headings state what area is or what user can do ("Selected KPIs", "Plan status") + +**Universal rules** (apply to ALL types): +- Define CSS variables for color system +- No default font stacks (Inter, Roboto, Arial, system) +- One job per section +- "If deleting 30% of the copy improves it, keep deleting" +- Cards earn their existence — no decorative card grids + +**AI Slop blacklist** (the 10 patterns that scream "AI-generated"): +1. Purple/violet/indigo gradient backgrounds or blue-to-purple color schemes +2. **The 3-column feature grid:** icon-in-colored-circle + bold title + 2-line description, repeated 3x symmetrically. THE most recognizable AI layout. +3. Icons in colored circles as section decoration (SaaS starter template look) +4. Centered everything (`text-align: center` on all headings, descriptions, cards) +5. Uniform bubbly border-radius on every element (same large radius on everything) +6. Decorative blobs, floating circles, wavy SVG dividers (if a section feels empty, it needs better content, not decoration) +7. Emoji as design elements (rockets in headings, emoji as bullet points) +8. Colored left-border on cards (`border-left: 3px solid `) +9. Generic hero copy ("Welcome to [X]", "Unlock the power of...", "Your all-in-one solution for...") +10. Cookie-cutter section rhythm (hero → 3 features → testimonials → pricing → CTA, every section same height) + +Source: [OpenAI "Designing Delightful Frontends with GPT-5.4"](https://developers.openai.com/blog/designing-delightful-frontends-with-gpt-5-4) (Mar 2026) + gstack design methodology. - "Cards with icons" → what differentiates these from every SaaS template? - "Hero section" → what makes this hero feel like THIS product? - "Clean, modern UI" → meaningless. Replace with actual design decisions. diff --git a/design-consultation/SKILL.md b/design-consultation/SKILL.md index 183913c0..d4cf72b2 100644 --- a/design-consultation/SKILL.md +++ b/design-consultation/SKILL.md @@ -423,6 +423,71 @@ If the user said no research, skip entirely and proceed to Phase 3 using your bu --- +## Design Outside Voices (parallel) + +Use AskUserQuestion: +> "Want outside design voices? Codex evaluates against OpenAI's design hard rules + litmus checks; Claude subagent does an independent design direction proposal." +> +> A) Yes — run outside design voices +> B) No — proceed without + +If user chooses B, skip this step and continue. + +**Check Codex availability:** +```bash +which codex 2>/dev/null && echo "CODEX_AVAILABLE" || echo "CODEX_NOT_AVAILABLE" +``` + +**If Codex is available**, launch both voices simultaneously: + +1. **Codex design voice** (via Bash): +```bash +TMPERR_DESIGN=$(mktemp /tmp/codex-design-XXXXXXXX) +codex exec "Given this product context, propose a complete design direction: +- Visual thesis: one sentence describing mood, material, and energy +- Typography: specific font names (not defaults — no Inter/Roboto/Arial/system) + hex colors +- Color system: CSS variables for background, surface, primary text, muted text, accent +- Layout: composition-first, not component-first. First viewport as poster, not document +- Differentiation: 2 deliberate departures from category norms +- Anti-slop: no purple gradients, no 3-column icon grids, no centered everything, no decorative blobs + +Be opinionated. Be specific. Do not hedge. This is YOUR design direction — own it." -s read-only -c 'model_reasoning_effort="medium"' --enable web_search_cached 2>"$TMPERR_DESIGN" +``` +Use a 5-minute timeout (`timeout: 300000`). After the command completes, read stderr: +```bash +cat "$TMPERR_DESIGN" && rm -f "$TMPERR_DESIGN" +``` + +2. **Claude design subagent** (via Agent tool): +Dispatch a subagent with this prompt: +"Given this product context, propose a design direction that would SURPRISE. What would the cool indie studio do that the enterprise UI team wouldn't? +- Propose an aesthetic direction, typography stack (specific font names), color palette (hex values) +- 2 deliberate departures from category norms +- What emotional reaction should the user have in the first 3 seconds? + +Be bold. Be specific. No hedging." + +**Error handling (all non-blocking):** +- **Auth failure:** If stderr contains "auth", "login", "unauthorized", or "API key": "Codex authentication failed. Run `codex login` to authenticate." +- **Timeout:** "Codex timed out after 5 minutes." +- **Empty response:** "Codex returned no response." +- On any Codex error: proceed with Claude subagent output only, tagged `[single-model]`. +- If Claude subagent also fails: "Outside voices unavailable — continuing with primary review." + +Present Codex output under a `CODEX SAYS (design direction):` header. +Present subagent output under a `CLAUDE SUBAGENT (design direction):` header. + +**Synthesis:** Claude main references both Codex and subagent proposals in the Phase 3 proposal. Present: +- Areas of agreement between all three voices (Claude main + Codex + subagent) +- Genuine divergences as creative alternatives for the user to choose from +- "Codex and I agree on X. Codex suggested Y where I'm proposing Z — here's why..." + +**Log the result:** +```bash +~/.claude/skills/gstack/bin/gstack-review-log '{"skill":"design-outside-voices","timestamp":"'"$(date -u +%Y-%m-%dT%H:%M:%SZ)"'","status":"STATUS","source":"SOURCE","commit":"'"$(git rev-parse --short HEAD)"'"}' +``` +Replace STATUS with "clean" or "issues_found", SOURCE with "codex+subagent", "codex-only", "subagent-only", or "unavailable". + ## Phase 3: The Complete Proposal This is the soul of the skill. Propose EVERYTHING as one coherent package. diff --git a/design-consultation/SKILL.md.tmpl b/design-consultation/SKILL.md.tmpl index ed9a4efa..87c191df 100644 --- a/design-consultation/SKILL.md.tmpl +++ b/design-consultation/SKILL.md.tmpl @@ -131,6 +131,8 @@ If the user said no research, skip entirely and proceed to Phase 3 using your bu --- +{{DESIGN_OUTSIDE_VOICES}} + ## Phase 3: The Complete Proposal This is the soul of the skill. Propose EVERYTHING as one coherent package. diff --git a/design-review/SKILL.md b/design-review/SKILL.md index 34c7b543..ae8fa1bd 100644 --- a/design-review/SKILL.md +++ b/design-review/SKILL.md @@ -856,6 +856,75 @@ Tie everything to user goals and product objectives. Always suggest specific imp 10. **Depth over breadth.** 5-10 well-documented findings with screenshots and specific suggestions > 20 vague observations. 11. **Show screenshots to the user.** After every `$B screenshot`, `$B snapshot -a -o`, or `$B responsive` command, use the Read tool on the output file(s) so the user can see them inline. For `responsive` (3 files), Read all three. This is critical — without it, screenshots are invisible to the user. +### Design Hard Rules + +**Classifier — determine rule set before evaluating:** +- **MARKETING/LANDING PAGE** (hero-driven, brand-forward, conversion-focused) → apply Landing Page Rules +- **APP UI** (workspace-driven, data-dense, task-focused: dashboards, admin, settings) → apply App UI Rules +- **HYBRID** (marketing shell with app-like sections) → apply Landing Page Rules to hero/marketing sections, App UI Rules to functional sections + +**Hard rejection criteria** (instant-fail patterns — flag if ANY apply): +1. Generic SaaS card grid as first impression +2. Beautiful image with weak brand +3. Strong headline with no clear action +4. Busy imagery behind text +5. Sections repeating same mood statement +6. Carousel with no narrative purpose +7. App UI made of stacked cards instead of layout + +**Litmus checks** (answer YES/NO for each — used for cross-model consensus scoring): +1. Brand/product unmistakable in first screen? +2. One strong visual anchor present? +3. Page understandable by scanning headlines only? +4. Each section has one job? +5. Are cards actually necessary? +6. Does motion improve hierarchy or atmosphere? +7. Would design feel premium with all decorative shadows removed? + +**Landing page rules** (apply when classifier = MARKETING/LANDING): +- First viewport reads as one composition, not a dashboard +- Brand-first hierarchy: brand > headline > body > CTA +- Typography: expressive, purposeful — no default stacks (Inter, Roboto, Arial, system) +- No flat single-color backgrounds — use gradients, images, subtle patterns +- Hero: full-bleed, edge-to-edge, no inset/tiled/rounded variants +- Hero budget: brand, one headline, one supporting sentence, one CTA group, one image +- No cards in hero. Cards only when card IS the interaction +- One job per section: one purpose, one headline, one short supporting sentence +- Motion: 2-3 intentional motions minimum (entrance, scroll-linked, hover/reveal) +- Color: define CSS variables, avoid purple-on-white defaults, one accent color default +- Copy: product language not design commentary. "If deleting 30% improves it, keep deleting" +- Beautiful defaults: composition-first, brand as loudest text, two typefaces max, cardless by default, first viewport as poster not document + +**App UI rules** (apply when classifier = APP UI): +- Calm surface hierarchy, strong typography, few colors +- Dense but readable, minimal chrome +- Organize: primary workspace, navigation, secondary context, one accent +- Avoid: dashboard-card mosaics, thick borders, decorative gradients, ornamental icons +- Copy: utility language — orientation, status, action. Not mood/brand/aspiration +- Cards only when card IS the interaction +- Section headings state what area is or what user can do ("Selected KPIs", "Plan status") + +**Universal rules** (apply to ALL types): +- Define CSS variables for color system +- No default font stacks (Inter, Roboto, Arial, system) +- One job per section +- "If deleting 30% of the copy improves it, keep deleting" +- Cards earn their existence — no decorative card grids + +**AI Slop blacklist** (the 10 patterns that scream "AI-generated"): +1. Purple/violet/indigo gradient backgrounds or blue-to-purple color schemes +2. **The 3-column feature grid:** icon-in-colored-circle + bold title + 2-line description, repeated 3x symmetrically. THE most recognizable AI layout. +3. Icons in colored circles as section decoration (SaaS starter template look) +4. Centered everything (`text-align: center` on all headings, descriptions, cards) +5. Uniform bubbly border-radius on every element (same large radius on everything) +6. Decorative blobs, floating circles, wavy SVG dividers (if a section feels empty, it needs better content, not decoration) +7. Emoji as design elements (rockets in headings, emoji as bullet points) +8. Colored left-border on cards (`border-left: 3px solid `) +9. Generic hero copy ("Welcome to [X]", "Unlock the power of...", "Your all-in-one solution for...") +10. Cookie-cutter section rhythm (hero → 3 features → testimonials → pricing → CTA, every section same height) + +Source: [OpenAI "Designing Delightful Frontends with GPT-5.4"](https://developers.openai.com/blog/designing-delightful-frontends-with-gpt-5-4) (Mar 2026) + gstack design methodology. + Record baseline design score and AI slop score at end of Phase 6. --- @@ -879,6 +948,87 @@ Record baseline design score and AI slop score at end of Phase 6. --- +## Design Outside Voices (parallel) + +**Automatic:** Outside voices run automatically when Codex is available. No opt-in needed. + +**Check Codex availability:** +```bash +which codex 2>/dev/null && echo "CODEX_AVAILABLE" || echo "CODEX_NOT_AVAILABLE" +``` + +**If Codex is available**, launch both voices simultaneously: + +1. **Codex design voice** (via Bash): +```bash +TMPERR_DESIGN=$(mktemp /tmp/codex-design-XXXXXXXX) +codex exec "Review the frontend source code in this repo. Evaluate against these design hard rules: +- Spacing: systematic (design tokens / CSS variables) or magic numbers? +- Typography: expressive purposeful fonts or default stacks? +- Color: CSS variables with defined system, or hardcoded hex scattered? +- Responsive: breakpoints defined? calc(100svh - header) for heroes? Mobile tested? +- A11y: ARIA landmarks, alt text, contrast ratios, 44px touch targets? +- Motion: 2-3 intentional animations, or zero / ornamental only? +- Cards: used only when card IS the interaction? No decorative card grids? + +First classify as MARKETING/LANDING PAGE vs APP UI vs HYBRID, then apply matching rules. + +LITMUS CHECKS — answer YES/NO: +1. Brand/product unmistakable in first screen? +2. One strong visual anchor present? +3. Page understandable by scanning headlines only? +4. Each section has one job? +5. Are cards actually necessary? +6. Does motion improve hierarchy or atmosphere? +7. Would design feel premium with all decorative shadows removed? + +HARD REJECTION — flag if ANY apply: +1. Generic SaaS card grid as first impression +2. Beautiful image with weak brand +3. Strong headline with no clear action +4. Busy imagery behind text +5. Sections repeating same mood statement +6. Carousel with no narrative purpose +7. App UI made of stacked cards instead of layout + +Be specific. Reference file:line for every finding." -s read-only -c 'model_reasoning_effort="high"' --enable web_search_cached 2>"$TMPERR_DESIGN" +``` +Use a 5-minute timeout (`timeout: 300000`). After the command completes, read stderr: +```bash +cat "$TMPERR_DESIGN" && rm -f "$TMPERR_DESIGN" +``` + +2. **Claude design subagent** (via Agent tool): +Dispatch a subagent with this prompt: +"Review the frontend source code in this repo. You are an independent senior product designer doing a source-code design audit. Focus on CONSISTENCY PATTERNS across files rather than individual violations: +- Are spacing values systematic across the codebase? +- Is there ONE color system or scattered approaches? +- Do responsive breakpoints follow a consistent set? +- Is the accessibility approach consistent or spotty? + +For each finding: what's wrong, severity (critical/high/medium), and the file:line." + +**Error handling (all non-blocking):** +- **Auth failure:** If stderr contains "auth", "login", "unauthorized", or "API key": "Codex authentication failed. Run `codex login` to authenticate." +- **Timeout:** "Codex timed out after 5 minutes." +- **Empty response:** "Codex returned no response." +- On any Codex error: proceed with Claude subagent output only, tagged `[single-model]`. +- If Claude subagent also fails: "Outside voices unavailable — continuing with primary review." + +Present Codex output under a `CODEX SAYS (design source audit):` header. +Present subagent output under a `CLAUDE SUBAGENT (design consistency):` header. + +**Synthesis — Litmus scorecard:** + +Use the same scorecard format as /plan-design-review (shown above). Fill in from both outputs. +Merge findings into the triage with `[codex]` / `[subagent]` / `[cross-model]` tags. + +**Log the result:** +```bash +~/.claude/skills/gstack/bin/gstack-review-log '{"skill":"design-outside-voices","timestamp":"'"$(date -u +%Y-%m-%dT%H:%M:%SZ)"'","status":"STATUS","source":"SOURCE","commit":"'"$(git rev-parse --short HEAD)"'"}' +``` +Replace STATUS with "clean" or "issues_found", SOURCE with "codex+subagent", "codex-only", "subagent-only", or "unavailable". + ## Phase 7: Triage Sort all discovered findings by impact, then decide which to fix: diff --git a/design-review/SKILL.md.tmpl b/design-review/SKILL.md.tmpl index 84119c26..e54332fa 100644 --- a/design-review/SKILL.md.tmpl +++ b/design-review/SKILL.md.tmpl @@ -84,6 +84,8 @@ mkdir -p "$REPORT_DIR/screenshots" {{DESIGN_METHODOLOGY}} +{{DESIGN_HARD_RULES}} + Record baseline design score and AI slop score at end of Phase 6. --- @@ -107,6 +109,8 @@ Record baseline design score and AI slop score at end of Phase 6. --- +{{DESIGN_OUTSIDE_VOICES}} + ## Phase 7: Triage Sort all discovered findings by impact, then decide which to fix: diff --git a/office-hours/SKILL.md b/office-hours/SKILL.md index 47a841a7..ab69f1b6 100644 --- a/office-hours/SKILL.md +++ b/office-hours/SKILL.md @@ -731,6 +731,35 @@ Reference the wireframe screenshot in the design doc's "Recommended Approach" se The screenshot file at `/tmp/gstack-sketch.png` can be referenced by downstream skills (`/plan-design-review`, `/design-review`) to see what was originally envisioned. +**Step 6: Outside design voices** (optional) + +After the wireframe is approved, offer outside design perspectives: + +```bash +which codex 2>/dev/null && echo "CODEX_AVAILABLE" || echo "CODEX_NOT_AVAILABLE" +``` + +If Codex is available, use AskUserQuestion: +> "Want outside design perspectives on the chosen approach? Codex proposes a visual thesis, content plan, and interaction ideas. A Claude subagent proposes an alternative aesthetic direction." +> +> A) Yes — get outside design voices +> B) No — proceed without + +If user chooses A, launch both voices simultaneously: + +1. **Codex** (via Bash, `model_reasoning_effort="medium"`): +```bash +TMPERR_SKETCH=$(mktemp /tmp/codex-sketch-XXXXXXXX) +codex exec "For this product approach, provide: a visual thesis (one sentence — mood, material, energy), a content plan (hero → support → detail → CTA), and 2 interaction ideas that change page feel. Apply beautiful defaults: composition-first, brand-first, cardless, poster not document. Be opinionated." -s read-only -c 'model_reasoning_effort="medium"' --enable web_search_cached 2>"$TMPERR_SKETCH" +``` +Use a 5-minute timeout (`timeout: 300000`). After completion: `cat "$TMPERR_SKETCH" && rm -f "$TMPERR_SKETCH"` + +2. **Claude subagent** (via Agent tool): +"For this product approach, what design direction would you recommend? What aesthetic, typography, and interaction patterns fit? What would make this approach feel inevitable to the user? Be specific — font names, hex colors, spacing values." + +Present Codex output under `CODEX SAYS (design sketch):` and subagent output under `CLAUDE SUBAGENT (design direction):`. +Error handling: all non-blocking. On failure, skip and continue. + --- ## Phase 4.5: Founder Signal Synthesis diff --git a/plan-design-review/SKILL.md b/plan-design-review/SKILL.md index afd81ff0..fb0bbfa2 100644 --- a/plan-design-review/SKILL.md +++ b/plan-design-review/SKILL.md @@ -420,6 +420,113 @@ AskUserQuestion: "I've rated this plan {N}/10 on design completeness. The bigges **STOP.** Do NOT proceed until user responds. +## Design Outside Voices (parallel) + +Use AskUserQuestion: +> "Want outside design voices before the detailed review? Codex evaluates against OpenAI's design hard rules + litmus checks; Claude subagent does an independent completeness review." +> +> A) Yes — run outside design voices +> B) No — proceed without + +If user chooses B, skip this step and continue. + +**Check Codex availability:** +```bash +which codex 2>/dev/null && echo "CODEX_AVAILABLE" || echo "CODEX_NOT_AVAILABLE" +``` + +**If Codex is available**, launch both voices simultaneously: + +1. **Codex design voice** (via Bash): +```bash +TMPERR_DESIGN=$(mktemp /tmp/codex-design-XXXXXXXX) +codex exec "Read the plan file at [plan-file-path]. Evaluate this plan's UI/UX design against these criteria. + +HARD REJECTION — flag if ANY apply: +1. Generic SaaS card grid as first impression +2. Beautiful image with weak brand +3. Strong headline with no clear action +4. Busy imagery behind text +5. Sections repeating same mood statement +6. Carousel with no narrative purpose +7. App UI made of stacked cards instead of layout + +LITMUS CHECKS — answer YES or NO for each: +1. Brand/product unmistakable in first screen? +2. One strong visual anchor present? +3. Page understandable by scanning headlines only? +4. Each section has one job? +5. Are cards actually necessary? +6. Does motion improve hierarchy or atmosphere? +7. Would design feel premium with all decorative shadows removed? + +HARD RULES — first classify as MARKETING/LANDING PAGE vs APP UI vs HYBRID, then flag violations of the matching rule set: +- MARKETING: First viewport as one composition, brand-first hierarchy, full-bleed hero, 2-3 intentional motions, composition-first layout +- APP UI: Calm surface hierarchy, dense but readable, utility language, minimal chrome +- UNIVERSAL: CSS variables for colors, no default font stacks, one job per section, cards earn existence + +For each finding: what's wrong, what will happen if it ships unresolved, and the specific fix. Be opinionated. No hedging." -s read-only -c 'model_reasoning_effort="high"' --enable web_search_cached 2>"$TMPERR_DESIGN" +``` +Use a 5-minute timeout (`timeout: 300000`). After the command completes, read stderr: +```bash +cat "$TMPERR_DESIGN" && rm -f "$TMPERR_DESIGN" +``` + +2. **Claude design subagent** (via Agent tool): +Dispatch a subagent with this prompt: +"Read the plan file at [plan-file-path]. You are an independent senior product designer reviewing this plan. You have NOT seen any prior review. Evaluate: + +1. Information hierarchy: what does the user see first, second, third? Is it right? +2. Missing states: loading, empty, error, success, partial — which are unspecified? +3. User journey: what's the emotional arc? Where does it break? +4. Specificity: does the plan describe SPECIFIC UI ("48px Söhne Bold header, #1a1a1a on white") or generic patterns ("clean modern card-based layout")? +5. What design decisions will haunt the implementer if left ambiguous? + +For each finding: what's wrong, severity (critical/high/medium), and the fix." + +**Error handling (all non-blocking):** +- **Auth failure:** If stderr contains "auth", "login", "unauthorized", or "API key": "Codex authentication failed. Run `codex login` to authenticate." +- **Timeout:** "Codex timed out after 5 minutes." +- **Empty response:** "Codex returned no response." +- On any Codex error: proceed with Claude subagent output only, tagged `[single-model]`. +- If Claude subagent also fails: "Outside voices unavailable — continuing with primary review." + +Present Codex output under a `CODEX SAYS (design critique):` header. +Present subagent output under a `CLAUDE SUBAGENT (design completeness):` header. + +**Synthesis — Litmus scorecard:** + +``` +DESIGN OUTSIDE VOICES — LITMUS SCORECARD: +═══════════════════════════════════════════════════════════════ + Check Claude Codex Consensus + ─────────────────────────────────────── ─────── ─────── ───────── + 1. Brand unmistakable in first screen? — — — + 2. One strong visual anchor? — — — + 3. Scannable by headlines only? — — — + 4. Each section has one job? — — — + 5. Cards actually necessary? — — — + 6. Motion improves hierarchy? — — — + 7. Premium without decorative shadows? — — — + ─────────────────────────────────────── ─────── ─────── ───────── + Hard rejections triggered: — — — +═══════════════════════════════════════════════════════════════ +``` + +Fill in each cell from the Codex and subagent outputs. CONFIRMED = both agree. DISAGREE = models differ. NOT SPEC'D = not enough info to evaluate. + +**Pass integration (respects existing 7-pass contract):** +- Hard rejections → raised as the FIRST items in Pass 1, tagged `[HARD REJECTION]` +- Litmus DISAGREE items → raised in the relevant pass with both perspectives +- Litmus CONFIRMED failures → pre-loaded as known issues in the relevant pass +- Passes can skip discovery and go straight to fixing for pre-identified issues + +**Log the result:** +```bash +~/.claude/skills/gstack/bin/gstack-review-log '{"skill":"design-outside-voices","timestamp":"'"$(date -u +%Y-%m-%dT%H:%M:%SZ)"'","status":"STATUS","source":"SOURCE","commit":"'"$(git rev-parse --short HEAD)"'"}' +``` +Replace STATUS with "clean" or "issues_found", SOURCE with "codex+subagent", "codex-only", "subagent-only", or "unavailable". + ## The 0-10 Rating Method For each design section, rate the plan 0-10 on that dimension. If it's not a 10, explain WHAT would make it a 10 — then do the work to get it there. @@ -468,6 +575,75 @@ Apply time-horizon design: 5-sec visceral, 5-min behavioral, 5-year reflective. ### Pass 4: AI Slop Risk Rate 0-10: Does the plan describe specific, intentional UI — or generic patterns? FIX TO 10: Rewrite vague UI descriptions with specific alternatives. + +### Design Hard Rules + +**Classifier — determine rule set before evaluating:** +- **MARKETING/LANDING PAGE** (hero-driven, brand-forward, conversion-focused) → apply Landing Page Rules +- **APP UI** (workspace-driven, data-dense, task-focused: dashboards, admin, settings) → apply App UI Rules +- **HYBRID** (marketing shell with app-like sections) → apply Landing Page Rules to hero/marketing sections, App UI Rules to functional sections + +**Hard rejection criteria** (instant-fail patterns — flag if ANY apply): +1. Generic SaaS card grid as first impression +2. Beautiful image with weak brand +3. Strong headline with no clear action +4. Busy imagery behind text +5. Sections repeating same mood statement +6. Carousel with no narrative purpose +7. App UI made of stacked cards instead of layout + +**Litmus checks** (answer YES/NO for each — used for cross-model consensus scoring): +1. Brand/product unmistakable in first screen? +2. One strong visual anchor present? +3. Page understandable by scanning headlines only? +4. Each section has one job? +5. Are cards actually necessary? +6. Does motion improve hierarchy or atmosphere? +7. Would design feel premium with all decorative shadows removed? + +**Landing page rules** (apply when classifier = MARKETING/LANDING): +- First viewport reads as one composition, not a dashboard +- Brand-first hierarchy: brand > headline > body > CTA +- Typography: expressive, purposeful — no default stacks (Inter, Roboto, Arial, system) +- No flat single-color backgrounds — use gradients, images, subtle patterns +- Hero: full-bleed, edge-to-edge, no inset/tiled/rounded variants +- Hero budget: brand, one headline, one supporting sentence, one CTA group, one image +- No cards in hero. Cards only when card IS the interaction +- One job per section: one purpose, one headline, one short supporting sentence +- Motion: 2-3 intentional motions minimum (entrance, scroll-linked, hover/reveal) +- Color: define CSS variables, avoid purple-on-white defaults, one accent color default +- Copy: product language not design commentary. "If deleting 30% improves it, keep deleting" +- Beautiful defaults: composition-first, brand as loudest text, two typefaces max, cardless by default, first viewport as poster not document + +**App UI rules** (apply when classifier = APP UI): +- Calm surface hierarchy, strong typography, few colors +- Dense but readable, minimal chrome +- Organize: primary workspace, navigation, secondary context, one accent +- Avoid: dashboard-card mosaics, thick borders, decorative gradients, ornamental icons +- Copy: utility language — orientation, status, action. Not mood/brand/aspiration +- Cards only when card IS the interaction +- Section headings state what area is or what user can do ("Selected KPIs", "Plan status") + +**Universal rules** (apply to ALL types): +- Define CSS variables for color system +- No default font stacks (Inter, Roboto, Arial, system) +- One job per section +- "If deleting 30% of the copy improves it, keep deleting" +- Cards earn their existence — no decorative card grids + +**AI Slop blacklist** (the 10 patterns that scream "AI-generated"): +1. Purple/violet/indigo gradient backgrounds or blue-to-purple color schemes +2. **The 3-column feature grid:** icon-in-colored-circle + bold title + 2-line description, repeated 3x symmetrically. THE most recognizable AI layout. +3. Icons in colored circles as section decoration (SaaS starter template look) +4. Centered everything (`text-align: center` on all headings, descriptions, cards) +5. Uniform bubbly border-radius on every element (same large radius on everything) +6. Decorative blobs, floating circles, wavy SVG dividers (if a section feels empty, it needs better content, not decoration) +7. Emoji as design elements (rockets in headings, emoji as bullet points) +8. Colored left-border on cards (`border-left: 3px solid `) +9. Generic hero copy ("Welcome to [X]", "Unlock the power of...", "Your all-in-one solution for...") +10. Cookie-cutter section rhythm (hero → 3 features → testimonials → pricing → CTA, every section same height) + +Source: [OpenAI "Designing Delightful Frontends with GPT-5.4"](https://developers.openai.com/blog/designing-delightful-frontends-with-gpt-5-4) (Mar 2026) + gstack design methodology. - "Cards with icons" → what differentiates these from every SaaS template? - "Hero section" → what makes this hero feel like THIS product? - "Clean, modern UI" → meaningless. Replace with actual design decisions. diff --git a/plan-design-review/SKILL.md.tmpl b/plan-design-review/SKILL.md.tmpl index 46e5b6f1..30e5b414 100644 --- a/plan-design-review/SKILL.md.tmpl +++ b/plan-design-review/SKILL.md.tmpl @@ -128,6 +128,8 @@ AskUserQuestion: "I've rated this plan {N}/10 on design completeness. The bigges **STOP.** Do NOT proceed until user responds. +{{DESIGN_OUTSIDE_VOICES}} + ## The 0-10 Rating Method For each design section, rate the plan 0-10 on that dimension. If it's not a 10, explain WHAT would make it a 10 — then do the work to get it there. @@ -176,6 +178,8 @@ Apply time-horizon design: 5-sec visceral, 5-min behavioral, 5-year reflective. ### Pass 4: AI Slop Risk Rate 0-10: Does the plan describe specific, intentional UI — or generic patterns? FIX TO 10: Rewrite vague UI descriptions with specific alternatives. + +{{DESIGN_HARD_RULES}} - "Cards with icons" → what differentiates these from every SaaS template? - "Hero section" → what makes this hero feel like THIS product? - "Clean, modern UI" → meaningless. Replace with actual design decisions. diff --git a/review/SKILL.md b/review/SKILL.md index 3d5e21fc..f3e7444a 100644 --- a/review/SKILL.md +++ b/review/SKILL.md @@ -447,6 +447,28 @@ source <(~/.claude/skills/gstack/bin/gstack-diff-scope 2>/dev/null) 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`. +7. **Codex design voice** (optional, automatic if available): + +```bash +which codex 2>/dev/null && echo "CODEX_AVAILABLE" || echo "CODEX_NOT_AVAILABLE" +``` + +If Codex is available, run a lightweight design check on the diff: + +```bash +TMPERR_DRL=$(mktemp /tmp/codex-drl-XXXXXXXX) +codex exec "Review the git diff on this branch. Run 7 litmus checks (YES/NO each): 1. Brand/product unmistakable in first screen? 2. One strong visual anchor present? 3. Page understandable by scanning headlines only? 4. Each section has one job? 5. Are cards actually necessary? 6. Does motion improve hierarchy or atmosphere? 7. Would design feel premium with all decorative shadows removed? Flag any hard rejections: 1. Generic SaaS card grid as first impression 2. Beautiful image with weak brand 3. Strong headline with no clear action 4. Busy imagery behind text 5. Sections repeating same mood statement 6. Carousel with no narrative purpose 7. App UI made of stacked cards instead of layout 5 most important design findings only. Reference file:line." -s read-only -c 'model_reasoning_effort="high"' --enable web_search_cached 2>"$TMPERR_DRL" +``` + +Use a 5-minute timeout (`timeout: 300000`). After the command completes, read stderr: +```bash +cat "$TMPERR_DRL" && rm -f "$TMPERR_DRL" +``` + +**Error handling:** All errors are non-blocking. On auth failure, timeout, or empty response — skip with a brief note and continue. + +Present Codex output under a `CODEX (design):` header, merged with the checklist findings above. + Include any design findings alongside the findings from Step 4. They follow the same Fix-First flow in Step 5 — AUTO-FIX for mechanical CSS fixes, ASK for everything else. --- diff --git a/ship/SKILL.md b/ship/SKILL.md index a8b5047e..dc7f5e37 100644 --- a/ship/SKILL.md +++ b/ship/SKILL.md @@ -1042,6 +1042,28 @@ source <(~/.claude/skills/gstack/bin/gstack-diff-scope 2>/dev/null) 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`. +7. **Codex design voice** (optional, automatic if available): + +```bash +which codex 2>/dev/null && echo "CODEX_AVAILABLE" || echo "CODEX_NOT_AVAILABLE" +``` + +If Codex is available, run a lightweight design check on the diff: + +```bash +TMPERR_DRL=$(mktemp /tmp/codex-drl-XXXXXXXX) +codex exec "Review the git diff on this branch. Run 7 litmus checks (YES/NO each): 1. Brand/product unmistakable in first screen? 2. One strong visual anchor present? 3. Page understandable by scanning headlines only? 4. Each section has one job? 5. Are cards actually necessary? 6. Does motion improve hierarchy or atmosphere? 7. Would design feel premium with all decorative shadows removed? Flag any hard rejections: 1. Generic SaaS card grid as first impression 2. Beautiful image with weak brand 3. Strong headline with no clear action 4. Busy imagery behind text 5. Sections repeating same mood statement 6. Carousel with no narrative purpose 7. App UI made of stacked cards instead of layout 5 most important design findings only. Reference file:line." -s read-only -c 'model_reasoning_effort="high"' --enable web_search_cached 2>"$TMPERR_DRL" +``` + +Use a 5-minute timeout (`timeout: 300000`). After the command completes, read stderr: +```bash +cat "$TMPERR_DRL" && rm -f "$TMPERR_DRL" +``` + +**Error handling:** All errors are non-blocking. On auth failure, timeout, or empty response — skip with a brief note and continue. + +Present Codex output under a `CODEX (design):` header, merged with the checklist findings above. + Include any design findings alongside the code review findings. They follow the same Fix-First flow below. 4. **Classify each finding as AUTO-FIX or ASK** per the Fix-First Heuristic in