diff --git a/.claude/skills/critique/SKILL.md b/.claude/skills/critique/SKILL.md index ffca3867d..65f84e48e 100644 --- a/.claude/skills/critique/SKILL.md +++ b/.claude/skills/critique/SKILL.md @@ -1,6 +1,6 @@ --- name: critique -description: Evaluate design effectiveness from a UX perspective. Assesses visual hierarchy, information architecture, emotional resonance, and overall design quality with actionable feedback. +description: Evaluate design effectiveness from a UX perspective. Assesses visual hierarchy, information architecture, emotional resonance, and overall design quality with actionable feedback. Use when the user wants a design review, UX feedback, asks to evaluate visual quality, or wants to check for AI-generated design tells. user-invokable: true args: - name: area @@ -16,137 +16,46 @@ Use the frontend-design skill -- it contains design principles, anti-patterns, a ## AUTOMATED ANTI-PATTERN SCAN (First Pass) -Before the manual critique, run the deterministic anti-pattern detector. This catches 25 issues across AI slop tells and general design quality problems with zero false negatives. - -### Step 1: Determine the target - -Based on the user's request, identify what to scan: -- **Specific file(s)**: Use the file path(s) directly -- **Component/area**: Identify the relevant directory or files -- **URL**: Use the URL directly (the script supports URL scanning via Puppeteer) -- **Whole project / vague target**: Default to the project root, but check scope first - -### Step 2: Check scope (directories only) - -For directory targets, estimate the number of scannable files first: - -```bash -find [target-dir] -type f \( -name "*.html" -o -name "*.htm" -o -name "*.css" -o -name "*.scss" -o -name "*.jsx" -o -name "*.tsx" -o -name "*.vue" -o -name "*.svelte" -o -name "*.astro" \) -not -path "*/node_modules/*" -not -path "*/.git/*" -not -path "*/dist/*" -not -path "*/build/*" -not -path "*/.next/*" | wc -l -``` - -- **< 200 files**: Run full scan (jsdom for HTML, regex for the rest) -- **200-500 files**: Run with `--fast` (regex-only, much faster) -- **> 500 files**: Narrow scope. Scan only the most relevant subdirectory, or ask the user which area to focus on. - -### Step 3: Run the scan +Before the manual critique, run the bundled deterministic detector. It catches 25 specific issues (AI slop tells + general design quality). ```bash node scripts/detect-antipatterns.mjs --json [--fast] [target] ``` -The script exits with code 0 (clean) or 2 (findings). Use `--json` for structured output that's easier to parse. +- Pass files, directories, or URLs as `[target]` +- For large directories (200+ scannable files), use `--fast` (regex-only, skips jsdom) +- For 500+ files, narrow scope to the most relevant subdirectory or ask the user +- Exit code 0 = clean, 2 = findings -### Step 4: Interpret results - -- If findings are found, they MUST appear in the Anti-Patterns Verdict and Priority Issues -- Group findings by type (e.g., "5 side-tab borders across 3 files, 2 gradient text instances") -- Note which files have the most issues -- Deterministic findings are ground truth. Do not contradict them in the LLM analysis. +Include scan findings in the Anti-Patterns Verdict and Priority Issues. The detector is highly reliable but not perfect. If a finding is clearly a false positive given the context (e.g., intentional design choice), note it as such rather than blindly reporting it. --- ## BROWSER VISUALIZATION (When Available) -If you have access to browser automation tools that control a real visual browser in front of the user (e.g., `mcp__claude-in-chrome__javascript_tool` and `mcp__claude-in-chrome__navigate`, or Cursor's browser integration), AND the target includes a viewable page (HTML file or URL), enhance the critique with live visual overlays. +If you have browser automation tools that control a visual browser in front of the user (e.g., `mcp__claude-in-chrome__javascript_tool`, Cursor's browser), AND the target is a viewable page, enhance the critique with live visual overlays. -### How it works +1. **Navigate** to the page (use dev server URL for local files, or direct URL) +2. **Inject** `scripts/detect-antipatterns-browser.js` via `javascript_tool`: read the file and pass its content as JS to evaluate. The IIFE auto-executes and shows pink/magenta outlines with labels on every issue. Do NOT `cat` the file into the conversation first. +3. **Reference** the overlays in your report: "As highlighted in the browser..." -1. **Navigate to the page**: For URLs, navigate directly. For local HTML files, check if a dev server is running (look at package.json scripts for `dev`, `start`, or `serve`) and use its URL. As a fallback, try `file:///` + absolute path. - -2. **Read the browser detection script**: -```bash -cat scripts/detect-antipatterns-browser.js -``` - -3. **Inject the script** via `javascript_tool` (or equivalent): Pass the entire script content as JavaScript to evaluate in the page context. The script is an IIFE that auto-executes and shows visual overlays. - -4. **Interpret**: After injection, the user's browser shows pink/magenta outlines around every problematic element with labels describing the issue. A banner at the top shows page-level findings. The user can hover overlays to see detailed tooltips. - -5. **Reference the visuals** in your critique report: "As highlighted in the browser, the card component uses a side-tab border pattern..." - -If the target has multiple important views (e.g., a full site), inject the script on 3-5 representative pages. - -**If injection fails** (tool not available, CSP error, page won't load), continue with CLI scan results only. Do not let browser issues block the critique. +For multi-view targets, inject on 3-5 representative pages. If injection fails, continue with CLI results only. --- -Conduct a holistic design critique, evaluating whether the interface actually works -- not just technically, but as a designed experience. Think like a design director giving feedback. +Think like a design director giving feedback. Evaluate whether the interface works as a designed experience. ## Design Critique -Evaluate the interface across these dimensions: +### AI Slop Detection (CRITICAL) -### 1. AI Slop Detection (CRITICAL) +**This is the most important check.** Does this look like every other AI-generated interface? Review against ALL **DON'T** guidelines in the frontend-design skill. Check for AI color palette, gradient text, dark glows, glassmorphism, hero metric layouts, identical card grids, generic fonts, and all other tells. -**This is the most important check.** Does this look like every other AI-generated interface from 2024-2025? +**The test**: If someone said "AI made this," would you believe them immediately? -Review the design against ALL the **DON'T** guidelines in the frontend-design skill -- they are the fingerprints of AI-generated work. Check for the AI color palette, gradient text, dark mode with glowing accents, glassmorphism, hero metric layouts, identical card grids, generic fonts, and all other tells. +### Holistic Design Review -**The test**: If you showed this to someone and said "AI made this," would they believe you immediately? If yes, that's the problem. - -### 2. Visual Hierarchy -- Does the eye flow to the most important element first? -- Is there a clear primary action? Can you spot it in 2 seconds? -- Do size, color, and position communicate importance correctly? -- Is there visual competition between elements that should have different weights? - -### 3. Information Architecture -- Is the structure intuitive? Would a new user understand the organization? -- Is related content grouped logically? -- Are there too many choices at once? (cognitive overload) -- Is the navigation clear and predictable? - -### 4. Emotional Resonance -- What emotion does this interface evoke? Is that intentional? -- Does it match the brand personality? -- Does it feel trustworthy, approachable, premium, playful -- whatever it should feel? -- Would the target user feel "this is for me"? - -### 5. Discoverability & Affordance -- Are interactive elements obviously interactive? -- Would a user know what to do without instructions? -- Are hover/focus states providing useful feedback? -- Are there hidden features that should be more visible? - -### 6. Composition & Balance -- Does the layout feel balanced or uncomfortably weighted? -- Is whitespace used intentionally or just leftover? -- Is there visual rhythm in spacing and repetition? -- Does asymmetry feel designed or accidental? - -### 7. Typography as Communication -- Does the type hierarchy clearly signal what to read first, second, third? -- Is body text comfortable to read? (line length, spacing, size) -- Do font choices reinforce the brand/tone? -- Is there enough contrast between heading levels? - -### 8. Color with Purpose -- Is color used to communicate, not just decorate? -- Does the palette feel cohesive? -- Are accent colors drawing attention to the right things? -- Does it work for colorblind users? (not just technically -- does meaning still come through?) - -### 9. States & Edge Cases -- Empty states: Do they guide users toward action, or just say "nothing here"? -- Loading states: Do they reduce perceived wait time? -- Error states: Are they helpful and non-blaming? -- Success states: Do they confirm and guide next steps? - -### 10. Microcopy & Voice -- Is the writing clear and concise? -- Does it sound like a human (the right human for this brand)? -- Are labels and buttons unambiguous? -- Does error copy help users fix the problem? +Evaluate: **visual hierarchy** (eye flow, primary action clarity), **information architecture** (structure, grouping, cognitive load), **emotional resonance** (does it match brand and audience?), **discoverability** (are interactive elements obvious?), **composition** (balance, whitespace, rhythm), **typography** (hierarchy, readability, font choices), **color** (purposeful use, cohesion, accessibility), **states & edge cases** (empty, loading, error, success), **microcopy** (clarity, tone, helpfulness). ## Generate Critique Report @@ -156,7 +65,7 @@ Structure your feedback as a design director would: **Start here.** Does this look AI-generated? -**Deterministic scan**: Summarize what the automated detector found, with counts and file locations. These are confirmed issues. Do not dispute them. +**Deterministic scan**: Summarize what the automated detector found, with counts and file locations. **Visual overlays** (if browser was used): Reference what the user can see highlighted in their browser. diff --git a/source/skills/critique/SKILL.md b/source/skills/critique/SKILL.md index 262036525..f2c9d3917 100644 --- a/source/skills/critique/SKILL.md +++ b/source/skills/critique/SKILL.md @@ -1,6 +1,6 @@ --- name: critique -description: Evaluate design effectiveness from a UX perspective. Assesses visual hierarchy, information architecture, emotional resonance, and overall design quality with actionable feedback. +description: Evaluate design effectiveness from a UX perspective. Assesses visual hierarchy, information architecture, emotional resonance, and overall design quality with actionable feedback. Use when the user wants a design review, UX feedback, asks to evaluate visual quality, or wants to check for AI-generated design tells. args: - name: area description: The feature or area to critique (optional) @@ -16,137 +16,46 @@ Use the frontend-design skill -- it contains design principles, anti-patterns, a ## AUTOMATED ANTI-PATTERN SCAN (First Pass) -Before the manual critique, run the deterministic anti-pattern detector. This catches 25 issues across AI slop tells and general design quality problems with zero false negatives. - -### Step 1: Determine the target - -Based on the user's request, identify what to scan: -- **Specific file(s)**: Use the file path(s) directly -- **Component/area**: Identify the relevant directory or files -- **URL**: Use the URL directly (the script supports URL scanning via Puppeteer) -- **Whole project / vague target**: Default to the project root, but check scope first - -### Step 2: Check scope (directories only) - -For directory targets, estimate the number of scannable files first: - -```bash -find [target-dir] -type f \( -name "*.html" -o -name "*.htm" -o -name "*.css" -o -name "*.scss" -o -name "*.jsx" -o -name "*.tsx" -o -name "*.vue" -o -name "*.svelte" -o -name "*.astro" \) -not -path "*/node_modules/*" -not -path "*/.git/*" -not -path "*/dist/*" -not -path "*/build/*" -not -path "*/.next/*" | wc -l -``` - -- **< 200 files**: Run full scan (jsdom for HTML, regex for the rest) -- **200-500 files**: Run with `--fast` (regex-only, much faster) -- **> 500 files**: Narrow scope. Scan only the most relevant subdirectory, or ask the user which area to focus on. - -### Step 3: Run the scan +Before the manual critique, run the bundled deterministic detector. It catches 25 specific issues (AI slop tells + general design quality). ```bash node scripts/detect-antipatterns.mjs --json [--fast] [target] ``` -The script exits with code 0 (clean) or 2 (findings). Use `--json` for structured output that's easier to parse. +- Pass files, directories, or URLs as `[target]` +- For large directories (200+ scannable files), use `--fast` (regex-only, skips jsdom) +- For 500+ files, narrow scope to the most relevant subdirectory or ask the user +- Exit code 0 = clean, 2 = findings -### Step 4: Interpret results - -- If findings are found, they MUST appear in the Anti-Patterns Verdict and Priority Issues -- Group findings by type (e.g., "5 side-tab borders across 3 files, 2 gradient text instances") -- Note which files have the most issues -- Deterministic findings are ground truth. Do not contradict them in the LLM analysis. +Include scan findings in the Anti-Patterns Verdict and Priority Issues. The detector is highly reliable but not perfect. If a finding is clearly a false positive given the context (e.g., intentional design choice), note it as such rather than blindly reporting it. --- ## BROWSER VISUALIZATION (When Available) -If you have access to browser automation tools that control a real visual browser in front of the user (e.g., `mcp__claude-in-chrome__javascript_tool` and `mcp__claude-in-chrome__navigate`, or Cursor's browser integration), AND the target includes a viewable page (HTML file or URL), enhance the critique with live visual overlays. +If you have browser automation tools that control a visual browser in front of the user (e.g., `mcp__claude-in-chrome__javascript_tool`, Cursor's browser), AND the target is a viewable page, enhance the critique with live visual overlays. -### How it works +1. **Navigate** to the page (use dev server URL for local files, or direct URL) +2. **Inject** `scripts/detect-antipatterns-browser.js` via `javascript_tool`: read the file and pass its content as JS to evaluate. The IIFE auto-executes and shows pink/magenta outlines with labels on every issue. Do NOT `cat` the file into the conversation first. +3. **Reference** the overlays in your report: "As highlighted in the browser..." -1. **Navigate to the page**: For URLs, navigate directly. For local HTML files, check if a dev server is running (look at package.json scripts for `dev`, `start`, or `serve`) and use its URL. As a fallback, try `file:///` + absolute path. - -2. **Read the browser detection script**: -```bash -cat scripts/detect-antipatterns-browser.js -``` - -3. **Inject the script** via `javascript_tool` (or equivalent): Pass the entire script content as JavaScript to evaluate in the page context. The script is an IIFE that auto-executes and shows visual overlays. - -4. **Interpret**: After injection, the user's browser shows pink/magenta outlines around every problematic element with labels describing the issue. A banner at the top shows page-level findings. The user can hover overlays to see detailed tooltips. - -5. **Reference the visuals** in your critique report: "As highlighted in the browser, the card component uses a side-tab border pattern..." - -If the target has multiple important views (e.g., a full site), inject the script on 3-5 representative pages. - -**If injection fails** (tool not available, CSP error, page won't load), continue with CLI scan results only. Do not let browser issues block the critique. +For multi-view targets, inject on 3-5 representative pages. If injection fails, continue with CLI results only. --- -Conduct a holistic design critique, evaluating whether the interface actually works -- not just technically, but as a designed experience. Think like a design director giving feedback. +Think like a design director giving feedback. Evaluate whether the interface works as a designed experience. ## Design Critique -Evaluate the interface across these dimensions: +### AI Slop Detection (CRITICAL) -### 1. AI Slop Detection (CRITICAL) +**This is the most important check.** Does this look like every other AI-generated interface? Review against ALL **DON'T** guidelines in the frontend-design skill. Check for AI color palette, gradient text, dark glows, glassmorphism, hero metric layouts, identical card grids, generic fonts, and all other tells. -**This is the most important check.** Does this look like every other AI-generated interface from 2024-2025? +**The test**: If someone said "AI made this," would you believe them immediately? -Review the design against ALL the **DON'T** guidelines in the frontend-design skill -- they are the fingerprints of AI-generated work. Check for the AI color palette, gradient text, dark mode with glowing accents, glassmorphism, hero metric layouts, identical card grids, generic fonts, and all other tells. +### Holistic Design Review -**The test**: If you showed this to someone and said "AI made this," would they believe you immediately? If yes, that's the problem. - -### 2. Visual Hierarchy -- Does the eye flow to the most important element first? -- Is there a clear primary action? Can you spot it in 2 seconds? -- Do size, color, and position communicate importance correctly? -- Is there visual competition between elements that should have different weights? - -### 3. Information Architecture -- Is the structure intuitive? Would a new user understand the organization? -- Is related content grouped logically? -- Are there too many choices at once? (cognitive overload) -- Is the navigation clear and predictable? - -### 4. Emotional Resonance -- What emotion does this interface evoke? Is that intentional? -- Does it match the brand personality? -- Does it feel trustworthy, approachable, premium, playful -- whatever it should feel? -- Would the target user feel "this is for me"? - -### 5. Discoverability & Affordance -- Are interactive elements obviously interactive? -- Would a user know what to do without instructions? -- Are hover/focus states providing useful feedback? -- Are there hidden features that should be more visible? - -### 6. Composition & Balance -- Does the layout feel balanced or uncomfortably weighted? -- Is whitespace used intentionally or just leftover? -- Is there visual rhythm in spacing and repetition? -- Does asymmetry feel designed or accidental? - -### 7. Typography as Communication -- Does the type hierarchy clearly signal what to read first, second, third? -- Is body text comfortable to read? (line length, spacing, size) -- Do font choices reinforce the brand/tone? -- Is there enough contrast between heading levels? - -### 8. Color with Purpose -- Is color used to communicate, not just decorate? -- Does the palette feel cohesive? -- Are accent colors drawing attention to the right things? -- Does it work for colorblind users? (not just technically -- does meaning still come through?) - -### 9. States & Edge Cases -- Empty states: Do they guide users toward action, or just say "nothing here"? -- Loading states: Do they reduce perceived wait time? -- Error states: Are they helpful and non-blaming? -- Success states: Do they confirm and guide next steps? - -### 10. Microcopy & Voice -- Is the writing clear and concise? -- Does it sound like a human (the right human for this brand)? -- Are labels and buttons unambiguous? -- Does error copy help users fix the problem? +Evaluate: **visual hierarchy** (eye flow, primary action clarity), **information architecture** (structure, grouping, cognitive load), **emotional resonance** (does it match brand and audience?), **discoverability** (are interactive elements obvious?), **composition** (balance, whitespace, rhythm), **typography** (hierarchy, readability, font choices), **color** (purposeful use, cohesion, accessibility), **states & edge cases** (empty, loading, error, success), **microcopy** (clarity, tone, helpfulness). ## Generate Critique Report @@ -156,7 +65,7 @@ Structure your feedback as a design director would: **Start here.** Does this look AI-generated? -**Deterministic scan**: Summarize what the automated detector found, with counts and file locations. These are confirmed issues. Do not dispute them. +**Deterministic scan**: Summarize what the automated detector found, with counts and file locations. **Visual overlays** (if browser was used): Reference what the user can see highlighted in their browser.