From d7937b1844ff86c01ee8e38dc82eeff7688ac17e Mon Sep 17 00:00:00 2001 From: Paul Bakaus Date: Wed, 7 Jan 2026 18:57:55 -0800 Subject: [PATCH] Rename /review command to /critique to avoid Claude conflict MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit The /review command conflicts with a built-in Claude Code command. Renamed to /critique which better reflects design terminology. - Rename source/commands/review.md → critique.md - Update command content and descriptions - Rename demo file and update references - Update data.js command mappings - Update case study example in index.html - Rebuild dist files for all providers Co-Authored-By: Claude Opus 4.5 --- .claude/commands/critique.md | 107 ++++++++++++++++++ .claude/commands/teach-impeccable.md | 92 +++++++-------- dist/claude-code/.claude/commands/critique.md | 107 ++++++++++++++++++ .../.claude/commands/teach-impeccable.md | 92 +++++++-------- dist/codex/.codex/prompts/critique.md | 102 +++++++++++++++++ dist/codex/.codex/prompts/teach-impeccable.md | 92 +++++++-------- dist/cursor/.cursor/commands/critique.md | 97 ++++++++++++++++ .../.cursor/commands/teach-impeccable.md | 90 +++++++-------- dist/gemini/.gemini/commands/critique.toml | 100 ++++++++++++++++ .../.gemini/commands/teach-impeccable.toml | 92 +++++++-------- public/index.html | 2 +- public/js/data.js | 6 +- .../demos/commands/{review.js => critique.js} | 4 +- public/js/demos/commands/index.js | 4 +- source/commands/{review.md => critique.md} | 10 +- 15 files changed, 735 insertions(+), 262 deletions(-) create mode 100644 .claude/commands/critique.md create mode 100644 dist/claude-code/.claude/commands/critique.md create mode 100644 dist/codex/.codex/prompts/critique.md create mode 100644 dist/cursor/.cursor/commands/critique.md create mode 100644 dist/gemini/.gemini/commands/critique.toml rename public/js/demos/commands/{review.js => critique.js} (97%) rename source/commands/{review.md => critique.md} (92%) diff --git a/.claude/commands/critique.md b/.claude/commands/critique.md new file mode 100644 index 000000000..ea1f8377a --- /dev/null +++ b/.claude/commands/critique.md @@ -0,0 +1,107 @@ +--- +name: critique +description: Evaluate design effectiveness from a UX perspective. Assesses visual hierarchy, information architecture, emotional resonance, and overall design quality with actionable feedback. +context: fork +args: + - name: area + description: The feature or area to critique (optional) + required: false +--- + +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. + +→ *Apply the frontend-design skill for design principles, if not already in context.* + +## Design Critique + +Evaluate the interface across these dimensions: + +### 1. 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? + +### 2. 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? + +### 3. 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"? + +### 4. 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? + +### 5. 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? + +### 6. 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? + +### 7. 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?) + +### 8. 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? + +### 9. 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? + +## Generate Critique Report + +Structure your feedback as a design director would: + +### Overall Impression +A brief gut reaction—what works, what doesn't, and the single biggest opportunity. + +### What's Working +Highlight 2-3 things done well. Be specific about why they work. + +### Priority Issues +The 3-5 most impactful design problems, ordered by importance: + +For each issue: +- **What**: Name the problem clearly +- **Why it matters**: How this hurts users or undermines goals +- **Fix**: What to do about it (be concrete) +- **Command**: Which command to use (`/polish`, `/simplify`, `/bolder`, `/quieter`, etc.) + +### Minor Observations +Quick notes on smaller issues worth addressing. + +### Questions to Consider +Provocative questions that might unlock better solutions: +- "What if the primary action were more prominent?" +- "Does this need to feel this complex?" +- "What would a confident version of this look like?" + +**Remember**: +- Be direct—vague feedback wastes everyone's time +- Be specific—"the submit button" not "some elements" +- Say what's wrong AND why it matters to users +- Give concrete suggestions, not just "consider exploring..." +- Prioritize ruthlessly—if everything is important, nothing is +- Don't soften criticism—developers need honest feedback to ship great design \ No newline at end of file diff --git a/.claude/commands/teach-impeccable.md b/.claude/commands/teach-impeccable.md index d00b1f81b..d8ef7f386 100644 --- a/.claude/commands/teach-impeccable.md +++ b/.claude/commands/teach-impeccable.md @@ -1,76 +1,68 @@ --- name: teach-impeccable -description: One-time setup that gathers comprehensive design context for your project and saves it to your AI config file. Run once to establish persistent design guidelines. +description: One-time setup that gathers design context for your project and saves it to your AI config file. Run once to establish persistent design guidelines. --- -Gather comprehensive design context for this project through a structured conversation, then persist it for all future sessions. +Gather design context for this project, then persist it for all future sessions. -## Gather Design Context +## Step 1: Explore the Codebase -use the AskUserQuestion tool to clarify what you cannot infer. Explore these areas thoroughly: +Before asking questions, thoroughly scan the project to discover what you can: -### 1. Project & Audience -- What is this project? (app, marketing site, dashboard, etc.) -- Who is the primary audience? (developers, consumers, enterprise, etc.) -- What's their technical sophistication? Age range? Key demographics? -- What problem does this solve for them? +- **README and docs**: Project purpose, target audience, any stated goals +- **Package.json / config files**: Tech stack, dependencies, existing design libraries +- **Existing components**: Current design patterns, spacing, typography in use +- **Brand assets**: Logos, favicons, color values already defined +- **Design tokens / CSS variables**: Existing color palettes, font stacks, spacing scales +- **Any style guides or brand documentation** -### 2. Brand & Identity -- Does an existing brand guide or design system exist? Where? -- What are the brand colors, if any? -- What's the brand personality? (professional, playful, luxurious, approachable, etc.) -- Any fonts already in use or required? -- Logos or visual assets to incorporate? +Note what you've learned and what remains unclear. -### 3. Aesthetic Direction -- What's the desired tone? (minimal, bold, elegant, playful, technical, organic, etc.) -- Any reference sites or apps they admire? What specifically about them? -- What should this NOT look like? Any anti-references? +## Step 2: Ask UX-Focused Questions + +use the AskUserQuestion tool to clarify what you cannot infer. Focus only on what you couldn't infer from the codebase: + +### Users & Purpose +- Who uses this? What's their context when using it? +- What job are they trying to get done? +- What emotions should the interface evoke? (confidence, delight, calm, urgency, etc.) + +### Brand & Personality +- How would you describe the brand personality in 3 words? +- Any reference sites or apps that capture the right feel? What specifically about them? +- What should this explicitly NOT look like? Any anti-references? + +### Aesthetic Preferences +- Any strong preferences for visual direction? (minimal, bold, elegant, playful, technical, organic, etc.) - Light mode, dark mode, or both? +- Any colors that must be used or avoided? -### 4. Technical Constraints -- Framework in use? (React, Vue, vanilla, etc.) -- CSS approach? (Tailwind, CSS modules, styled-components, etc.) -- Component library in use or to avoid? -- Performance budget or requirements? -- Browser/device support requirements? +### Accessibility & Inclusion +- Specific accessibility requirements? (WCAG level, known user needs) +- Considerations for reduced motion, color blindness, or other accommodations? -### 5. Accessibility Requirements -- WCAG compliance level needed? (A, AA, AAA) -- Known accessibility requirements? -- Reduced motion considerations? +Skip questions where the answer is already clear from the codebase exploration. -### 6. Content & Scope -- What types of content will be displayed? -- Are there existing components to maintain consistency with? -- What's the scope—full redesign or incremental improvements? +## Step 3: Write Design Context -## Write Design Context - -After gathering responses, create a `## Design Context` section with the collected information, formatted for clarity: +Synthesize your findings and the user's answers into a `## Design Context` section: ```markdown ## Design Context -### Audience -[Summarize target users, their needs, and context] +### Users +[Who they are, their context, the job to be done] -### Brand -[Colors, fonts, personality, existing assets] +### Brand Personality +[Voice, tone, 3-word personality, emotional goals] ### Aesthetic Direction -[Tone, references, anti-references, theme preference] - -### Technical Stack -[Framework, CSS approach, constraints] - -### Accessibility -[Requirements and considerations] +[Visual tone, references, anti-references, theme] ### Design Principles -[Key principles derived from the conversation] +[3-5 principles derived from the conversation that should guide all design decisions] ``` -Write this section to CLAUDE.md in the project root. If the file exists, append or update the Design Context section. If it doesn't exist, create it with this section. +Write this section to CLAUDE.md in the project root. If the file exists, append or update the Design Context section. -Confirm completion and remind the user that this context will now inform all future design work with Impeccable. \ No newline at end of file +Confirm completion and summarize the key design principles that will now guide all future work. \ No newline at end of file diff --git a/dist/claude-code/.claude/commands/critique.md b/dist/claude-code/.claude/commands/critique.md new file mode 100644 index 000000000..ea1f8377a --- /dev/null +++ b/dist/claude-code/.claude/commands/critique.md @@ -0,0 +1,107 @@ +--- +name: critique +description: Evaluate design effectiveness from a UX perspective. Assesses visual hierarchy, information architecture, emotional resonance, and overall design quality with actionable feedback. +context: fork +args: + - name: area + description: The feature or area to critique (optional) + required: false +--- + +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. + +→ *Apply the frontend-design skill for design principles, if not already in context.* + +## Design Critique + +Evaluate the interface across these dimensions: + +### 1. 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? + +### 2. 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? + +### 3. 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"? + +### 4. 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? + +### 5. 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? + +### 6. 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? + +### 7. 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?) + +### 8. 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? + +### 9. 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? + +## Generate Critique Report + +Structure your feedback as a design director would: + +### Overall Impression +A brief gut reaction—what works, what doesn't, and the single biggest opportunity. + +### What's Working +Highlight 2-3 things done well. Be specific about why they work. + +### Priority Issues +The 3-5 most impactful design problems, ordered by importance: + +For each issue: +- **What**: Name the problem clearly +- **Why it matters**: How this hurts users or undermines goals +- **Fix**: What to do about it (be concrete) +- **Command**: Which command to use (`/polish`, `/simplify`, `/bolder`, `/quieter`, etc.) + +### Minor Observations +Quick notes on smaller issues worth addressing. + +### Questions to Consider +Provocative questions that might unlock better solutions: +- "What if the primary action were more prominent?" +- "Does this need to feel this complex?" +- "What would a confident version of this look like?" + +**Remember**: +- Be direct—vague feedback wastes everyone's time +- Be specific—"the submit button" not "some elements" +- Say what's wrong AND why it matters to users +- Give concrete suggestions, not just "consider exploring..." +- Prioritize ruthlessly—if everything is important, nothing is +- Don't soften criticism—developers need honest feedback to ship great design \ No newline at end of file diff --git a/dist/claude-code/.claude/commands/teach-impeccable.md b/dist/claude-code/.claude/commands/teach-impeccable.md index d00b1f81b..d8ef7f386 100644 --- a/dist/claude-code/.claude/commands/teach-impeccable.md +++ b/dist/claude-code/.claude/commands/teach-impeccable.md @@ -1,76 +1,68 @@ --- name: teach-impeccable -description: One-time setup that gathers comprehensive design context for your project and saves it to your AI config file. Run once to establish persistent design guidelines. +description: One-time setup that gathers design context for your project and saves it to your AI config file. Run once to establish persistent design guidelines. --- -Gather comprehensive design context for this project through a structured conversation, then persist it for all future sessions. +Gather design context for this project, then persist it for all future sessions. -## Gather Design Context +## Step 1: Explore the Codebase -use the AskUserQuestion tool to clarify what you cannot infer. Explore these areas thoroughly: +Before asking questions, thoroughly scan the project to discover what you can: -### 1. Project & Audience -- What is this project? (app, marketing site, dashboard, etc.) -- Who is the primary audience? (developers, consumers, enterprise, etc.) -- What's their technical sophistication? Age range? Key demographics? -- What problem does this solve for them? +- **README and docs**: Project purpose, target audience, any stated goals +- **Package.json / config files**: Tech stack, dependencies, existing design libraries +- **Existing components**: Current design patterns, spacing, typography in use +- **Brand assets**: Logos, favicons, color values already defined +- **Design tokens / CSS variables**: Existing color palettes, font stacks, spacing scales +- **Any style guides or brand documentation** -### 2. Brand & Identity -- Does an existing brand guide or design system exist? Where? -- What are the brand colors, if any? -- What's the brand personality? (professional, playful, luxurious, approachable, etc.) -- Any fonts already in use or required? -- Logos or visual assets to incorporate? +Note what you've learned and what remains unclear. -### 3. Aesthetic Direction -- What's the desired tone? (minimal, bold, elegant, playful, technical, organic, etc.) -- Any reference sites or apps they admire? What specifically about them? -- What should this NOT look like? Any anti-references? +## Step 2: Ask UX-Focused Questions + +use the AskUserQuestion tool to clarify what you cannot infer. Focus only on what you couldn't infer from the codebase: + +### Users & Purpose +- Who uses this? What's their context when using it? +- What job are they trying to get done? +- What emotions should the interface evoke? (confidence, delight, calm, urgency, etc.) + +### Brand & Personality +- How would you describe the brand personality in 3 words? +- Any reference sites or apps that capture the right feel? What specifically about them? +- What should this explicitly NOT look like? Any anti-references? + +### Aesthetic Preferences +- Any strong preferences for visual direction? (minimal, bold, elegant, playful, technical, organic, etc.) - Light mode, dark mode, or both? +- Any colors that must be used or avoided? -### 4. Technical Constraints -- Framework in use? (React, Vue, vanilla, etc.) -- CSS approach? (Tailwind, CSS modules, styled-components, etc.) -- Component library in use or to avoid? -- Performance budget or requirements? -- Browser/device support requirements? +### Accessibility & Inclusion +- Specific accessibility requirements? (WCAG level, known user needs) +- Considerations for reduced motion, color blindness, or other accommodations? -### 5. Accessibility Requirements -- WCAG compliance level needed? (A, AA, AAA) -- Known accessibility requirements? -- Reduced motion considerations? +Skip questions where the answer is already clear from the codebase exploration. -### 6. Content & Scope -- What types of content will be displayed? -- Are there existing components to maintain consistency with? -- What's the scope—full redesign or incremental improvements? +## Step 3: Write Design Context -## Write Design Context - -After gathering responses, create a `## Design Context` section with the collected information, formatted for clarity: +Synthesize your findings and the user's answers into a `## Design Context` section: ```markdown ## Design Context -### Audience -[Summarize target users, their needs, and context] +### Users +[Who they are, their context, the job to be done] -### Brand -[Colors, fonts, personality, existing assets] +### Brand Personality +[Voice, tone, 3-word personality, emotional goals] ### Aesthetic Direction -[Tone, references, anti-references, theme preference] - -### Technical Stack -[Framework, CSS approach, constraints] - -### Accessibility -[Requirements and considerations] +[Visual tone, references, anti-references, theme] ### Design Principles -[Key principles derived from the conversation] +[3-5 principles derived from the conversation that should guide all design decisions] ``` -Write this section to CLAUDE.md in the project root. If the file exists, append or update the Design Context section. If it doesn't exist, create it with this section. +Write this section to CLAUDE.md in the project root. If the file exists, append or update the Design Context section. -Confirm completion and remind the user that this context will now inform all future design work with Impeccable. \ No newline at end of file +Confirm completion and summarize the key design principles that will now guide all future work. \ No newline at end of file diff --git a/dist/codex/.codex/prompts/critique.md b/dist/codex/.codex/prompts/critique.md new file mode 100644 index 000000000..e9bba4687 --- /dev/null +++ b/dist/codex/.codex/prompts/critique.md @@ -0,0 +1,102 @@ +--- +description: Evaluate design effectiveness from a UX perspective. Assesses visual hierarchy, information architecture, emotional resonance, and overall design quality with actionable feedback. +argument-hint: [AREA=] +--- + +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. + +→ *Apply the frontend-design skill for design principles, if not already in context.* + +## Design Critique + +Evaluate the interface across these dimensions: + +### 1. 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? + +### 2. 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? + +### 3. 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"? + +### 4. 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? + +### 5. 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? + +### 6. 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? + +### 7. 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?) + +### 8. 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? + +### 9. 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? + +## Generate Critique Report + +Structure your feedback as a design director would: + +### Overall Impression +A brief gut reaction—what works, what doesn't, and the single biggest opportunity. + +### What's Working +Highlight 2-3 things done well. Be specific about why they work. + +### Priority Issues +The 3-5 most impactful design problems, ordered by importance: + +For each issue: +- **What**: Name the problem clearly +- **Why it matters**: How this hurts users or undermines goals +- **Fix**: What to do about it (be concrete) +- **Command**: Which command to use (`/polish`, `/simplify`, `/bolder`, `/quieter`, etc.) + +### Minor Observations +Quick notes on smaller issues worth addressing. + +### Questions to Consider +Provocative questions that might unlock better solutions: +- "What if the primary action were more prominent?" +- "Does this need to feel this complex?" +- "What would a confident version of this look like?" + +**Remember**: +- Be direct—vague feedback wastes everyone's time +- Be specific—"the submit button" not "some elements" +- Say what's wrong AND why it matters to users +- Give concrete suggestions, not just "consider exploring..." +- Prioritize ruthlessly—if everything is important, nothing is +- Don't soften criticism—developers need honest feedback to ship great design \ No newline at end of file diff --git a/dist/codex/.codex/prompts/teach-impeccable.md b/dist/codex/.codex/prompts/teach-impeccable.md index 5f28590e8..8581608c6 100644 --- a/dist/codex/.codex/prompts/teach-impeccable.md +++ b/dist/codex/.codex/prompts/teach-impeccable.md @@ -1,75 +1,67 @@ --- -description: One-time setup that gathers comprehensive design context for your project and saves it to your AI config file. Run once to establish persistent design guidelines. +description: One-time setup that gathers design context for your project and saves it to your AI config file. Run once to establish persistent design guidelines. --- -Gather comprehensive design context for this project through a structured conversation, then persist it for all future sessions. +Gather design context for this project, then persist it for all future sessions. -## Gather Design Context +## Step 1: Explore the Codebase -ask the user directly to clarify what you cannot infer. Explore these areas thoroughly: +Before asking questions, thoroughly scan the project to discover what you can: -### 1. Project & Audience -- What is this project? (app, marketing site, dashboard, etc.) -- Who is the primary audience? (developers, consumers, enterprise, etc.) -- What's their technical sophistication? Age range? Key demographics? -- What problem does this solve for them? +- **README and docs**: Project purpose, target audience, any stated goals +- **Package.json / config files**: Tech stack, dependencies, existing design libraries +- **Existing components**: Current design patterns, spacing, typography in use +- **Brand assets**: Logos, favicons, color values already defined +- **Design tokens / CSS variables**: Existing color palettes, font stacks, spacing scales +- **Any style guides or brand documentation** -### 2. Brand & Identity -- Does an existing brand guide or design system exist? Where? -- What are the brand colors, if any? -- What's the brand personality? (professional, playful, luxurious, approachable, etc.) -- Any fonts already in use or required? -- Logos or visual assets to incorporate? +Note what you've learned and what remains unclear. -### 3. Aesthetic Direction -- What's the desired tone? (minimal, bold, elegant, playful, technical, organic, etc.) -- Any reference sites or apps they admire? What specifically about them? -- What should this NOT look like? Any anti-references? +## Step 2: Ask UX-Focused Questions + +ask the user directly to clarify what you cannot infer. Focus only on what you couldn't infer from the codebase: + +### Users & Purpose +- Who uses this? What's their context when using it? +- What job are they trying to get done? +- What emotions should the interface evoke? (confidence, delight, calm, urgency, etc.) + +### Brand & Personality +- How would you describe the brand personality in 3 words? +- Any reference sites or apps that capture the right feel? What specifically about them? +- What should this explicitly NOT look like? Any anti-references? + +### Aesthetic Preferences +- Any strong preferences for visual direction? (minimal, bold, elegant, playful, technical, organic, etc.) - Light mode, dark mode, or both? +- Any colors that must be used or avoided? -### 4. Technical Constraints -- Framework in use? (React, Vue, vanilla, etc.) -- CSS approach? (Tailwind, CSS modules, styled-components, etc.) -- Component library in use or to avoid? -- Performance budget or requirements? -- Browser/device support requirements? +### Accessibility & Inclusion +- Specific accessibility requirements? (WCAG level, known user needs) +- Considerations for reduced motion, color blindness, or other accommodations? -### 5. Accessibility Requirements -- WCAG compliance level needed? (A, AA, AAA) -- Known accessibility requirements? -- Reduced motion considerations? +Skip questions where the answer is already clear from the codebase exploration. -### 6. Content & Scope -- What types of content will be displayed? -- Are there existing components to maintain consistency with? -- What's the scope—full redesign or incremental improvements? +## Step 3: Write Design Context -## Write Design Context - -After gathering responses, create a `## Design Context` section with the collected information, formatted for clarity: +Synthesize your findings and the user's answers into a `## Design Context` section: ```markdown ## Design Context -### Audience -[Summarize target users, their needs, and context] +### Users +[Who they are, their context, the job to be done] -### Brand -[Colors, fonts, personality, existing assets] +### Brand Personality +[Voice, tone, 3-word personality, emotional goals] ### Aesthetic Direction -[Tone, references, anti-references, theme preference] - -### Technical Stack -[Framework, CSS approach, constraints] - -### Accessibility -[Requirements and considerations] +[Visual tone, references, anti-references, theme] ### Design Principles -[Key principles derived from the conversation] +[3-5 principles derived from the conversation that should guide all design decisions] ``` -Write this section to AGENTS.md in the project root. If the file exists, append or update the Design Context section. If it doesn't exist, create it with this section. +Write this section to AGENTS.md in the project root. If the file exists, append or update the Design Context section. -Confirm completion and remind the user that this context will now inform all future design work with Impeccable. \ No newline at end of file +Confirm completion and summarize the key design principles that will now guide all future work. \ No newline at end of file diff --git a/dist/cursor/.cursor/commands/critique.md b/dist/cursor/.cursor/commands/critique.md new file mode 100644 index 000000000..5580cd569 --- /dev/null +++ b/dist/cursor/.cursor/commands/critique.md @@ -0,0 +1,97 @@ +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. + +→ *Apply the frontend-design skill for design principles, if not already in context.* + +## Design Critique + +Evaluate the interface across these dimensions: + +### 1. 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? + +### 2. 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? + +### 3. 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"? + +### 4. 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? + +### 5. 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? + +### 6. 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? + +### 7. 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?) + +### 8. 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? + +### 9. 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? + +## Generate Critique Report + +Structure your feedback as a design director would: + +### Overall Impression +A brief gut reaction—what works, what doesn't, and the single biggest opportunity. + +### What's Working +Highlight 2-3 things done well. Be specific about why they work. + +### Priority Issues +The 3-5 most impactful design problems, ordered by importance: + +For each issue: +- **What**: Name the problem clearly +- **Why it matters**: How this hurts users or undermines goals +- **Fix**: What to do about it (be concrete) +- **Command**: Which command to use (`/polish`, `/simplify`, `/bolder`, `/quieter`, etc.) + +### Minor Observations +Quick notes on smaller issues worth addressing. + +### Questions to Consider +Provocative questions that might unlock better solutions: +- "What if the primary action were more prominent?" +- "Does this need to feel this complex?" +- "What would a confident version of this look like?" + +**Remember**: +- Be direct—vague feedback wastes everyone's time +- Be specific—"the submit button" not "some elements" +- Say what's wrong AND why it matters to users +- Give concrete suggestions, not just "consider exploring..." +- Prioritize ruthlessly—if everything is important, nothing is +- Don't soften criticism—developers need honest feedback to ship great design \ No newline at end of file diff --git a/dist/cursor/.cursor/commands/teach-impeccable.md b/dist/cursor/.cursor/commands/teach-impeccable.md index 56a1f2813..c932996a1 100644 --- a/dist/cursor/.cursor/commands/teach-impeccable.md +++ b/dist/cursor/.cursor/commands/teach-impeccable.md @@ -1,71 +1,63 @@ -Gather comprehensive design context for this project through a structured conversation, then persist it for all future sessions. +Gather design context for this project, then persist it for all future sessions. -## Gather Design Context +## Step 1: Explore the Codebase -ask the user directly to clarify what you cannot infer. Explore these areas thoroughly: +Before asking questions, thoroughly scan the project to discover what you can: -### 1. Project & Audience -- What is this project? (app, marketing site, dashboard, etc.) -- Who is the primary audience? (developers, consumers, enterprise, etc.) -- What's their technical sophistication? Age range? Key demographics? -- What problem does this solve for them? +- **README and docs**: Project purpose, target audience, any stated goals +- **Package.json / config files**: Tech stack, dependencies, existing design libraries +- **Existing components**: Current design patterns, spacing, typography in use +- **Brand assets**: Logos, favicons, color values already defined +- **Design tokens / CSS variables**: Existing color palettes, font stacks, spacing scales +- **Any style guides or brand documentation** -### 2. Brand & Identity -- Does an existing brand guide or design system exist? Where? -- What are the brand colors, if any? -- What's the brand personality? (professional, playful, luxurious, approachable, etc.) -- Any fonts already in use or required? -- Logos or visual assets to incorporate? +Note what you've learned and what remains unclear. -### 3. Aesthetic Direction -- What's the desired tone? (minimal, bold, elegant, playful, technical, organic, etc.) -- Any reference sites or apps they admire? What specifically about them? -- What should this NOT look like? Any anti-references? +## Step 2: Ask UX-Focused Questions + +ask the user directly to clarify what you cannot infer. Focus only on what you couldn't infer from the codebase: + +### Users & Purpose +- Who uses this? What's their context when using it? +- What job are they trying to get done? +- What emotions should the interface evoke? (confidence, delight, calm, urgency, etc.) + +### Brand & Personality +- How would you describe the brand personality in 3 words? +- Any reference sites or apps that capture the right feel? What specifically about them? +- What should this explicitly NOT look like? Any anti-references? + +### Aesthetic Preferences +- Any strong preferences for visual direction? (minimal, bold, elegant, playful, technical, organic, etc.) - Light mode, dark mode, or both? +- Any colors that must be used or avoided? -### 4. Technical Constraints -- Framework in use? (React, Vue, vanilla, etc.) -- CSS approach? (Tailwind, CSS modules, styled-components, etc.) -- Component library in use or to avoid? -- Performance budget or requirements? -- Browser/device support requirements? +### Accessibility & Inclusion +- Specific accessibility requirements? (WCAG level, known user needs) +- Considerations for reduced motion, color blindness, or other accommodations? -### 5. Accessibility Requirements -- WCAG compliance level needed? (A, AA, AAA) -- Known accessibility requirements? -- Reduced motion considerations? +Skip questions where the answer is already clear from the codebase exploration. -### 6. Content & Scope -- What types of content will be displayed? -- Are there existing components to maintain consistency with? -- What's the scope—full redesign or incremental improvements? +## Step 3: Write Design Context -## Write Design Context - -After gathering responses, create a `## Design Context` section with the collected information, formatted for clarity: +Synthesize your findings and the user's answers into a `## Design Context` section: ```markdown ## Design Context -### Audience -[Summarize target users, their needs, and context] +### Users +[Who they are, their context, the job to be done] -### Brand -[Colors, fonts, personality, existing assets] +### Brand Personality +[Voice, tone, 3-word personality, emotional goals] ### Aesthetic Direction -[Tone, references, anti-references, theme preference] - -### Technical Stack -[Framework, CSS approach, constraints] - -### Accessibility -[Requirements and considerations] +[Visual tone, references, anti-references, theme] ### Design Principles -[Key principles derived from the conversation] +[3-5 principles derived from the conversation that should guide all design decisions] ``` -Write this section to .cursorrules in the project root. If the file exists, append or update the Design Context section. If it doesn't exist, create it with this section. +Write this section to .cursorrules in the project root. If the file exists, append or update the Design Context section. -Confirm completion and remind the user that this context will now inform all future design work with Impeccable. \ No newline at end of file +Confirm completion and summarize the key design principles that will now guide all future work. \ No newline at end of file diff --git a/dist/gemini/.gemini/commands/critique.toml b/dist/gemini/.gemini/commands/critique.toml new file mode 100644 index 000000000..ce5f20ffe --- /dev/null +++ b/dist/gemini/.gemini/commands/critique.toml @@ -0,0 +1,100 @@ +description = "Evaluate design effectiveness from a UX perspective. Assesses visual hierarchy, information architecture, emotional resonance, and overall design quality with actionable feedback." +prompt = """ +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. + +→ *Apply the frontend-design skill for design principles, if not already in context.* + +## Design Critique + +Evaluate the interface across these dimensions: + +### 1. 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? + +### 2. 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? + +### 3. 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"? + +### 4. 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? + +### 5. 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? + +### 6. 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? + +### 7. 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?) + +### 8. 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? + +### 9. 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? + +## Generate Critique Report + +Structure your feedback as a design director would: + +### Overall Impression +A brief gut reaction—what works, what doesn't, and the single biggest opportunity. + +### What's Working +Highlight 2-3 things done well. Be specific about why they work. + +### Priority Issues +The 3-5 most impactful design problems, ordered by importance: + +For each issue: +- **What**: Name the problem clearly +- **Why it matters**: How this hurts users or undermines goals +- **Fix**: What to do about it (be concrete) +- **Command**: Which command to use (`/polish`, `/simplify`, `/bolder`, `/quieter`, etc.) + +### Minor Observations +Quick notes on smaller issues worth addressing. + +### Questions to Consider +Provocative questions that might unlock better solutions: +- "What if the primary action were more prominent?" +- "Does this need to feel this complex?" +- "What would a confident version of this look like?" + +**Remember**: +- Be direct—vague feedback wastes everyone's time +- Be specific—"the submit button" not "some elements" +- Say what's wrong AND why it matters to users +- Give concrete suggestions, not just "consider exploring..." +- Prioritize ruthlessly—if everything is important, nothing is +- Don't soften criticism—developers need honest feedback to ship great design +""" \ No newline at end of file diff --git a/dist/gemini/.gemini/commands/teach-impeccable.toml b/dist/gemini/.gemini/commands/teach-impeccable.toml index 572e19afa..58705c0fb 100644 --- a/dist/gemini/.gemini/commands/teach-impeccable.toml +++ b/dist/gemini/.gemini/commands/teach-impeccable.toml @@ -1,74 +1,66 @@ -description = "One-time setup that gathers comprehensive design context for your project and saves it to your AI config file. Run once to establish persistent design guidelines." +description = "One-time setup that gathers design context for your project and saves it to your AI config file. Run once to establish persistent design guidelines." prompt = """ -Gather comprehensive design context for this project through a structured conversation, then persist it for all future sessions. +Gather design context for this project, then persist it for all future sessions. -## Gather Design Context +## Step 1: Explore the Codebase -ask the user directly to clarify what you cannot infer. Explore these areas thoroughly: +Before asking questions, thoroughly scan the project to discover what you can: -### 1. Project & Audience -- What is this project? (app, marketing site, dashboard, etc.) -- Who is the primary audience? (developers, consumers, enterprise, etc.) -- What's their technical sophistication? Age range? Key demographics? -- What problem does this solve for them? +- **README and docs**: Project purpose, target audience, any stated goals +- **Package.json / config files**: Tech stack, dependencies, existing design libraries +- **Existing components**: Current design patterns, spacing, typography in use +- **Brand assets**: Logos, favicons, color values already defined +- **Design tokens / CSS variables**: Existing color palettes, font stacks, spacing scales +- **Any style guides or brand documentation** -### 2. Brand & Identity -- Does an existing brand guide or design system exist? Where? -- What are the brand colors, if any? -- What's the brand personality? (professional, playful, luxurious, approachable, etc.) -- Any fonts already in use or required? -- Logos or visual assets to incorporate? +Note what you've learned and what remains unclear. -### 3. Aesthetic Direction -- What's the desired tone? (minimal, bold, elegant, playful, technical, organic, etc.) -- Any reference sites or apps they admire? What specifically about them? -- What should this NOT look like? Any anti-references? +## Step 2: Ask UX-Focused Questions + +ask the user directly to clarify what you cannot infer. Focus only on what you couldn't infer from the codebase: + +### Users & Purpose +- Who uses this? What's their context when using it? +- What job are they trying to get done? +- What emotions should the interface evoke? (confidence, delight, calm, urgency, etc.) + +### Brand & Personality +- How would you describe the brand personality in 3 words? +- Any reference sites or apps that capture the right feel? What specifically about them? +- What should this explicitly NOT look like? Any anti-references? + +### Aesthetic Preferences +- Any strong preferences for visual direction? (minimal, bold, elegant, playful, technical, organic, etc.) - Light mode, dark mode, or both? +- Any colors that must be used or avoided? -### 4. Technical Constraints -- Framework in use? (React, Vue, vanilla, etc.) -- CSS approach? (Tailwind, CSS modules, styled-components, etc.) -- Component library in use or to avoid? -- Performance budget or requirements? -- Browser/device support requirements? +### Accessibility & Inclusion +- Specific accessibility requirements? (WCAG level, known user needs) +- Considerations for reduced motion, color blindness, or other accommodations? -### 5. Accessibility Requirements -- WCAG compliance level needed? (A, AA, AAA) -- Known accessibility requirements? -- Reduced motion considerations? +Skip questions where the answer is already clear from the codebase exploration. -### 6. Content & Scope -- What types of content will be displayed? -- Are there existing components to maintain consistency with? -- What's the scope—full redesign or incremental improvements? +## Step 3: Write Design Context -## Write Design Context - -After gathering responses, create a `## Design Context` section with the collected information, formatted for clarity: +Synthesize your findings and the user's answers into a `## Design Context` section: ```markdown ## Design Context -### Audience -[Summarize target users, their needs, and context] +### Users +[Who they are, their context, the job to be done] -### Brand -[Colors, fonts, personality, existing assets] +### Brand Personality +[Voice, tone, 3-word personality, emotional goals] ### Aesthetic Direction -[Tone, references, anti-references, theme preference] - -### Technical Stack -[Framework, CSS approach, constraints] - -### Accessibility -[Requirements and considerations] +[Visual tone, references, anti-references, theme] ### Design Principles -[Key principles derived from the conversation] +[3-5 principles derived from the conversation that should guide all design decisions] ``` -Write this section to GEMINI.md in the project root. If the file exists, append or update the Design Context section. If it doesn't exist, create it with this section. +Write this section to GEMINI.md in the project root. If the file exists, append or update the Design Context section. -Confirm completion and remind the user that this context will now inform all future design work with Impeccable. +Confirm completion and summarize the key design principles that will now guide all future work. """ \ No newline at end of file diff --git a/public/index.html b/public/index.html index 4874a20c3..33a7fc3d6 100644 --- a/public/index.html +++ b/public/index.html @@ -289,7 +289,7 @@

Landing Page Polish

AI-generated landing page refined from generic template to memorable brand experience.

- /review + /critique /polish /animate
diff --git a/public/js/data.js b/public/js/data.js index 94ee14b33..4af3c8593 100644 --- a/public/js/data.js +++ b/public/js/data.js @@ -39,7 +39,7 @@ export const skillReferenceDomains = [ export const commandProcessSteps = { 'teach-impeccable': ['Gather', 'Clarify', 'Document', 'Save'], 'audit': ['Scan', 'Document', 'Prioritize', 'Recommend'], - 'review': ['Evaluate', 'Critique', 'Prioritize', 'Suggest'], + 'critique': ['Evaluate', 'Critique', 'Prioritize', 'Suggest'], 'normalize': ['Analyze', 'Identify', 'Align', 'Verify'], 'polish': ['Review', 'Refine', 'Verify'], 'optimize': ['Profile', 'Identify', 'Improve', 'Measure'], @@ -59,7 +59,7 @@ export const commandProcessSteps = { export const commandCategories = { 'teach-impeccable': 'system', 'audit': 'diagnostic', - 'review': 'diagnostic', + 'critique': 'diagnostic', 'normalize': 'quality', 'polish': 'quality', 'optimize': 'quality', @@ -88,7 +88,7 @@ export const skillRelationships = { export const commandRelationships = { 'teach-impeccable': { flow: 'Setup: One-time project context gathering' }, 'audit': { leadsTo: ['normalize', 'harden', 'optimize', 'adapt', 'clarify'], flow: 'Diagnostic: Technical quality audit' }, - 'review': { leadsTo: ['polish', 'simplify', 'bolder', 'quieter'], flow: 'Diagnostic: UX and design review' }, + 'critique': { leadsTo: ['polish', 'simplify', 'bolder', 'quieter'], flow: 'Diagnostic: UX and design review' }, 'normalize': { combinesWith: ['clarify', 'adapt'], flow: 'Quality: Align with design system' }, 'polish': { flow: 'Quality: Final pass before shipping' }, 'optimize': { flow: 'Quality: Performance improvements' }, diff --git a/public/js/demos/commands/review.js b/public/js/demos/commands/critique.js similarity index 97% rename from public/js/demos/commands/review.js rename to public/js/demos/commands/critique.js index 78a95af57..5ce8b95cf 100644 --- a/public/js/demos/commands/review.js +++ b/public/js/demos/commands/critique.js @@ -1,6 +1,6 @@ -// Review command demo - shows design/UX issues being identified +// Critique command demo - shows design/UX issues being identified export default { - id: 'review', + id: 'critique', caption: 'Confusing design → UX issues identified with fixes', before: ` diff --git a/public/js/demos/commands/index.js b/public/js/demos/commands/index.js index 212485e2c..f42859b35 100644 --- a/public/js/demos/commands/index.js +++ b/public/js/demos/commands/index.js @@ -4,7 +4,7 @@ import animate from "./animate.js"; import bolder from "./bolder.js"; import normalize from "./normalize.js"; import audit from "./audit.js"; -import review from "./review.js"; +import critique from "./critique.js"; import polish from "./polish.js"; import optimize from "./optimize.js"; import harden from "./harden.js"; @@ -22,7 +22,7 @@ export const commandDemos = { bolder, animate, audit, - review, + critique, polish, optimize, harden, diff --git a/source/commands/review.md b/source/commands/critique.md similarity index 92% rename from source/commands/review.md rename to source/commands/critique.md index 92eeb877a..d486c12bb 100644 --- a/source/commands/review.md +++ b/source/commands/critique.md @@ -1,18 +1,18 @@ --- -name: review +name: critique description: Evaluate design effectiveness from a UX perspective. Assesses visual hierarchy, information architecture, emotional resonance, and overall design quality with actionable feedback. context: fork args: - name: area - description: The feature or area to review (optional) + description: The feature or area to critique (optional) required: false --- -Conduct a holistic design review, evaluating whether the interface actually works—not just technically, but as a designed experience. Think like a design director giving feedback. +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. → *Apply the frontend-design skill for design principles, if not already in context.* -## Design Review +## Design Critique Evaluate the interface across these dimensions: @@ -70,7 +70,7 @@ Evaluate the interface across these dimensions: - Are labels and buttons unambiguous? - Does error copy help users fix the problem? -## Generate Review Report +## Generate Critique Report Structure your feedback as a design director would: