From 8531503f2cc4c397c9da8f4d222398cc23e852e4 Mon Sep 17 00:00:00 2001 From: Paul Bakaus Date: Fri, 3 Apr 2026 20:07:02 -0700 Subject: [PATCH] Rename /craft to /shape, add /impeccable craft, remove "--" pattern - Rename /craft skill to /shape and make it planning-only (no code output) - Add /impeccable craft sub-command that calls /shape, loads references, builds with visual iteration until delightful - Replace all " -- " (em dash substitutes) with proper punctuation across all skill files and index.html - Move v1.6 changelog entry to "View older releases" section Co-Authored-By: Claude Opus 4.6 (1M context) --- .agents/skills/audit/SKILL.md | 4 +- .agents/skills/craft/SKILL.md | 97 ------------------- .agents/skills/critique/SKILL.md | 80 +++++++-------- .agents/skills/impeccable/SKILL.md | 10 +- .agents/skills/impeccable/reference/craft.md | 70 +++++++++++++ .agents/skills/shape/SKILL.md | 95 ++++++++++++++++++ .agents/skills/validate/SKILL.md | 14 +-- .claude/skills/audit/SKILL.md | 4 +- .claude/skills/craft/SKILL.md | 97 ------------------- .claude/skills/critique/SKILL.md | 80 +++++++-------- .claude/skills/impeccable/SKILL.md | 10 +- .claude/skills/impeccable/reference/craft.md | 70 +++++++++++++ .claude/skills/shape/SKILL.md | 95 ++++++++++++++++++ .claude/skills/validate/SKILL.md | 14 +-- .codex/skills/audit/SKILL.md | 4 +- .codex/skills/craft/SKILL.md | 96 ------------------ .codex/skills/critique/SKILL.md | 80 +++++++-------- .codex/skills/impeccable/SKILL.md | 10 +- .codex/skills/impeccable/reference/craft.md | 70 +++++++++++++ .codex/skills/shape/SKILL.md | 94 ++++++++++++++++++ .codex/skills/validate/SKILL.md | 14 +-- .cursor/skills/audit/SKILL.md | 4 +- .cursor/skills/craft/SKILL.md | 95 ------------------ .cursor/skills/critique/SKILL.md | 80 +++++++-------- .cursor/skills/impeccable/SKILL.md | 8 +- .cursor/skills/impeccable/reference/craft.md | 70 +++++++++++++ .cursor/skills/shape/SKILL.md | 93 ++++++++++++++++++ .cursor/skills/validate/SKILL.md | 14 +-- .gemini/skills/audit/SKILL.md | 4 +- .gemini/skills/craft/SKILL.md | 95 ------------------ .gemini/skills/critique/SKILL.md | 80 +++++++-------- .gemini/skills/impeccable/SKILL.md | 8 +- .gemini/skills/impeccable/reference/craft.md | 70 +++++++++++++ .gemini/skills/shape/SKILL.md | 93 ++++++++++++++++++ .gemini/skills/validate/SKILL.md | 14 +-- .kiro/skills/audit/SKILL.md | 4 +- .kiro/skills/craft/SKILL.md | 95 ------------------ .kiro/skills/critique/SKILL.md | 80 +++++++-------- .kiro/skills/impeccable/SKILL.md | 8 +- .kiro/skills/impeccable/reference/craft.md | 70 +++++++++++++ .kiro/skills/shape/SKILL.md | 93 ++++++++++++++++++ .kiro/skills/validate/SKILL.md | 14 +-- .opencode/skills/audit/SKILL.md | 4 +- .opencode/skills/craft/SKILL.md | 97 ------------------- .opencode/skills/critique/SKILL.md | 80 +++++++-------- .opencode/skills/impeccable/SKILL.md | 10 +- .../skills/impeccable/reference/craft.md | 70 +++++++++++++ .opencode/skills/shape/SKILL.md | 95 ++++++++++++++++++ .opencode/skills/validate/SKILL.md | 14 +-- .pi/skills/audit/SKILL.md | 4 +- .pi/skills/craft/SKILL.md | 95 ------------------ .pi/skills/critique/SKILL.md | 80 +++++++-------- .pi/skills/impeccable/SKILL.md | 8 +- .pi/skills/impeccable/reference/craft.md | 70 +++++++++++++ .pi/skills/shape/SKILL.md | 93 ++++++++++++++++++ .pi/skills/validate/SKILL.md | 14 +-- .rovodev/skills/audit/SKILL.md | 4 +- .rovodev/skills/craft/SKILL.md | 97 ------------------- .rovodev/skills/critique/SKILL.md | 80 +++++++-------- .rovodev/skills/impeccable/SKILL.md | 10 +- .rovodev/skills/impeccable/reference/craft.md | 70 +++++++++++++ .rovodev/skills/shape/SKILL.md | 95 ++++++++++++++++++ .rovodev/skills/validate/SKILL.md | 14 +-- .trae-cn/skills/audit/SKILL.md | 4 +- .trae-cn/skills/craft/SKILL.md | 97 ------------------- .trae-cn/skills/critique/SKILL.md | 80 +++++++-------- .trae-cn/skills/impeccable/SKILL.md | 10 +- .trae-cn/skills/impeccable/reference/craft.md | 70 +++++++++++++ .trae-cn/skills/shape/SKILL.md | 95 ++++++++++++++++++ .trae-cn/skills/validate/SKILL.md | 14 +-- .trae/skills/audit/SKILL.md | 4 +- .trae/skills/craft/SKILL.md | 97 ------------------- .trae/skills/critique/SKILL.md | 80 +++++++-------- .trae/skills/impeccable/SKILL.md | 10 +- .trae/skills/impeccable/reference/craft.md | 70 +++++++++++++ .trae/skills/shape/SKILL.md | 95 ++++++++++++++++++ .trae/skills/validate/SKILL.md | 14 +-- public/index.html | 44 ++++----- source/skills/craft/SKILL.md | 97 ------------------- source/skills/critique/SKILL.md | 76 +++++++-------- source/skills/impeccable/SKILL.md | 10 +- source/skills/impeccable/reference/craft.md | 70 +++++++++++++ source/skills/shape/SKILL.md | 95 ++++++++++++++++++ source/skills/validate/SKILL.md | 14 +-- 84 files changed, 2669 insertions(+), 1781 deletions(-) delete mode 100644 .agents/skills/craft/SKILL.md create mode 100644 .agents/skills/impeccable/reference/craft.md create mode 100644 .agents/skills/shape/SKILL.md delete mode 100644 .claude/skills/craft/SKILL.md create mode 100644 .claude/skills/impeccable/reference/craft.md create mode 100644 .claude/skills/shape/SKILL.md delete mode 100644 .codex/skills/craft/SKILL.md create mode 100644 .codex/skills/impeccable/reference/craft.md create mode 100644 .codex/skills/shape/SKILL.md delete mode 100644 .cursor/skills/craft/SKILL.md create mode 100644 .cursor/skills/impeccable/reference/craft.md create mode 100644 .cursor/skills/shape/SKILL.md delete mode 100644 .gemini/skills/craft/SKILL.md create mode 100644 .gemini/skills/impeccable/reference/craft.md create mode 100644 .gemini/skills/shape/SKILL.md delete mode 100644 .kiro/skills/craft/SKILL.md create mode 100644 .kiro/skills/impeccable/reference/craft.md create mode 100644 .kiro/skills/shape/SKILL.md delete mode 100644 .opencode/skills/craft/SKILL.md create mode 100644 .opencode/skills/impeccable/reference/craft.md create mode 100644 .opencode/skills/shape/SKILL.md delete mode 100644 .pi/skills/craft/SKILL.md create mode 100644 .pi/skills/impeccable/reference/craft.md create mode 100644 .pi/skills/shape/SKILL.md delete mode 100644 .rovodev/skills/craft/SKILL.md create mode 100644 .rovodev/skills/impeccable/reference/craft.md create mode 100644 .rovodev/skills/shape/SKILL.md delete mode 100644 .trae-cn/skills/craft/SKILL.md create mode 100644 .trae-cn/skills/impeccable/reference/craft.md create mode 100644 .trae-cn/skills/shape/SKILL.md delete mode 100644 .trae/skills/craft/SKILL.md create mode 100644 .trae/skills/impeccable/reference/craft.md create mode 100644 .trae/skills/shape/SKILL.md delete mode 100644 source/skills/craft/SKILL.md create mode 100644 source/skills/impeccable/reference/craft.md create mode 100644 source/skills/shape/SKILL.md diff --git a/.agents/skills/audit/SKILL.md b/.agents/skills/audit/SKILL.md index dcabe5eea..fa777e5c0 100644 --- a/.agents/skills/audit/SKILL.md +++ b/.agents/skills/audit/SKILL.md @@ -108,7 +108,7 @@ For each issue, document: - **Impact**: How it affects users - **WCAG/Standard**: Which standard it violates (if applicable) - **Recommendation**: How to fix it -- **Suggested command**: Which command to use (prefer: /animate, /validate, /quieter, /craft, /optimize, /adapt, /clarify, /distill, /delight, /onboard, /normalize, /audit, /harden, /polish, /extract, /bolder, /arrange, /typeset, /critique, /colorize, /overdrive) +- **Suggested command**: Which command to use (prefer: /animate, /validate, /quieter, /shape, /optimize, /adapt, /clarify, /distill, /delight, /onboard, /normalize, /audit, /harden, /polish, /extract, /bolder, /arrange, /typeset, /critique, /colorize, /overdrive) ### Patterns & Systemic Issues @@ -127,7 +127,7 @@ List recommended commands in priority order (P0 first, then P1, then P2): 1. **[P?] `/command-name`** — Brief description (specific context from audit findings) 2. **[P?] `/command-name`** — Brief description (specific context) -**Rules**: Only recommend commands from: /animate, /validate, /quieter, /craft, /optimize, /adapt, /clarify, /distill, /delight, /onboard, /normalize, /audit, /harden, /polish, /extract, /bolder, /arrange, /typeset, /critique, /colorize, /overdrive. Map findings to the most appropriate command. End with `/polish` as the final step if any fixes were recommended. +**Rules**: Only recommend commands from: /animate, /validate, /quieter, /shape, /optimize, /adapt, /clarify, /distill, /delight, /onboard, /normalize, /audit, /harden, /polish, /extract, /bolder, /arrange, /typeset, /critique, /colorize, /overdrive. Map findings to the most appropriate command. End with `/polish` as the final step if any fixes were recommended. After presenting the summary, tell the user: diff --git a/.agents/skills/craft/SKILL.md b/.agents/skills/craft/SKILL.md deleted file mode 100644 index 419dcd8ad..000000000 --- a/.agents/skills/craft/SKILL.md +++ /dev/null @@ -1,97 +0,0 @@ ---- -name: craft -description: Design and build ideal UX+UI for a feature through guided discovery. Interviews the user about purpose, audience, and design goals before implementing. Use when building a new feature, redesigning an existing one, or when the user wants a thoughtful, user-centered design process rather than jumping straight to code. -user-invocable: true -argument-hint: "[feature to design]" ---- - -## MANDATORY PREPARATION - -Invoke /impeccable -- it contains design principles, anti-patterns, and the **Context Gathering Protocol**. Follow the protocol before proceeding -- if no design context exists yet, you MUST run /impeccable teach first. - ---- - -Build the ideal UX and UI for a feature. This skill is about getting the design RIGHT before writing code -- through structured discovery, not guesswork. - -**Scope**: UX + UI design and implementation. Out of scope: building the underlying business logic, backend, or data layer. If the feature needs backend work, note what's needed but focus on the interface. - -## Philosophy - -Most AI-generated UIs fail not because of bad code, but because of skipped thinking. They jump to "here's a card grid" without asking "what is the user trying to accomplish?" This skill inverts that: understand deeply, then build precisely. - -## Phase 1: Discovery Interview - -**Do NOT write any code during this phase.** Your only job is to understand the feature deeply enough to make excellent design decisions. - -Ask these questions in conversation, adapting based on answers. Don't dump them all at once -- have a natural dialogue. ask the user directly to clarify what you cannot infer. - -### Purpose & Context -- What is this feature for? What problem does it solve? -- Who specifically will use it? (Not "users" -- be specific: role, context, frequency) -- What does success look like? How will you know this feature is working? -- What's the user's state of mind when they reach this feature? (Rushed? Exploring? Anxious? Focused?) - -### Content & Data -- What content or data does this feature display or collect? -- What are the realistic ranges? (Minimum, typical, maximum -- e.g., 0 items, 5 items, 500 items) -- What are the edge cases? (Empty state, error state, first-time use, power user) -- Is any content dynamic? What changes and how often? - -### Design Goals -- What's the single most important thing a user should do or understand here? -- What should this feel like? (Fast/efficient? Calm/trustworthy? Fun/playful? Premium/refined?) -- Are there existing patterns in the product this should be consistent with? -- Are there specific examples (inside or outside the product) that capture what you're going for? - -### Constraints -- Are there technical constraints? (Framework, performance budget, browser support) -- Are there content constraints? (Localization, dynamic text length, user-generated content) -- Mobile/responsive requirements? -- Accessibility requirements beyond WCAG AA? - -### Anti-Goals -- What should this NOT be? What would be a wrong direction? -- What's the biggest risk of getting this wrong? - -## Phase 2: Design Synthesis - -After the interview, synthesize your understanding before touching code. Present this back to the user for confirmation: - -1. **Feature brief** (2-3 sentences): What this is, who it's for, what it needs to accomplish -2. **Primary user action**: The one thing that matters most -3. **Design direction**: How this should feel, what aesthetic approach fits -4. **Key states**: List every state the feature needs (default, empty, loading, error, success, edge cases) -5. **Open questions**: Anything unresolved that might change the approach - -ask the user directly to clarify what you cannot infer. -- get explicit confirmation before proceeding. If the user disagrees with your synthesis, revisit the relevant discovery questions. - -## Phase 3: Implementation - -Now build it. Use /impeccable as your design engine -- follow its principles, consult its references, avoid its anti-patterns. - -### Implementation Order -1. **Structure first**: HTML/semantic structure for the primary state. No styling yet. -2. **Layout and spacing**: Establish the spatial rhythm and visual hierarchy. -3. **Typography and color**: Apply the type scale and color system. -4. **Interactive states**: Hover, focus, active, disabled. -5. **Edge case states**: Empty, loading, error, overflow, first-run. -6. **Motion**: Purposeful transitions and animations (if appropriate). -7. **Responsive**: Adapt for different viewports -- don't just shrink, redesign for the context. - -### During Implementation -- Test with real (or realistic) data at every step, not placeholder text -- Check each state as you build it, not all at the end -- If you discover a design question during implementation, stop and ask rather than guessing -- Every visual choice should trace back to something learned in discovery - -## Phase 4: Validation - -After implementation, run /validate on your work. Fix any P0 or P1 issues before presenting to the user. - -Then present the result: -- Show the feature in its primary state -- Walk through the key states (empty, error, responsive) -- Explain design decisions that connect back to what you learned in discovery -- Ask for feedback: "What's working? What isn't?" - -Iterate based on feedback. Good design is rarely right on the first pass. \ No newline at end of file diff --git a/.agents/skills/critique/SKILL.md b/.agents/skills/critique/SKILL.md index 9111420bc..3b59cca66 100644 --- a/.agents/skills/critique/SKILL.md +++ b/.agents/skills/critique/SKILL.md @@ -9,21 +9,21 @@ argument-hint: "[area (feature, page, component...)]" ### Step 1: Preparation -Invoke /impeccable -- it contains design principles, anti-patterns, and the **Context Gathering Protocol**. Follow the protocol before proceeding -- if no design context exists yet, you MUST run /impeccable teach first. Additionally gather: what the interface is trying to accomplish. +Invoke /impeccable, which contains design principles, anti-patterns, and the **Context Gathering Protocol**. Follow the protocol before proceeding. If no design context exists yet, you MUST run /impeccable teach first. Additionally gather: what the interface is trying to accomplish. ### Step 2: Gather Assessments Launch two independent assessments. **Neither must see the other's output** to avoid bias. -You SHOULD delegate each assessment to a separate sub-agent for independence. Use your environment's agent spawning mechanism -- e.g., Claude Code's `Agent` tool, or Codex's subagent spawning ("spawn two agents in parallel"). Sub-agents should return their findings as structured text -- do NOT output findings to the user yet. +You SHOULD delegate each assessment to a separate sub-agent for independence. Use your environment's agent spawning mechanism (e.g., Claude Code's `Agent` tool, or Codex's subagent spawning). Sub-agents should return their findings as structured text. Do NOT output findings to the user yet. If sub-agents are not available in the current environment, complete each assessment sequentially, writing findings to internal notes before proceeding. -**Tab isolation**: When browser automation is available, each assessment MUST create its own new tab -- never reuse an existing tab, even if one is already open at the correct URL. This prevents the two assessments from interfering with each other's page state. +**Tab isolation**: When browser automation is available, each assessment MUST create its own new tab. Never reuse an existing tab, even if one is already open at the correct URL. This prevents the two assessments from interfering with each other's page state. #### Assessment A: LLM Design Review -Read the relevant source files (HTML, CSS, JS/TS) and, if browser automation is available, visually inspect the live page. **Create a new tab** for this -- do not reuse existing tabs. After navigation, label the tab by setting the document title: +Read the relevant source files (HTML, CSS, JS/TS) and, if browser automation is available, visually inspect the live page. **Create a new tab** for this; do not reuse existing tabs. After navigation, label the tab by setting the document title: ```javascript document.title = '[LLM] ' + document.title; ``` @@ -34,8 +34,8 @@ Think like a design director. Evaluate: **Holistic Design Review**: 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). **Cognitive Load** (consult [cognitive-load](reference/cognitive-load.md)): -- Run the 8-item cognitive load checklist. Report failure count: 0--1 = low (good), 2--3 = moderate, 4+ = critical. -- Count visible options at each decision point -- if >4, flag it. +- Run the 8-item cognitive load checklist. Report failure count: 0-1 = low (good), 2-3 = moderate, 4+ = critical. +- Count visible options at each decision point. If >4, flag it. - Check for progressive disclosure: is complexity revealed only when needed? **Emotional Journey**: @@ -44,9 +44,9 @@ Think like a design director. Evaluate: - **Emotional valleys**: Check for anxiety spikes at high-stakes moments (payment, delete, commit). Are there design interventions (progress indicators, reassurance copy, undo options)? **Nielsen's Heuristics** (consult [heuristics-scoring](reference/heuristics-scoring.md)): -Score each of the 10 heuristics 0--4. This scoring will be presented in the report. +Score each of the 10 heuristics 0-4. This scoring will be presented in the report. -Return structured findings covering: AI slop verdict, heuristic scores, cognitive load assessment, what's working (2--3 items), priority issues (3--5 with what/why/fix), minor observations, and provocative questions. +Return structured findings covering: AI slop verdict, heuristic scores, cognitive load assessment, what's working (2-3 items), priority issues (3-5 with what/why/fix), minor observations, and provocative questions. #### Assessment B: Automated Detection @@ -65,37 +65,37 @@ npx impeccable --json [--fast] [target] **Browser visualization** (when browser automation tools are available AND the target is a viewable page): -The overlay is a **visual aid for the user** -- it highlights issues directly in their browser. Do NOT scroll through the page to screenshot overlays. Instead, read the console output to get the results programmatically. +The overlay is a **visual aid for the user**. It highlights issues directly in their browser. Do NOT scroll through the page to screenshot overlays. Instead, read the console output to get the results programmatically. 1. **Start the live detection server**: ```bash npx impeccable live & ``` Note the port printed to stdout (auto-assigned). Use `--port=PORT` to fix it. -2. **Create a new tab** and navigate to the page (use dev server URL for local files, or direct URL) -- do not reuse existing tabs +2. **Create a new tab** and navigate to the page (use dev server URL for local files, or direct URL). Do not reuse existing tabs. 3. **Label the tab** via `javascript_tool` so the user can distinguish it: ```javascript document.title = '[Human] ' + document.title; ``` -4. **Scroll to top** -- ensure the page is scrolled to the very top before injection +4. **Scroll to top** to ensure the page is scrolled to the very top before injection 5. **Inject** via `javascript_tool` (replace PORT with the port from step 1): ```javascript const s = document.createElement('script'); s.src = 'http://localhost:PORT/detect.js'; document.head.appendChild(s); ``` -6. Wait 2--3 seconds for the detector to render overlays -7. **Read results from console** using `read_console_messages` with pattern `impeccable` -- the detector logs all findings with the `[impeccable]` prefix. Do NOT scroll through the page to take screenshots of the overlays. +6. Wait 2-3 seconds for the detector to render overlays +7. **Read results from console** using `read_console_messages` with pattern `impeccable`. The detector logs all findings with the `[impeccable]` prefix. Do NOT scroll through the page to take screenshots of the overlays. 8. **Cleanup**: Stop the live server when done: ```bash npx impeccable live stop ``` -For multi-view targets, inject on 3--5 representative pages. If injection fails, continue with CLI results only. +For multi-view targets, inject on 3-5 representative pages. If injection fails, continue with CLI results only. Return: CLI findings (JSON), browser console findings (if applicable), and any false positives noted. ### Step 3: Generate Combined Critique Report -Synthesize both assessments into a single report. Do NOT simply concatenate -- weave the findings together, noting where the LLM review and detector agree, where the detector caught issues the LLM missed, and where detector findings are false positives. +Synthesize both assessments into a single report. Do NOT simply concatenate. Weave the findings together, noting where the LLM review and detector agree, where the detector caught issues the LLM missed, and where detector findings are false positives. Structure your feedback as a design director would: @@ -106,7 +106,7 @@ Present the Nielsen's 10 heuristics scores as a table: | # | Heuristic | Score | Key Issue | |---|-----------|-------|-----------| -| 1 | Visibility of System Status | ? | [specific finding or "--" if solid] | +| 1 | Visibility of System Status | ? | [specific finding or "n/a" if solid] | | 2 | Match System / Real World | ? | | | 3 | User Control and Freedom | ? | | | 4 | Consistency and Standards | ? | | @@ -118,7 +118,7 @@ Present the Nielsen's 10 heuristics scores as a table: | 10 | Help and Documentation | ? | | | **Total** | | **??/40** | **[Rating band]** | -Be honest with scores. A 4 means genuinely excellent. Most real interfaces score 20--32. +Be honest with scores. A 4 means genuinely excellent. Most real interfaces score 20-32. #### Anti-Patterns Verdict @@ -131,24 +131,24 @@ Be honest with scores. A 4 means genuinely excellent. Most real interfaces score **Visual overlays** (if browser was used): Tell the user that overlays are now visible in the **[Human]** tab in their browser, highlighting the detected issues. Summarize what the console output reported. #### Overall Impression -A brief gut reaction -- what works, what doesn't, and the single biggest opportunity. +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. +Highlight 2-3 things done well. Be specific about why they work. #### Priority Issues -The 3--5 most impactful design problems, ordered by importance. +The 3-5 most impactful design problems, ordered by importance. -For each issue, tag with **P0--P3 severity** (consult [heuristics-scoring](reference/heuristics-scoring.md) for severity definitions): +For each issue, tag with **P0-P3 severity** (consult [heuristics-scoring](reference/heuristics-scoring.md) for severity definitions): - **[P?] What**: Name the problem clearly - **Why it matters**: How this hurts users or undermines goals - **Fix**: What to do about it (be concrete) -- **Suggested command**: Which command could address this (from: /animate, /validate, /quieter, /craft, /optimize, /adapt, /clarify, /distill, /delight, /onboard, /normalize, /audit, /harden, /polish, /extract, /bolder, /arrange, /typeset, /critique, /colorize, /overdrive) +- **Suggested command**: Which command could address this (from: /animate, /validate, /quieter, /shape, /optimize, /adapt, /clarify, /distill, /delight, /onboard, /normalize, /audit, /harden, /polish, /extract, /bolder, /arrange, /typeset, /critique, /colorize, /overdrive) #### Persona Red Flags > *Consult [personas](reference/personas.md)* -Auto-select 2--3 personas most relevant to this interface type (use the selection table in the reference). If `.github/copilot-instructions.md` contains a `## Design Context` section from `impeccable teach`, also generate 1--2 project-specific personas from the audience/brand info. +Auto-select 2-3 personas most relevant to this interface type (use the selection table in the reference). If `.github/copilot-instructions.md` contains a `## Design Context` section from `impeccable teach`, also generate 1-2 project-specific personas from the audience/brand info. For each selected persona, walk through the primary user action and list specific red flags found: @@ -156,7 +156,7 @@ For each selected persona, walk through the primary user action and list specifi **Jordan (First-Timer)**: Icon-only nav in sidebar. Technical jargon in error messages ("404 Not Found"). No visible help. Will abandon at step 2. -Be specific -- name the exact elements and interactions that fail each persona. Don't write generic persona descriptions; write what broke for them. +Be specific. Name the exact elements and interactions that fail each persona. Don't write generic persona descriptions; write what broke for them. #### Minor Observations Quick notes on smaller issues worth addressing. @@ -168,32 +168,32 @@ Provocative questions that might unlock better solutions: - "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 +- 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 +- Prioritize ruthlessly. If everything is important, nothing is. +- Don't soften criticism. Developers need honest feedback to ship great design. ### Step 4: Ask the User **After presenting findings**, use targeted questions based on what was actually found. ask the user directly to clarify what you cannot infer. These answers will shape the action plan. -Ask questions along these lines (adapt to the specific findings -- do NOT ask generic questions): +Ask questions along these lines (adapt to the specific findings; do NOT ask generic questions): -1. **Priority direction**: Based on the issues found, ask which category matters most to the user right now. For example: "I found problems with visual hierarchy, color usage, and information overload. Which area should we tackle first?" Offer the top 2--3 issue categories as options. +1. **Priority direction**: Based on the issues found, ask which category matters most to the user right now. For example: "I found problems with visual hierarchy, color usage, and information overload. Which area should we tackle first?" Offer the top 2-3 issue categories as options. -2. **Design intent**: If the critique found a tonal mismatch, ask whether it was intentional. For example: "The interface feels clinical and corporate. Is that the intended tone, or should it feel warmer/bolder/more playful?" Offer 2--3 tonal directions as options based on what would fix the issues found. +2. **Design intent**: If the critique found a tonal mismatch, ask whether it was intentional. For example: "The interface feels clinical and corporate. Is that the intended tone, or should it feel warmer/bolder/more playful?" Offer 2-3 tonal directions as options based on what would fix the issues found. 3. **Scope**: Ask how much the user wants to take on. For example: "I found N issues. Want to address everything, or focus on the top 3?" Offer scope options like "Top 3 only", "All issues", "Critical issues only". -4. **Constraints** (optional -- only ask if relevant): If the findings touch many areas, ask if anything is off-limits. For example: "Should any sections stay as-is?" This prevents the plan from touching things the user considers done. +4. **Constraints** (optional; only ask if relevant): If the findings touch many areas, ask if anything is off-limits. For example: "Should any sections stay as-is?" This prevents the plan from touching things the user considers done. **Rules for questions**: -- Every question must reference specific findings from the report -- never ask generic "who is your audience?" questions -- Keep it to 2--4 questions maximum -- respect the user's time -- Offer concrete options, not open-ended prompts -- If findings are straightforward (e.g., only 1--2 clear issues), skip questions and go directly to Step 5 +- Every question must reference specific findings from the report. Never ask generic "who is your audience?" questions. +- Keep it to 2-4 questions maximum. Respect the user's time. +- Offer concrete options, not open-ended prompts. +- If findings are straightforward (e.g., only 1-2 clear issues), skip questions and go directly to Step 5. ### Step 5: Recommended Actions @@ -203,12 +203,12 @@ Ask questions along these lines (adapt to the specific findings -- do NOT ask ge List recommended commands in priority order, based on the user's answers: -1. **`/command-name`** -- Brief description of what to fix (specific context from critique findings) -2. **`/command-name`** -- Brief description (specific context) +1. **`/command-name`**: Brief description of what to fix (specific context from critique findings) +2. **`/command-name`**: Brief description (specific context) ... **Rules for recommendations**: -- Only recommend commands from: /animate, /validate, /quieter, /craft, /optimize, /adapt, /clarify, /distill, /delight, /onboard, /normalize, /audit, /harden, /polish, /extract, /bolder, /arrange, /typeset, /critique, /colorize, /overdrive +- Only recommend commands from: /animate, /validate, /quieter, /shape, /optimize, /adapt, /clarify, /distill, /delight, /onboard, /normalize, /audit, /harden, /polish, /extract, /bolder, /arrange, /typeset, /critique, /colorize, /overdrive - Order by the user's stated priorities first, then by impact - Each item's description should carry enough context that the command knows what to focus on - Map each Priority Issue to the appropriate command diff --git a/.agents/skills/impeccable/SKILL.md b/.agents/skills/impeccable/SKILL.md index dca3c0588..586e026b8 100644 --- a/.agents/skills/impeccable/SKILL.md +++ b/.agents/skills/impeccable/SKILL.md @@ -1,8 +1,8 @@ --- name: impeccable -description: Create distinctive, production-grade frontend interfaces with high design quality. Generates creative, polished code that avoids generic AI aesthetics. Use when the user asks to build web components, pages, artifacts, posters, or applications, or when any design skill requires project context. Call with 'teach' argument to run design context setup. +description: Create distinctive, production-grade frontend interfaces with high design quality. Generates creative, polished code that avoids generic AI aesthetics. Use when the user asks to build web components, pages, artifacts, posters, or applications, or when any design skill requires project context. Call with 'craft' to run the full shape-then-build flow, or 'teach' for design context setup. user-invocable: true -argument-hint: "[teach]" +argument-hint: "[craft|teach]" license: Apache 2.0. Based on Anthropic's frontend-design skill. See NOTICE.md for attribution. --- @@ -150,6 +150,12 @@ Remember: the model is capable of extraordinary creative work. Don't hold back. --- +## Craft Mode + +If this skill is invoked with the argument "craft" (e.g., `/impeccable craft [feature description]`), follow the [craft flow](reference/craft.md). Pass any additional arguments as the feature description. + +--- + ## Teach Mode If this skill is invoked with the argument "teach" (e.g., `/impeccable teach`), skip all design work above and instead run the teach flow below. This is a one-time setup that gathers design context for the project. diff --git a/.agents/skills/impeccable/reference/craft.md b/.agents/skills/impeccable/reference/craft.md new file mode 100644 index 000000000..d2961057f --- /dev/null +++ b/.agents/skills/impeccable/reference/craft.md @@ -0,0 +1,70 @@ +# Craft Flow + +Build a feature with impeccable UX and UI quality through a structured process: shape the design, load the right references, then build and iterate visually until the result is delightful. + +## Step 1: Shape the Design + +Run /shape, passing along whatever feature description the user provided. + +Wait for the design brief to be fully confirmed before proceeding. The brief is your blueprint, and every implementation decision should trace back to it. + +If the user has already run /shape and has a confirmed design brief, skip this step and use the existing brief. + +## Step 2: Load References + +Based on the design brief's "Recommended References" section, consult the relevant impeccable reference files. At minimum, always consult: + +- [spatial-design.md](spatial-design.md) for layout and spacing +- [typography.md](typography.md) for type hierarchy + +Then add references based on the brief's needs: +- Complex interactions or forms? Consult [interaction-design.md](interaction-design.md) +- Animation or transitions? Consult [motion-design.md](motion-design.md) +- Color-heavy or themed? Consult [color-and-contrast.md](color-and-contrast.md) +- Responsive requirements? Consult [responsive-design.md](responsive-design.md) +- Heavy on copy, labels, or errors? Consult [ux-writing.md](ux-writing.md) + +## Step 3: Build + +Implement the feature following the design brief. Work in this order: + +1. **Structure first**: HTML/semantic structure for the primary state. No styling yet. +2. **Layout and spacing**: Establish the spatial rhythm and visual hierarchy. +3. **Typography and color**: Apply the type scale and color system. +4. **Interactive states**: Hover, focus, active, disabled. +5. **Edge case states**: Empty, loading, error, overflow, first-run. +6. **Motion**: Purposeful transitions and animations (if appropriate). +7. **Responsive**: Adapt for different viewports. Don't just shrink; redesign for the context. + +### During Build +- Test with real (or realistic) data at every step, not placeholder text +- Check each state as you build it, not all at the end +- If you discover a design question, stop and ask rather than guessing +- Every visual choice should trace back to something in the design brief + +## Step 4: Visual Iteration + +**This step is critical.** Do not stop after the first implementation pass. + +Open the result in a browser window. If browser automation tools are available, use them to navigate to the page and visually inspect the result. If not, ask the user to open it and provide feedback. + +Iterate through these checks visually: + +1. **Does it match the brief?** Compare the live result against every section of the design brief. Fix discrepancies. +2. **Does it pass the AI slop test?** If someone saw this and said "AI made this," would they believe it immediately? If yes, it needs more design intention. +3. **Run /validate.** Fix any P0 or P1 issues. +4. **Check every state.** Navigate through empty, error, loading, and edge case states. Each one should feel intentional, not like an afterthought. +5. **Check responsive.** Resize the viewport. Does it adapt well or just shrink? +6. **Check the details.** Spacing consistency, type hierarchy clarity, color contrast, interactive feedback, motion timing. + +After each round of fixes, visually verify again. **Repeat until you would be proud to show this to the user.** The bar is not "it works"; the bar is "this delights." + +## Step 5: Present + +Present the result to the user: +- Show the feature in its primary state +- Walk through the key states (empty, error, responsive) +- Explain design decisions that connect back to the design brief +- Ask: "What's working? What isn't?" + +Iterate based on feedback. Good design is rarely right on the first pass. diff --git a/.agents/skills/shape/SKILL.md b/.agents/skills/shape/SKILL.md new file mode 100644 index 000000000..330b9b02e --- /dev/null +++ b/.agents/skills/shape/SKILL.md @@ -0,0 +1,95 @@ +--- +name: shape +description: Plan the UX and UI for a feature before writing code. Runs a structured discovery interview, then produces a design brief that guides implementation. Use during the planning phase to establish design direction, constraints, and strategy before any code is written. +user-invocable: true +argument-hint: "[feature to shape]" +--- + +## MANDATORY PREPARATION + +Invoke /impeccable, which contains design principles, anti-patterns, and the **Context Gathering Protocol**. Follow the protocol before proceeding. If no design context exists yet, you MUST run /impeccable teach first. + +--- + +Shape the UX and UI for a feature before any code is written. This skill produces a **design brief**: a structured artifact that guides implementation through discovery, not guesswork. + +**Scope**: Design planning only. This skill does NOT write code. It produces the thinking that makes code good. + +**Output**: A design brief that can be handed off to /impeccable craft, /impeccable, or any other implementation skill. + +## Philosophy + +Most AI-generated UIs fail not because of bad code, but because of skipped thinking. They jump to "here's a card grid" without asking "what is the user trying to accomplish?" This skill inverts that: understand deeply first, so implementation is precise. + +## Phase 1: Discovery Interview + +**Do NOT write any code or make any design decisions during this phase.** Your only job is to understand the feature deeply enough to make excellent design decisions later. + +Ask these questions in conversation, adapting based on answers. Don't dump them all at once; have a natural dialogue. ask the user directly to clarify what you cannot infer. + +### Purpose & Context +- What is this feature for? What problem does it solve? +- Who specifically will use it? (Not "users"; be specific: role, context, frequency) +- What does success look like? How will you know this feature is working? +- What's the user's state of mind when they reach this feature? (Rushed? Exploring? Anxious? Focused?) + +### Content & Data +- What content or data does this feature display or collect? +- What are the realistic ranges? (Minimum, typical, maximum, e.g., 0 items, 5 items, 500 items) +- What are the edge cases? (Empty state, error state, first-time use, power user) +- Is any content dynamic? What changes and how often? + +### Design Goals +- What's the single most important thing a user should do or understand here? +- What should this feel like? (Fast/efficient? Calm/trustworthy? Fun/playful? Premium/refined?) +- Are there existing patterns in the product this should be consistent with? +- Are there specific examples (inside or outside the product) that capture what you're going for? + +### Constraints +- Are there technical constraints? (Framework, performance budget, browser support) +- Are there content constraints? (Localization, dynamic text length, user-generated content) +- Mobile/responsive requirements? +- Accessibility requirements beyond WCAG AA? + +### Anti-Goals +- What should this NOT be? What would be a wrong direction? +- What's the biggest risk of getting this wrong? + +## Phase 2: Design Brief + +After the interview, synthesize everything into a structured design brief. Present it to the user for confirmation before considering this skill complete. + +### Brief Structure + +**1. Feature Summary** (2-3 sentences) +What this is, who it's for, what it needs to accomplish. + +**2. Primary User Action** +The single most important thing a user should do or understand here. + +**3. Design Direction** +How this should feel. What aesthetic approach fits. Reference the project's design context from `.impeccable.md` and explain how this feature should express it. + +**4. Layout Strategy** +High-level spatial approach: what gets emphasis, what's secondary, how information flows. Describe the visual hierarchy and rhythm, not specific CSS. + +**5. Key States** +List every state the feature needs: default, empty, loading, error, success, edge cases. For each, note what the user needs to see and feel. + +**6. Interaction Model** +How users interact with this feature. What happens on click, hover, scroll? What feedback do they get? What's the flow from entry to completion? + +**7. Content Requirements** +What copy, labels, empty state messages, error messages, and microcopy are needed. Note any dynamic content and its realistic ranges. + +**8. Recommended References** +Based on the brief, list which impeccable reference files would be most valuable during implementation (e.g., spatial-design.md for complex layouts, motion-design.md for animated features, interaction-design.md for form-heavy features). + +**9. Open Questions** +Anything unresolved that the implementer should resolve during build. + +--- + +ask the user directly to clarify what you cannot infer. Get explicit confirmation of the brief before finishing. If the user disagrees with any part, revisit the relevant discovery questions. + +Once confirmed, the brief is complete. The user can now hand it to /impeccable craft to build the feature, or use it to guide any other implementation approach. \ No newline at end of file diff --git a/.agents/skills/validate/SKILL.md b/.agents/skills/validate/SKILL.md index a100bdf1f..62e4ac05d 100644 --- a/.agents/skills/validate/SKILL.md +++ b/.agents/skills/validate/SKILL.md @@ -7,11 +7,11 @@ argument-hint: "[area to validate]" ## MANDATORY PREPARATION -Invoke /impeccable -- it contains design principles, anti-patterns, and the **Context Gathering Protocol**. Follow the protocol before proceeding -- if no design context exists yet, you MUST run /impeccable teach first. +Invoke /impeccable, which contains design principles, anti-patterns, and the **Context Gathering Protocol**. Follow the protocol before proceeding. If no design context exists yet, you MUST run /impeccable teach first. --- -A fast, focused quality gate. Not a full audit or critique -- this is the 2-minute check you run after every UI change to catch the most common and damaging issues before they ship. +A fast, focused quality gate. Not a full audit or critique; this is the 2-minute check you run after every UI change to catch the most common and damaging issues before they ship. Think of this as a design linter: opinionated, fast, and actionable. Flag what's wrong, say how to fix it, move on. @@ -71,10 +71,10 @@ Check against ALL **DON'T** guidelines in the impeccable skill. The most common Report findings as a flat list, grouped by severity: **Severity levels:** -- **P0 -- Broken**: Visually broken, inaccessible, or fundamentally wrong. Fix before shipping. -- **P1 -- Anti-pattern**: Clear design anti-pattern that undermines quality. Fix now. -- **P2 -- Inconsistency**: Spacing, token, or style drift from the design system. Fix soon. -- **P3 -- Polish**: Minor refinement opportunity. Fix if time allows. +- **P0 (Broken)**: Visually broken, inaccessible, or fundamentally wrong. Fix before shipping. +- **P1 (Anti-pattern)**: Clear design anti-pattern that undermines quality. Fix now. +- **P2 (Inconsistency)**: Spacing, token, or style drift from the design system. Fix soon. +- **P3 (Polish)**: Minor refinement opportunity. Fix if time allows. For each finding: ``` @@ -82,7 +82,7 @@ For each finding: → Fix: Concrete action to take (file:line if applicable) ``` -Keep the total list short. If everything looks good, say so -- don't invent issues. +Keep the total list short. If everything looks good, say so. Don't invent issues. ## After Validation diff --git a/.claude/skills/audit/SKILL.md b/.claude/skills/audit/SKILL.md index dcabe5eea..fa777e5c0 100644 --- a/.claude/skills/audit/SKILL.md +++ b/.claude/skills/audit/SKILL.md @@ -108,7 +108,7 @@ For each issue, document: - **Impact**: How it affects users - **WCAG/Standard**: Which standard it violates (if applicable) - **Recommendation**: How to fix it -- **Suggested command**: Which command to use (prefer: /animate, /validate, /quieter, /craft, /optimize, /adapt, /clarify, /distill, /delight, /onboard, /normalize, /audit, /harden, /polish, /extract, /bolder, /arrange, /typeset, /critique, /colorize, /overdrive) +- **Suggested command**: Which command to use (prefer: /animate, /validate, /quieter, /shape, /optimize, /adapt, /clarify, /distill, /delight, /onboard, /normalize, /audit, /harden, /polish, /extract, /bolder, /arrange, /typeset, /critique, /colorize, /overdrive) ### Patterns & Systemic Issues @@ -127,7 +127,7 @@ List recommended commands in priority order (P0 first, then P1, then P2): 1. **[P?] `/command-name`** — Brief description (specific context from audit findings) 2. **[P?] `/command-name`** — Brief description (specific context) -**Rules**: Only recommend commands from: /animate, /validate, /quieter, /craft, /optimize, /adapt, /clarify, /distill, /delight, /onboard, /normalize, /audit, /harden, /polish, /extract, /bolder, /arrange, /typeset, /critique, /colorize, /overdrive. Map findings to the most appropriate command. End with `/polish` as the final step if any fixes were recommended. +**Rules**: Only recommend commands from: /animate, /validate, /quieter, /shape, /optimize, /adapt, /clarify, /distill, /delight, /onboard, /normalize, /audit, /harden, /polish, /extract, /bolder, /arrange, /typeset, /critique, /colorize, /overdrive. Map findings to the most appropriate command. End with `/polish` as the final step if any fixes were recommended. After presenting the summary, tell the user: diff --git a/.claude/skills/craft/SKILL.md b/.claude/skills/craft/SKILL.md deleted file mode 100644 index 48b711eb7..000000000 --- a/.claude/skills/craft/SKILL.md +++ /dev/null @@ -1,97 +0,0 @@ ---- -name: craft -description: Design and build ideal UX+UI for a feature through guided discovery. Interviews the user about purpose, audience, and design goals before implementing. Use when building a new feature, redesigning an existing one, or when the user wants a thoughtful, user-centered design process rather than jumping straight to code. -user-invocable: true -argument-hint: "[feature to design]" ---- - -## MANDATORY PREPARATION - -Invoke /impeccable -- it contains design principles, anti-patterns, and the **Context Gathering Protocol**. Follow the protocol before proceeding -- if no design context exists yet, you MUST run /impeccable teach first. - ---- - -Build the ideal UX and UI for a feature. This skill is about getting the design RIGHT before writing code -- through structured discovery, not guesswork. - -**Scope**: UX + UI design and implementation. Out of scope: building the underlying business logic, backend, or data layer. If the feature needs backend work, note what's needed but focus on the interface. - -## Philosophy - -Most AI-generated UIs fail not because of bad code, but because of skipped thinking. They jump to "here's a card grid" without asking "what is the user trying to accomplish?" This skill inverts that: understand deeply, then build precisely. - -## Phase 1: Discovery Interview - -**Do NOT write any code during this phase.** Your only job is to understand the feature deeply enough to make excellent design decisions. - -Ask these questions in conversation, adapting based on answers. Don't dump them all at once -- have a natural dialogue. STOP and call the AskUserQuestion tool to clarify. - -### Purpose & Context -- What is this feature for? What problem does it solve? -- Who specifically will use it? (Not "users" -- be specific: role, context, frequency) -- What does success look like? How will you know this feature is working? -- What's the user's state of mind when they reach this feature? (Rushed? Exploring? Anxious? Focused?) - -### Content & Data -- What content or data does this feature display or collect? -- What are the realistic ranges? (Minimum, typical, maximum -- e.g., 0 items, 5 items, 500 items) -- What are the edge cases? (Empty state, error state, first-time use, power user) -- Is any content dynamic? What changes and how often? - -### Design Goals -- What's the single most important thing a user should do or understand here? -- What should this feel like? (Fast/efficient? Calm/trustworthy? Fun/playful? Premium/refined?) -- Are there existing patterns in the product this should be consistent with? -- Are there specific examples (inside or outside the product) that capture what you're going for? - -### Constraints -- Are there technical constraints? (Framework, performance budget, browser support) -- Are there content constraints? (Localization, dynamic text length, user-generated content) -- Mobile/responsive requirements? -- Accessibility requirements beyond WCAG AA? - -### Anti-Goals -- What should this NOT be? What would be a wrong direction? -- What's the biggest risk of getting this wrong? - -## Phase 2: Design Synthesis - -After the interview, synthesize your understanding before touching code. Present this back to the user for confirmation: - -1. **Feature brief** (2-3 sentences): What this is, who it's for, what it needs to accomplish -2. **Primary user action**: The one thing that matters most -3. **Design direction**: How this should feel, what aesthetic approach fits -4. **Key states**: List every state the feature needs (default, empty, loading, error, success, edge cases) -5. **Open questions**: Anything unresolved that might change the approach - -STOP and call the AskUserQuestion tool to clarify. -- get explicit confirmation before proceeding. If the user disagrees with your synthesis, revisit the relevant discovery questions. - -## Phase 3: Implementation - -Now build it. Use /impeccable as your design engine -- follow its principles, consult its references, avoid its anti-patterns. - -### Implementation Order -1. **Structure first**: HTML/semantic structure for the primary state. No styling yet. -2. **Layout and spacing**: Establish the spatial rhythm and visual hierarchy. -3. **Typography and color**: Apply the type scale and color system. -4. **Interactive states**: Hover, focus, active, disabled. -5. **Edge case states**: Empty, loading, error, overflow, first-run. -6. **Motion**: Purposeful transitions and animations (if appropriate). -7. **Responsive**: Adapt for different viewports -- don't just shrink, redesign for the context. - -### During Implementation -- Test with real (or realistic) data at every step, not placeholder text -- Check each state as you build it, not all at the end -- If you discover a design question during implementation, stop and ask rather than guessing -- Every visual choice should trace back to something learned in discovery - -## Phase 4: Validation - -After implementation, run /validate on your work. Fix any P0 or P1 issues before presenting to the user. - -Then present the result: -- Show the feature in its primary state -- Walk through the key states (empty, error, responsive) -- Explain design decisions that connect back to what you learned in discovery -- Ask for feedback: "What's working? What isn't?" - -Iterate based on feedback. Good design is rarely right on the first pass. \ No newline at end of file diff --git a/.claude/skills/critique/SKILL.md b/.claude/skills/critique/SKILL.md index fd799e93c..6accc0d59 100644 --- a/.claude/skills/critique/SKILL.md +++ b/.claude/skills/critique/SKILL.md @@ -11,21 +11,21 @@ allowed-tools: ### Step 1: Preparation -Invoke /impeccable -- it contains design principles, anti-patterns, and the **Context Gathering Protocol**. Follow the protocol before proceeding -- if no design context exists yet, you MUST run /impeccable teach first. Additionally gather: what the interface is trying to accomplish. +Invoke /impeccable, which contains design principles, anti-patterns, and the **Context Gathering Protocol**. Follow the protocol before proceeding. If no design context exists yet, you MUST run /impeccable teach first. Additionally gather: what the interface is trying to accomplish. ### Step 2: Gather Assessments Launch two independent assessments. **Neither must see the other's output** to avoid bias. -You SHOULD delegate each assessment to a separate sub-agent for independence. Use your environment's agent spawning mechanism -- e.g., Claude Code's `Agent` tool, or Codex's subagent spawning ("spawn two agents in parallel"). Sub-agents should return their findings as structured text -- do NOT output findings to the user yet. +You SHOULD delegate each assessment to a separate sub-agent for independence. Use your environment's agent spawning mechanism (e.g., Claude Code's `Agent` tool, or Codex's subagent spawning). Sub-agents should return their findings as structured text. Do NOT output findings to the user yet. If sub-agents are not available in the current environment, complete each assessment sequentially, writing findings to internal notes before proceeding. -**Tab isolation**: When browser automation is available, each assessment MUST create its own new tab -- never reuse an existing tab, even if one is already open at the correct URL. This prevents the two assessments from interfering with each other's page state. +**Tab isolation**: When browser automation is available, each assessment MUST create its own new tab. Never reuse an existing tab, even if one is already open at the correct URL. This prevents the two assessments from interfering with each other's page state. #### Assessment A: LLM Design Review -Read the relevant source files (HTML, CSS, JS/TS) and, if browser automation is available, visually inspect the live page. **Create a new tab** for this -- do not reuse existing tabs. After navigation, label the tab by setting the document title: +Read the relevant source files (HTML, CSS, JS/TS) and, if browser automation is available, visually inspect the live page. **Create a new tab** for this; do not reuse existing tabs. After navigation, label the tab by setting the document title: ```javascript document.title = '[LLM] ' + document.title; ``` @@ -36,8 +36,8 @@ Think like a design director. Evaluate: **Holistic Design Review**: 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). **Cognitive Load** (consult [cognitive-load](reference/cognitive-load.md)): -- Run the 8-item cognitive load checklist. Report failure count: 0--1 = low (good), 2--3 = moderate, 4+ = critical. -- Count visible options at each decision point -- if >4, flag it. +- Run the 8-item cognitive load checklist. Report failure count: 0-1 = low (good), 2-3 = moderate, 4+ = critical. +- Count visible options at each decision point. If >4, flag it. - Check for progressive disclosure: is complexity revealed only when needed? **Emotional Journey**: @@ -46,9 +46,9 @@ Think like a design director. Evaluate: - **Emotional valleys**: Check for anxiety spikes at high-stakes moments (payment, delete, commit). Are there design interventions (progress indicators, reassurance copy, undo options)? **Nielsen's Heuristics** (consult [heuristics-scoring](reference/heuristics-scoring.md)): -Score each of the 10 heuristics 0--4. This scoring will be presented in the report. +Score each of the 10 heuristics 0-4. This scoring will be presented in the report. -Return structured findings covering: AI slop verdict, heuristic scores, cognitive load assessment, what's working (2--3 items), priority issues (3--5 with what/why/fix), minor observations, and provocative questions. +Return structured findings covering: AI slop verdict, heuristic scores, cognitive load assessment, what's working (2-3 items), priority issues (3-5 with what/why/fix), minor observations, and provocative questions. #### Assessment B: Automated Detection @@ -67,37 +67,37 @@ npx impeccable --json [--fast] [target] **Browser visualization** (when browser automation tools are available AND the target is a viewable page): -The overlay is a **visual aid for the user** -- it highlights issues directly in their browser. Do NOT scroll through the page to screenshot overlays. Instead, read the console output to get the results programmatically. +The overlay is a **visual aid for the user**. It highlights issues directly in their browser. Do NOT scroll through the page to screenshot overlays. Instead, read the console output to get the results programmatically. 1. **Start the live detection server**: ```bash npx impeccable live & ``` Note the port printed to stdout (auto-assigned). Use `--port=PORT` to fix it. -2. **Create a new tab** and navigate to the page (use dev server URL for local files, or direct URL) -- do not reuse existing tabs +2. **Create a new tab** and navigate to the page (use dev server URL for local files, or direct URL). Do not reuse existing tabs. 3. **Label the tab** via `javascript_tool` so the user can distinguish it: ```javascript document.title = '[Human] ' + document.title; ``` -4. **Scroll to top** -- ensure the page is scrolled to the very top before injection +4. **Scroll to top** to ensure the page is scrolled to the very top before injection 5. **Inject** via `javascript_tool` (replace PORT with the port from step 1): ```javascript const s = document.createElement('script'); s.src = 'http://localhost:PORT/detect.js'; document.head.appendChild(s); ``` -6. Wait 2--3 seconds for the detector to render overlays -7. **Read results from console** using `read_console_messages` with pattern `impeccable` -- the detector logs all findings with the `[impeccable]` prefix. Do NOT scroll through the page to take screenshots of the overlays. +6. Wait 2-3 seconds for the detector to render overlays +7. **Read results from console** using `read_console_messages` with pattern `impeccable`. The detector logs all findings with the `[impeccable]` prefix. Do NOT scroll through the page to take screenshots of the overlays. 8. **Cleanup**: Stop the live server when done: ```bash npx impeccable live stop ``` -For multi-view targets, inject on 3--5 representative pages. If injection fails, continue with CLI results only. +For multi-view targets, inject on 3-5 representative pages. If injection fails, continue with CLI results only. Return: CLI findings (JSON), browser console findings (if applicable), and any false positives noted. ### Step 3: Generate Combined Critique Report -Synthesize both assessments into a single report. Do NOT simply concatenate -- weave the findings together, noting where the LLM review and detector agree, where the detector caught issues the LLM missed, and where detector findings are false positives. +Synthesize both assessments into a single report. Do NOT simply concatenate. Weave the findings together, noting where the LLM review and detector agree, where the detector caught issues the LLM missed, and where detector findings are false positives. Structure your feedback as a design director would: @@ -108,7 +108,7 @@ Present the Nielsen's 10 heuristics scores as a table: | # | Heuristic | Score | Key Issue | |---|-----------|-------|-----------| -| 1 | Visibility of System Status | ? | [specific finding or "--" if solid] | +| 1 | Visibility of System Status | ? | [specific finding or "n/a" if solid] | | 2 | Match System / Real World | ? | | | 3 | User Control and Freedom | ? | | | 4 | Consistency and Standards | ? | | @@ -120,7 +120,7 @@ Present the Nielsen's 10 heuristics scores as a table: | 10 | Help and Documentation | ? | | | **Total** | | **??/40** | **[Rating band]** | -Be honest with scores. A 4 means genuinely excellent. Most real interfaces score 20--32. +Be honest with scores. A 4 means genuinely excellent. Most real interfaces score 20-32. #### Anti-Patterns Verdict @@ -133,24 +133,24 @@ Be honest with scores. A 4 means genuinely excellent. Most real interfaces score **Visual overlays** (if browser was used): Tell the user that overlays are now visible in the **[Human]** tab in their browser, highlighting the detected issues. Summarize what the console output reported. #### Overall Impression -A brief gut reaction -- what works, what doesn't, and the single biggest opportunity. +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. +Highlight 2-3 things done well. Be specific about why they work. #### Priority Issues -The 3--5 most impactful design problems, ordered by importance. +The 3-5 most impactful design problems, ordered by importance. -For each issue, tag with **P0--P3 severity** (consult [heuristics-scoring](reference/heuristics-scoring.md) for severity definitions): +For each issue, tag with **P0-P3 severity** (consult [heuristics-scoring](reference/heuristics-scoring.md) for severity definitions): - **[P?] What**: Name the problem clearly - **Why it matters**: How this hurts users or undermines goals - **Fix**: What to do about it (be concrete) -- **Suggested command**: Which command could address this (from: /animate, /validate, /quieter, /craft, /optimize, /adapt, /clarify, /distill, /delight, /onboard, /normalize, /audit, /harden, /polish, /extract, /bolder, /arrange, /typeset, /critique, /colorize, /overdrive) +- **Suggested command**: Which command could address this (from: /animate, /validate, /quieter, /shape, /optimize, /adapt, /clarify, /distill, /delight, /onboard, /normalize, /audit, /harden, /polish, /extract, /bolder, /arrange, /typeset, /critique, /colorize, /overdrive) #### Persona Red Flags > *Consult [personas](reference/personas.md)* -Auto-select 2--3 personas most relevant to this interface type (use the selection table in the reference). If `CLAUDE.md` contains a `## Design Context` section from `impeccable teach`, also generate 1--2 project-specific personas from the audience/brand info. +Auto-select 2-3 personas most relevant to this interface type (use the selection table in the reference). If `CLAUDE.md` contains a `## Design Context` section from `impeccable teach`, also generate 1-2 project-specific personas from the audience/brand info. For each selected persona, walk through the primary user action and list specific red flags found: @@ -158,7 +158,7 @@ For each selected persona, walk through the primary user action and list specifi **Jordan (First-Timer)**: Icon-only nav in sidebar. Technical jargon in error messages ("404 Not Found"). No visible help. Will abandon at step 2. -Be specific -- name the exact elements and interactions that fail each persona. Don't write generic persona descriptions; write what broke for them. +Be specific. Name the exact elements and interactions that fail each persona. Don't write generic persona descriptions; write what broke for them. #### Minor Observations Quick notes on smaller issues worth addressing. @@ -170,32 +170,32 @@ Provocative questions that might unlock better solutions: - "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 +- 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 +- Prioritize ruthlessly. If everything is important, nothing is. +- Don't soften criticism. Developers need honest feedback to ship great design. ### Step 4: Ask the User **After presenting findings**, use targeted questions based on what was actually found. STOP and call the AskUserQuestion tool to clarify. These answers will shape the action plan. -Ask questions along these lines (adapt to the specific findings -- do NOT ask generic questions): +Ask questions along these lines (adapt to the specific findings; do NOT ask generic questions): -1. **Priority direction**: Based on the issues found, ask which category matters most to the user right now. For example: "I found problems with visual hierarchy, color usage, and information overload. Which area should we tackle first?" Offer the top 2--3 issue categories as options. +1. **Priority direction**: Based on the issues found, ask which category matters most to the user right now. For example: "I found problems with visual hierarchy, color usage, and information overload. Which area should we tackle first?" Offer the top 2-3 issue categories as options. -2. **Design intent**: If the critique found a tonal mismatch, ask whether it was intentional. For example: "The interface feels clinical and corporate. Is that the intended tone, or should it feel warmer/bolder/more playful?" Offer 2--3 tonal directions as options based on what would fix the issues found. +2. **Design intent**: If the critique found a tonal mismatch, ask whether it was intentional. For example: "The interface feels clinical and corporate. Is that the intended tone, or should it feel warmer/bolder/more playful?" Offer 2-3 tonal directions as options based on what would fix the issues found. 3. **Scope**: Ask how much the user wants to take on. For example: "I found N issues. Want to address everything, or focus on the top 3?" Offer scope options like "Top 3 only", "All issues", "Critical issues only". -4. **Constraints** (optional -- only ask if relevant): If the findings touch many areas, ask if anything is off-limits. For example: "Should any sections stay as-is?" This prevents the plan from touching things the user considers done. +4. **Constraints** (optional; only ask if relevant): If the findings touch many areas, ask if anything is off-limits. For example: "Should any sections stay as-is?" This prevents the plan from touching things the user considers done. **Rules for questions**: -- Every question must reference specific findings from the report -- never ask generic "who is your audience?" questions -- Keep it to 2--4 questions maximum -- respect the user's time -- Offer concrete options, not open-ended prompts -- If findings are straightforward (e.g., only 1--2 clear issues), skip questions and go directly to Step 5 +- Every question must reference specific findings from the report. Never ask generic "who is your audience?" questions. +- Keep it to 2-4 questions maximum. Respect the user's time. +- Offer concrete options, not open-ended prompts. +- If findings are straightforward (e.g., only 1-2 clear issues), skip questions and go directly to Step 5. ### Step 5: Recommended Actions @@ -205,12 +205,12 @@ Ask questions along these lines (adapt to the specific findings -- do NOT ask ge List recommended commands in priority order, based on the user's answers: -1. **`/command-name`** -- Brief description of what to fix (specific context from critique findings) -2. **`/command-name`** -- Brief description (specific context) +1. **`/command-name`**: Brief description of what to fix (specific context from critique findings) +2. **`/command-name`**: Brief description (specific context) ... **Rules for recommendations**: -- Only recommend commands from: /animate, /validate, /quieter, /craft, /optimize, /adapt, /clarify, /distill, /delight, /onboard, /normalize, /audit, /harden, /polish, /extract, /bolder, /arrange, /typeset, /critique, /colorize, /overdrive +- Only recommend commands from: /animate, /validate, /quieter, /shape, /optimize, /adapt, /clarify, /distill, /delight, /onboard, /normalize, /audit, /harden, /polish, /extract, /bolder, /arrange, /typeset, /critique, /colorize, /overdrive - Order by the user's stated priorities first, then by impact - Each item's description should carry enough context that the command knows what to focus on - Map each Priority Issue to the appropriate command diff --git a/.claude/skills/impeccable/SKILL.md b/.claude/skills/impeccable/SKILL.md index ca34f75ab..50c6075f4 100644 --- a/.claude/skills/impeccable/SKILL.md +++ b/.claude/skills/impeccable/SKILL.md @@ -1,8 +1,8 @@ --- name: impeccable -description: Create distinctive, production-grade frontend interfaces with high design quality. Generates creative, polished code that avoids generic AI aesthetics. Use when the user asks to build web components, pages, artifacts, posters, or applications, or when any design skill requires project context. Call with 'teach' argument to run design context setup. +description: Create distinctive, production-grade frontend interfaces with high design quality. Generates creative, polished code that avoids generic AI aesthetics. Use when the user asks to build web components, pages, artifacts, posters, or applications, or when any design skill requires project context. Call with 'craft' to run the full shape-then-build flow, or 'teach' for design context setup. user-invocable: true -argument-hint: "[teach]" +argument-hint: "[craft|teach]" license: Apache 2.0. Based on Anthropic's frontend-design skill. See NOTICE.md for attribution. --- @@ -150,6 +150,12 @@ Remember: Claude is capable of extraordinary creative work. Don't hold back. Sho --- +## Craft Mode + +If this skill is invoked with the argument "craft" (e.g., `/impeccable craft [feature description]`), follow the [craft flow](reference/craft.md). Pass any additional arguments as the feature description. + +--- + ## Teach Mode If this skill is invoked with the argument "teach" (e.g., `/impeccable teach`), skip all design work above and instead run the teach flow below. This is a one-time setup that gathers design context for the project. diff --git a/.claude/skills/impeccable/reference/craft.md b/.claude/skills/impeccable/reference/craft.md new file mode 100644 index 000000000..d2961057f --- /dev/null +++ b/.claude/skills/impeccable/reference/craft.md @@ -0,0 +1,70 @@ +# Craft Flow + +Build a feature with impeccable UX and UI quality through a structured process: shape the design, load the right references, then build and iterate visually until the result is delightful. + +## Step 1: Shape the Design + +Run /shape, passing along whatever feature description the user provided. + +Wait for the design brief to be fully confirmed before proceeding. The brief is your blueprint, and every implementation decision should trace back to it. + +If the user has already run /shape and has a confirmed design brief, skip this step and use the existing brief. + +## Step 2: Load References + +Based on the design brief's "Recommended References" section, consult the relevant impeccable reference files. At minimum, always consult: + +- [spatial-design.md](spatial-design.md) for layout and spacing +- [typography.md](typography.md) for type hierarchy + +Then add references based on the brief's needs: +- Complex interactions or forms? Consult [interaction-design.md](interaction-design.md) +- Animation or transitions? Consult [motion-design.md](motion-design.md) +- Color-heavy or themed? Consult [color-and-contrast.md](color-and-contrast.md) +- Responsive requirements? Consult [responsive-design.md](responsive-design.md) +- Heavy on copy, labels, or errors? Consult [ux-writing.md](ux-writing.md) + +## Step 3: Build + +Implement the feature following the design brief. Work in this order: + +1. **Structure first**: HTML/semantic structure for the primary state. No styling yet. +2. **Layout and spacing**: Establish the spatial rhythm and visual hierarchy. +3. **Typography and color**: Apply the type scale and color system. +4. **Interactive states**: Hover, focus, active, disabled. +5. **Edge case states**: Empty, loading, error, overflow, first-run. +6. **Motion**: Purposeful transitions and animations (if appropriate). +7. **Responsive**: Adapt for different viewports. Don't just shrink; redesign for the context. + +### During Build +- Test with real (or realistic) data at every step, not placeholder text +- Check each state as you build it, not all at the end +- If you discover a design question, stop and ask rather than guessing +- Every visual choice should trace back to something in the design brief + +## Step 4: Visual Iteration + +**This step is critical.** Do not stop after the first implementation pass. + +Open the result in a browser window. If browser automation tools are available, use them to navigate to the page and visually inspect the result. If not, ask the user to open it and provide feedback. + +Iterate through these checks visually: + +1. **Does it match the brief?** Compare the live result against every section of the design brief. Fix discrepancies. +2. **Does it pass the AI slop test?** If someone saw this and said "AI made this," would they believe it immediately? If yes, it needs more design intention. +3. **Run /validate.** Fix any P0 or P1 issues. +4. **Check every state.** Navigate through empty, error, loading, and edge case states. Each one should feel intentional, not like an afterthought. +5. **Check responsive.** Resize the viewport. Does it adapt well or just shrink? +6. **Check the details.** Spacing consistency, type hierarchy clarity, color contrast, interactive feedback, motion timing. + +After each round of fixes, visually verify again. **Repeat until you would be proud to show this to the user.** The bar is not "it works"; the bar is "this delights." + +## Step 5: Present + +Present the result to the user: +- Show the feature in its primary state +- Walk through the key states (empty, error, responsive) +- Explain design decisions that connect back to the design brief +- Ask: "What's working? What isn't?" + +Iterate based on feedback. Good design is rarely right on the first pass. diff --git a/.claude/skills/shape/SKILL.md b/.claude/skills/shape/SKILL.md new file mode 100644 index 000000000..21af45c2d --- /dev/null +++ b/.claude/skills/shape/SKILL.md @@ -0,0 +1,95 @@ +--- +name: shape +description: Plan the UX and UI for a feature before writing code. Runs a structured discovery interview, then produces a design brief that guides implementation. Use during the planning phase to establish design direction, constraints, and strategy before any code is written. +user-invocable: true +argument-hint: "[feature to shape]" +--- + +## MANDATORY PREPARATION + +Invoke /impeccable, which contains design principles, anti-patterns, and the **Context Gathering Protocol**. Follow the protocol before proceeding. If no design context exists yet, you MUST run /impeccable teach first. + +--- + +Shape the UX and UI for a feature before any code is written. This skill produces a **design brief**: a structured artifact that guides implementation through discovery, not guesswork. + +**Scope**: Design planning only. This skill does NOT write code. It produces the thinking that makes code good. + +**Output**: A design brief that can be handed off to /impeccable craft, /impeccable, or any other implementation skill. + +## Philosophy + +Most AI-generated UIs fail not because of bad code, but because of skipped thinking. They jump to "here's a card grid" without asking "what is the user trying to accomplish?" This skill inverts that: understand deeply first, so implementation is precise. + +## Phase 1: Discovery Interview + +**Do NOT write any code or make any design decisions during this phase.** Your only job is to understand the feature deeply enough to make excellent design decisions later. + +Ask these questions in conversation, adapting based on answers. Don't dump them all at once; have a natural dialogue. STOP and call the AskUserQuestion tool to clarify. + +### Purpose & Context +- What is this feature for? What problem does it solve? +- Who specifically will use it? (Not "users"; be specific: role, context, frequency) +- What does success look like? How will you know this feature is working? +- What's the user's state of mind when they reach this feature? (Rushed? Exploring? Anxious? Focused?) + +### Content & Data +- What content or data does this feature display or collect? +- What are the realistic ranges? (Minimum, typical, maximum, e.g., 0 items, 5 items, 500 items) +- What are the edge cases? (Empty state, error state, first-time use, power user) +- Is any content dynamic? What changes and how often? + +### Design Goals +- What's the single most important thing a user should do or understand here? +- What should this feel like? (Fast/efficient? Calm/trustworthy? Fun/playful? Premium/refined?) +- Are there existing patterns in the product this should be consistent with? +- Are there specific examples (inside or outside the product) that capture what you're going for? + +### Constraints +- Are there technical constraints? (Framework, performance budget, browser support) +- Are there content constraints? (Localization, dynamic text length, user-generated content) +- Mobile/responsive requirements? +- Accessibility requirements beyond WCAG AA? + +### Anti-Goals +- What should this NOT be? What would be a wrong direction? +- What's the biggest risk of getting this wrong? + +## Phase 2: Design Brief + +After the interview, synthesize everything into a structured design brief. Present it to the user for confirmation before considering this skill complete. + +### Brief Structure + +**1. Feature Summary** (2-3 sentences) +What this is, who it's for, what it needs to accomplish. + +**2. Primary User Action** +The single most important thing a user should do or understand here. + +**3. Design Direction** +How this should feel. What aesthetic approach fits. Reference the project's design context from `.impeccable.md` and explain how this feature should express it. + +**4. Layout Strategy** +High-level spatial approach: what gets emphasis, what's secondary, how information flows. Describe the visual hierarchy and rhythm, not specific CSS. + +**5. Key States** +List every state the feature needs: default, empty, loading, error, success, edge cases. For each, note what the user needs to see and feel. + +**6. Interaction Model** +How users interact with this feature. What happens on click, hover, scroll? What feedback do they get? What's the flow from entry to completion? + +**7. Content Requirements** +What copy, labels, empty state messages, error messages, and microcopy are needed. Note any dynamic content and its realistic ranges. + +**8. Recommended References** +Based on the brief, list which impeccable reference files would be most valuable during implementation (e.g., spatial-design.md for complex layouts, motion-design.md for animated features, interaction-design.md for form-heavy features). + +**9. Open Questions** +Anything unresolved that the implementer should resolve during build. + +--- + +STOP and call the AskUserQuestion tool to clarify. Get explicit confirmation of the brief before finishing. If the user disagrees with any part, revisit the relevant discovery questions. + +Once confirmed, the brief is complete. The user can now hand it to /impeccable craft to build the feature, or use it to guide any other implementation approach. \ No newline at end of file diff --git a/.claude/skills/validate/SKILL.md b/.claude/skills/validate/SKILL.md index fe0bf8912..127461ec0 100644 --- a/.claude/skills/validate/SKILL.md +++ b/.claude/skills/validate/SKILL.md @@ -7,11 +7,11 @@ argument-hint: "[area to validate]" ## MANDATORY PREPARATION -Invoke /impeccable -- it contains design principles, anti-patterns, and the **Context Gathering Protocol**. Follow the protocol before proceeding -- if no design context exists yet, you MUST run /impeccable teach first. +Invoke /impeccable, which contains design principles, anti-patterns, and the **Context Gathering Protocol**. Follow the protocol before proceeding. If no design context exists yet, you MUST run /impeccable teach first. --- -A fast, focused quality gate. Not a full audit or critique -- this is the 2-minute check you run after every UI change to catch the most common and damaging issues before they ship. +A fast, focused quality gate. Not a full audit or critique; this is the 2-minute check you run after every UI change to catch the most common and damaging issues before they ship. Think of this as a design linter: opinionated, fast, and actionable. Flag what's wrong, say how to fix it, move on. @@ -71,10 +71,10 @@ Check against ALL **DON'T** guidelines in the impeccable skill. The most common Report findings as a flat list, grouped by severity: **Severity levels:** -- **P0 -- Broken**: Visually broken, inaccessible, or fundamentally wrong. Fix before shipping. -- **P1 -- Anti-pattern**: Clear design anti-pattern that undermines quality. Fix now. -- **P2 -- Inconsistency**: Spacing, token, or style drift from the design system. Fix soon. -- **P3 -- Polish**: Minor refinement opportunity. Fix if time allows. +- **P0 (Broken)**: Visually broken, inaccessible, or fundamentally wrong. Fix before shipping. +- **P1 (Anti-pattern)**: Clear design anti-pattern that undermines quality. Fix now. +- **P2 (Inconsistency)**: Spacing, token, or style drift from the design system. Fix soon. +- **P3 (Polish)**: Minor refinement opportunity. Fix if time allows. For each finding: ``` @@ -82,7 +82,7 @@ For each finding: → Fix: Concrete action to take (file:line if applicable) ``` -Keep the total list short. If everything looks good, say so -- don't invent issues. +Keep the total list short. If everything looks good, say so. Don't invent issues. ## After Validation diff --git a/.codex/skills/audit/SKILL.md b/.codex/skills/audit/SKILL.md index c28a8a294..fd7a485bd 100644 --- a/.codex/skills/audit/SKILL.md +++ b/.codex/skills/audit/SKILL.md @@ -107,7 +107,7 @@ For each issue, document: - **Impact**: How it affects users - **WCAG/Standard**: Which standard it violates (if applicable) - **Recommendation**: How to fix it -- **Suggested command**: Which command to use (prefer: $animate, $validate, $quieter, $craft, $optimize, $adapt, $clarify, $distill, $delight, $onboard, $normalize, $audit, $harden, $polish, $extract, $bolder, $arrange, $typeset, $critique, $colorize, $overdrive) +- **Suggested command**: Which command to use (prefer: $animate, $validate, $quieter, $shape, $optimize, $adapt, $clarify, $distill, $delight, $onboard, $normalize, $audit, $harden, $polish, $extract, $bolder, $arrange, $typeset, $critique, $colorize, $overdrive) ### Patterns & Systemic Issues @@ -126,7 +126,7 @@ List recommended commands in priority order (P0 first, then P1, then P2): 1. **[P?] `$command-name`** — Brief description (specific context from audit findings) 2. **[P?] `$command-name`** — Brief description (specific context) -**Rules**: Only recommend commands from: $animate, $validate, $quieter, $craft, $optimize, $adapt, $clarify, $distill, $delight, $onboard, $normalize, $audit, $harden, $polish, $extract, $bolder, $arrange, $typeset, $critique, $colorize, $overdrive. Map findings to the most appropriate command. End with `$polish` as the final step if any fixes were recommended. +**Rules**: Only recommend commands from: $animate, $validate, $quieter, $shape, $optimize, $adapt, $clarify, $distill, $delight, $onboard, $normalize, $audit, $harden, $polish, $extract, $bolder, $arrange, $typeset, $critique, $colorize, $overdrive. Map findings to the most appropriate command. End with `$polish` as the final step if any fixes were recommended. After presenting the summary, tell the user: diff --git a/.codex/skills/craft/SKILL.md b/.codex/skills/craft/SKILL.md deleted file mode 100644 index d97d32145..000000000 --- a/.codex/skills/craft/SKILL.md +++ /dev/null @@ -1,96 +0,0 @@ ---- -name: craft -description: Design and build ideal UX+UI for a feature through guided discovery. Interviews the user about purpose, audience, and design goals before implementing. Use when building a new feature, redesigning an existing one, or when the user wants a thoughtful, user-centered design process rather than jumping straight to code. -argument-hint: "[feature to design]" ---- - -## MANDATORY PREPARATION - -Invoke $impeccable -- it contains design principles, anti-patterns, and the **Context Gathering Protocol**. Follow the protocol before proceeding -- if no design context exists yet, you MUST run $impeccable teach first. - ---- - -Build the ideal UX and UI for a feature. This skill is about getting the design RIGHT before writing code -- through structured discovery, not guesswork. - -**Scope**: UX + UI design and implementation. Out of scope: building the underlying business logic, backend, or data layer. If the feature needs backend work, note what's needed but focus on the interface. - -## Philosophy - -Most AI-generated UIs fail not because of bad code, but because of skipped thinking. They jump to "here's a card grid" without asking "what is the user trying to accomplish?" This skill inverts that: understand deeply, then build precisely. - -## Phase 1: Discovery Interview - -**Do NOT write any code during this phase.** Your only job is to understand the feature deeply enough to make excellent design decisions. - -Ask these questions in conversation, adapting based on answers. Don't dump them all at once -- have a natural dialogue. ask the user directly to clarify what you cannot infer. - -### Purpose & Context -- What is this feature for? What problem does it solve? -- Who specifically will use it? (Not "users" -- be specific: role, context, frequency) -- What does success look like? How will you know this feature is working? -- What's the user's state of mind when they reach this feature? (Rushed? Exploring? Anxious? Focused?) - -### Content & Data -- What content or data does this feature display or collect? -- What are the realistic ranges? (Minimum, typical, maximum -- e.g., 0 items, 5 items, 500 items) -- What are the edge cases? (Empty state, error state, first-time use, power user) -- Is any content dynamic? What changes and how often? - -### Design Goals -- What's the single most important thing a user should do or understand here? -- What should this feel like? (Fast/efficient? Calm/trustworthy? Fun/playful? Premium/refined?) -- Are there existing patterns in the product this should be consistent with? -- Are there specific examples (inside or outside the product) that capture what you're going for? - -### Constraints -- Are there technical constraints? (Framework, performance budget, browser support) -- Are there content constraints? (Localization, dynamic text length, user-generated content) -- Mobile/responsive requirements? -- Accessibility requirements beyond WCAG AA? - -### Anti-Goals -- What should this NOT be? What would be a wrong direction? -- What's the biggest risk of getting this wrong? - -## Phase 2: Design Synthesis - -After the interview, synthesize your understanding before touching code. Present this back to the user for confirmation: - -1. **Feature brief** (2-3 sentences): What this is, who it's for, what it needs to accomplish -2. **Primary user action**: The one thing that matters most -3. **Design direction**: How this should feel, what aesthetic approach fits -4. **Key states**: List every state the feature needs (default, empty, loading, error, success, edge cases) -5. **Open questions**: Anything unresolved that might change the approach - -ask the user directly to clarify what you cannot infer. -- get explicit confirmation before proceeding. If the user disagrees with your synthesis, revisit the relevant discovery questions. - -## Phase 3: Implementation - -Now build it. Use $impeccable as your design engine -- follow its principles, consult its references, avoid its anti-patterns. - -### Implementation Order -1. **Structure first**: HTML/semantic structure for the primary state. No styling yet. -2. **Layout and spacing**: Establish the spatial rhythm and visual hierarchy. -3. **Typography and color**: Apply the type scale and color system. -4. **Interactive states**: Hover, focus, active, disabled. -5. **Edge case states**: Empty, loading, error, overflow, first-run. -6. **Motion**: Purposeful transitions and animations (if appropriate). -7. **Responsive**: Adapt for different viewports -- don't just shrink, redesign for the context. - -### During Implementation -- Test with real (or realistic) data at every step, not placeholder text -- Check each state as you build it, not all at the end -- If you discover a design question during implementation, stop and ask rather than guessing -- Every visual choice should trace back to something learned in discovery - -## Phase 4: Validation - -After implementation, run $validate on your work. Fix any P0 or P1 issues before presenting to the user. - -Then present the result: -- Show the feature in its primary state -- Walk through the key states (empty, error, responsive) -- Explain design decisions that connect back to what you learned in discovery -- Ask for feedback: "What's working? What isn't?" - -Iterate based on feedback. Good design is rarely right on the first pass. \ No newline at end of file diff --git a/.codex/skills/critique/SKILL.md b/.codex/skills/critique/SKILL.md index d606d196b..3902edd38 100644 --- a/.codex/skills/critique/SKILL.md +++ b/.codex/skills/critique/SKILL.md @@ -8,21 +8,21 @@ argument-hint: "[area (feature, page, component...)]" ### Step 1: Preparation -Invoke $impeccable -- it contains design principles, anti-patterns, and the **Context Gathering Protocol**. Follow the protocol before proceeding -- if no design context exists yet, you MUST run $impeccable teach first. Additionally gather: what the interface is trying to accomplish. +Invoke $impeccable, which contains design principles, anti-patterns, and the **Context Gathering Protocol**. Follow the protocol before proceeding. If no design context exists yet, you MUST run $impeccable teach first. Additionally gather: what the interface is trying to accomplish. ### Step 2: Gather Assessments Launch two independent assessments. **Neither must see the other's output** to avoid bias. -You SHOULD delegate each assessment to a separate sub-agent for independence. Use your environment's agent spawning mechanism -- e.g., Claude Code's `Agent` tool, or Codex's subagent spawning ("spawn two agents in parallel"). Sub-agents should return their findings as structured text -- do NOT output findings to the user yet. +You SHOULD delegate each assessment to a separate sub-agent for independence. Use your environment's agent spawning mechanism (e.g., Claude Code's `Agent` tool, or Codex's subagent spawning). Sub-agents should return their findings as structured text. Do NOT output findings to the user yet. If sub-agents are not available in the current environment, complete each assessment sequentially, writing findings to internal notes before proceeding. -**Tab isolation**: When browser automation is available, each assessment MUST create its own new tab -- never reuse an existing tab, even if one is already open at the correct URL. This prevents the two assessments from interfering with each other's page state. +**Tab isolation**: When browser automation is available, each assessment MUST create its own new tab. Never reuse an existing tab, even if one is already open at the correct URL. This prevents the two assessments from interfering with each other's page state. #### Assessment A: LLM Design Review -Read the relevant source files (HTML, CSS, JS/TS) and, if browser automation is available, visually inspect the live page. **Create a new tab** for this -- do not reuse existing tabs. After navigation, label the tab by setting the document title: +Read the relevant source files (HTML, CSS, JS/TS) and, if browser automation is available, visually inspect the live page. **Create a new tab** for this; do not reuse existing tabs. After navigation, label the tab by setting the document title: ```javascript document.title = '[LLM] ' + document.title; ``` @@ -33,8 +33,8 @@ Think like a design director. Evaluate: **Holistic Design Review**: 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). **Cognitive Load** (consult [cognitive-load](reference/cognitive-load.md)): -- Run the 8-item cognitive load checklist. Report failure count: 0--1 = low (good), 2--3 = moderate, 4+ = critical. -- Count visible options at each decision point -- if >4, flag it. +- Run the 8-item cognitive load checklist. Report failure count: 0-1 = low (good), 2-3 = moderate, 4+ = critical. +- Count visible options at each decision point. If >4, flag it. - Check for progressive disclosure: is complexity revealed only when needed? **Emotional Journey**: @@ -43,9 +43,9 @@ Think like a design director. Evaluate: - **Emotional valleys**: Check for anxiety spikes at high-stakes moments (payment, delete, commit). Are there design interventions (progress indicators, reassurance copy, undo options)? **Nielsen's Heuristics** (consult [heuristics-scoring](reference/heuristics-scoring.md)): -Score each of the 10 heuristics 0--4. This scoring will be presented in the report. +Score each of the 10 heuristics 0-4. This scoring will be presented in the report. -Return structured findings covering: AI slop verdict, heuristic scores, cognitive load assessment, what's working (2--3 items), priority issues (3--5 with what/why/fix), minor observations, and provocative questions. +Return structured findings covering: AI slop verdict, heuristic scores, cognitive load assessment, what's working (2-3 items), priority issues (3-5 with what/why/fix), minor observations, and provocative questions. #### Assessment B: Automated Detection @@ -64,37 +64,37 @@ npx impeccable --json [--fast] [target] **Browser visualization** (when browser automation tools are available AND the target is a viewable page): -The overlay is a **visual aid for the user** -- it highlights issues directly in their browser. Do NOT scroll through the page to screenshot overlays. Instead, read the console output to get the results programmatically. +The overlay is a **visual aid for the user**. It highlights issues directly in their browser. Do NOT scroll through the page to screenshot overlays. Instead, read the console output to get the results programmatically. 1. **Start the live detection server**: ```bash npx impeccable live & ``` Note the port printed to stdout (auto-assigned). Use `--port=PORT` to fix it. -2. **Create a new tab** and navigate to the page (use dev server URL for local files, or direct URL) -- do not reuse existing tabs +2. **Create a new tab** and navigate to the page (use dev server URL for local files, or direct URL). Do not reuse existing tabs. 3. **Label the tab** via `javascript_tool` so the user can distinguish it: ```javascript document.title = '[Human] ' + document.title; ``` -4. **Scroll to top** -- ensure the page is scrolled to the very top before injection +4. **Scroll to top** to ensure the page is scrolled to the very top before injection 5. **Inject** via `javascript_tool` (replace PORT with the port from step 1): ```javascript const s = document.createElement('script'); s.src = 'http://localhost:PORT/detect.js'; document.head.appendChild(s); ``` -6. Wait 2--3 seconds for the detector to render overlays -7. **Read results from console** using `read_console_messages` with pattern `impeccable` -- the detector logs all findings with the `[impeccable]` prefix. Do NOT scroll through the page to take screenshots of the overlays. +6. Wait 2-3 seconds for the detector to render overlays +7. **Read results from console** using `read_console_messages` with pattern `impeccable`. The detector logs all findings with the `[impeccable]` prefix. Do NOT scroll through the page to take screenshots of the overlays. 8. **Cleanup**: Stop the live server when done: ```bash npx impeccable live stop ``` -For multi-view targets, inject on 3--5 representative pages. If injection fails, continue with CLI results only. +For multi-view targets, inject on 3-5 representative pages. If injection fails, continue with CLI results only. Return: CLI findings (JSON), browser console findings (if applicable), and any false positives noted. ### Step 3: Generate Combined Critique Report -Synthesize both assessments into a single report. Do NOT simply concatenate -- weave the findings together, noting where the LLM review and detector agree, where the detector caught issues the LLM missed, and where detector findings are false positives. +Synthesize both assessments into a single report. Do NOT simply concatenate. Weave the findings together, noting where the LLM review and detector agree, where the detector caught issues the LLM missed, and where detector findings are false positives. Structure your feedback as a design director would: @@ -105,7 +105,7 @@ Present the Nielsen's 10 heuristics scores as a table: | # | Heuristic | Score | Key Issue | |---|-----------|-------|-----------| -| 1 | Visibility of System Status | ? | [specific finding or "--" if solid] | +| 1 | Visibility of System Status | ? | [specific finding or "n/a" if solid] | | 2 | Match System / Real World | ? | | | 3 | User Control and Freedom | ? | | | 4 | Consistency and Standards | ? | | @@ -117,7 +117,7 @@ Present the Nielsen's 10 heuristics scores as a table: | 10 | Help and Documentation | ? | | | **Total** | | **??/40** | **[Rating band]** | -Be honest with scores. A 4 means genuinely excellent. Most real interfaces score 20--32. +Be honest with scores. A 4 means genuinely excellent. Most real interfaces score 20-32. #### Anti-Patterns Verdict @@ -130,24 +130,24 @@ Be honest with scores. A 4 means genuinely excellent. Most real interfaces score **Visual overlays** (if browser was used): Tell the user that overlays are now visible in the **[Human]** tab in their browser, highlighting the detected issues. Summarize what the console output reported. #### Overall Impression -A brief gut reaction -- what works, what doesn't, and the single biggest opportunity. +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. +Highlight 2-3 things done well. Be specific about why they work. #### Priority Issues -The 3--5 most impactful design problems, ordered by importance. +The 3-5 most impactful design problems, ordered by importance. -For each issue, tag with **P0--P3 severity** (consult [heuristics-scoring](reference/heuristics-scoring.md) for severity definitions): +For each issue, tag with **P0-P3 severity** (consult [heuristics-scoring](reference/heuristics-scoring.md) for severity definitions): - **[P?] What**: Name the problem clearly - **Why it matters**: How this hurts users or undermines goals - **Fix**: What to do about it (be concrete) -- **Suggested command**: Which command could address this (from: $animate, $validate, $quieter, $craft, $optimize, $adapt, $clarify, $distill, $delight, $onboard, $normalize, $audit, $harden, $polish, $extract, $bolder, $arrange, $typeset, $critique, $colorize, $overdrive) +- **Suggested command**: Which command could address this (from: $animate, $validate, $quieter, $shape, $optimize, $adapt, $clarify, $distill, $delight, $onboard, $normalize, $audit, $harden, $polish, $extract, $bolder, $arrange, $typeset, $critique, $colorize, $overdrive) #### Persona Red Flags > *Consult [personas](reference/personas.md)* -Auto-select 2--3 personas most relevant to this interface type (use the selection table in the reference). If `AGENTS.md` contains a `## Design Context` section from `impeccable teach`, also generate 1--2 project-specific personas from the audience/brand info. +Auto-select 2-3 personas most relevant to this interface type (use the selection table in the reference). If `AGENTS.md` contains a `## Design Context` section from `impeccable teach`, also generate 1-2 project-specific personas from the audience/brand info. For each selected persona, walk through the primary user action and list specific red flags found: @@ -155,7 +155,7 @@ For each selected persona, walk through the primary user action and list specifi **Jordan (First-Timer)**: Icon-only nav in sidebar. Technical jargon in error messages ("404 Not Found"). No visible help. Will abandon at step 2. -Be specific -- name the exact elements and interactions that fail each persona. Don't write generic persona descriptions; write what broke for them. +Be specific. Name the exact elements and interactions that fail each persona. Don't write generic persona descriptions; write what broke for them. #### Minor Observations Quick notes on smaller issues worth addressing. @@ -167,32 +167,32 @@ Provocative questions that might unlock better solutions: - "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 +- 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 +- Prioritize ruthlessly. If everything is important, nothing is. +- Don't soften criticism. Developers need honest feedback to ship great design. ### Step 4: Ask the User **After presenting findings**, use targeted questions based on what was actually found. ask the user directly to clarify what you cannot infer. These answers will shape the action plan. -Ask questions along these lines (adapt to the specific findings -- do NOT ask generic questions): +Ask questions along these lines (adapt to the specific findings; do NOT ask generic questions): -1. **Priority direction**: Based on the issues found, ask which category matters most to the user right now. For example: "I found problems with visual hierarchy, color usage, and information overload. Which area should we tackle first?" Offer the top 2--3 issue categories as options. +1. **Priority direction**: Based on the issues found, ask which category matters most to the user right now. For example: "I found problems with visual hierarchy, color usage, and information overload. Which area should we tackle first?" Offer the top 2-3 issue categories as options. -2. **Design intent**: If the critique found a tonal mismatch, ask whether it was intentional. For example: "The interface feels clinical and corporate. Is that the intended tone, or should it feel warmer$bolder/more playful?" Offer 2--3 tonal directions as options based on what would fix the issues found. +2. **Design intent**: If the critique found a tonal mismatch, ask whether it was intentional. For example: "The interface feels clinical and corporate. Is that the intended tone, or should it feel warmer$bolder/more playful?" Offer 2-3 tonal directions as options based on what would fix the issues found. 3. **Scope**: Ask how much the user wants to take on. For example: "I found N issues. Want to address everything, or focus on the top 3?" Offer scope options like "Top 3 only", "All issues", "Critical issues only". -4. **Constraints** (optional -- only ask if relevant): If the findings touch many areas, ask if anything is off-limits. For example: "Should any sections stay as-is?" This prevents the plan from touching things the user considers done. +4. **Constraints** (optional; only ask if relevant): If the findings touch many areas, ask if anything is off-limits. For example: "Should any sections stay as-is?" This prevents the plan from touching things the user considers done. **Rules for questions**: -- Every question must reference specific findings from the report -- never ask generic "who is your audience?" questions -- Keep it to 2--4 questions maximum -- respect the user's time -- Offer concrete options, not open-ended prompts -- If findings are straightforward (e.g., only 1--2 clear issues), skip questions and go directly to Step 5 +- Every question must reference specific findings from the report. Never ask generic "who is your audience?" questions. +- Keep it to 2-4 questions maximum. Respect the user's time. +- Offer concrete options, not open-ended prompts. +- If findings are straightforward (e.g., only 1-2 clear issues), skip questions and go directly to Step 5. ### Step 5: Recommended Actions @@ -202,12 +202,12 @@ Ask questions along these lines (adapt to the specific findings -- do NOT ask ge List recommended commands in priority order, based on the user's answers: -1. **`$command-name`** -- Brief description of what to fix (specific context from critique findings) -2. **`$command-name`** -- Brief description (specific context) +1. **`$command-name`**: Brief description of what to fix (specific context from critique findings) +2. **`$command-name`**: Brief description (specific context) ... **Rules for recommendations**: -- Only recommend commands from: $animate, $validate, $quieter, $craft, $optimize, $adapt, $clarify, $distill, $delight, $onboard, $normalize, $audit, $harden, $polish, $extract, $bolder, $arrange, $typeset, $critique, $colorize, $overdrive +- Only recommend commands from: $animate, $validate, $quieter, $shape, $optimize, $adapt, $clarify, $distill, $delight, $onboard, $normalize, $audit, $harden, $polish, $extract, $bolder, $arrange, $typeset, $critique, $colorize, $overdrive - Order by the user's stated priorities first, then by impact - Each item's description should carry enough context that the command knows what to focus on - Map each Priority Issue to the appropriate command diff --git a/.codex/skills/impeccable/SKILL.md b/.codex/skills/impeccable/SKILL.md index fb4b00c4e..d387490db 100644 --- a/.codex/skills/impeccable/SKILL.md +++ b/.codex/skills/impeccable/SKILL.md @@ -1,7 +1,7 @@ --- name: impeccable -description: Create distinctive, production-grade frontend interfaces with high design quality. Generates creative, polished code that avoids generic AI aesthetics. Use when the user asks to build web components, pages, artifacts, posters, or applications, or when any design skill requires project context. Call with 'teach' argument to run design context setup. -argument-hint: "[teach]" +description: Create distinctive, production-grade frontend interfaces with high design quality. Generates creative, polished code that avoids generic AI aesthetics. Use when the user asks to build web components, pages, artifacts, posters, or applications, or when any design skill requires project context. Call with 'craft' to run the full shape-then-build flow, or 'teach' for design context setup. +argument-hint: "[craft|teach]" license: Apache 2.0. Based on Anthropic's frontend-design skill. See NOTICE.md for attribution. --- @@ -149,6 +149,12 @@ Remember: GPT is capable of extraordinary creative work. Don't hold back. Show w --- +## Craft Mode + +If this skill is invoked with the argument "craft" (e.g., `$impeccable craft [feature description]`), follow the [craft flow](reference/craft.md). Pass any additional arguments as the feature description. + +--- + ## Teach Mode If this skill is invoked with the argument "teach" (e.g., `$impeccable teach`), skip all design work above and instead run the teach flow below. This is a one-time setup that gathers design context for the project. diff --git a/.codex/skills/impeccable/reference/craft.md b/.codex/skills/impeccable/reference/craft.md new file mode 100644 index 000000000..67614a755 --- /dev/null +++ b/.codex/skills/impeccable/reference/craft.md @@ -0,0 +1,70 @@ +# Craft Flow + +Build a feature with impeccable UX and UI quality through a structured process: shape the design, load the right references, then build and iterate visually until the result is delightful. + +## Step 1: Shape the Design + +Run $shape, passing along whatever feature description the user provided. + +Wait for the design brief to be fully confirmed before proceeding. The brief is your blueprint, and every implementation decision should trace back to it. + +If the user has already run $shape and has a confirmed design brief, skip this step and use the existing brief. + +## Step 2: Load References + +Based on the design brief's "Recommended References" section, consult the relevant impeccable reference files. At minimum, always consult: + +- [spatial-design.md](spatial-design.md) for layout and spacing +- [typography.md](typography.md) for type hierarchy + +Then add references based on the brief's needs: +- Complex interactions or forms? Consult [interaction-design.md](interaction-design.md) +- Animation or transitions? Consult [motion-design.md](motion-design.md) +- Color-heavy or themed? Consult [color-and-contrast.md](color-and-contrast.md) +- Responsive requirements? Consult [responsive-design.md](responsive-design.md) +- Heavy on copy, labels, or errors? Consult [ux-writing.md](ux-writing.md) + +## Step 3: Build + +Implement the feature following the design brief. Work in this order: + +1. **Structure first**: HTML/semantic structure for the primary state. No styling yet. +2. **Layout and spacing**: Establish the spatial rhythm and visual hierarchy. +3. **Typography and color**: Apply the type scale and color system. +4. **Interactive states**: Hover, focus, active, disabled. +5. **Edge case states**: Empty, loading, error, overflow, first-run. +6. **Motion**: Purposeful transitions and animations (if appropriate). +7. **Responsive**: Adapt for different viewports. Don't just shrink; redesign for the context. + +### During Build +- Test with real (or realistic) data at every step, not placeholder text +- Check each state as you build it, not all at the end +- If you discover a design question, stop and ask rather than guessing +- Every visual choice should trace back to something in the design brief + +## Step 4: Visual Iteration + +**This step is critical.** Do not stop after the first implementation pass. + +Open the result in a browser window. If browser automation tools are available, use them to navigate to the page and visually inspect the result. If not, ask the user to open it and provide feedback. + +Iterate through these checks visually: + +1. **Does it match the brief?** Compare the live result against every section of the design brief. Fix discrepancies. +2. **Does it pass the AI slop test?** If someone saw this and said "AI made this," would they believe it immediately? If yes, it needs more design intention. +3. **Run $validate.** Fix any P0 or P1 issues. +4. **Check every state.** Navigate through empty, error, loading, and edge case states. Each one should feel intentional, not like an afterthought. +5. **Check responsive.** Resize the viewport. Does it adapt well or just shrink? +6. **Check the details.** Spacing consistency, type hierarchy clarity, color contrast, interactive feedback, motion timing. + +After each round of fixes, visually verify again. **Repeat until you would be proud to show this to the user.** The bar is not "it works"; the bar is "this delights." + +## Step 5: Present + +Present the result to the user: +- Show the feature in its primary state +- Walk through the key states (empty, error, responsive) +- Explain design decisions that connect back to the design brief +- Ask: "What's working? What isn't?" + +Iterate based on feedback. Good design is rarely right on the first pass. diff --git a/.codex/skills/shape/SKILL.md b/.codex/skills/shape/SKILL.md new file mode 100644 index 000000000..035f3e7fa --- /dev/null +++ b/.codex/skills/shape/SKILL.md @@ -0,0 +1,94 @@ +--- +name: shape +description: Plan the UX and UI for a feature before writing code. Runs a structured discovery interview, then produces a design brief that guides implementation. Use during the planning phase to establish design direction, constraints, and strategy before any code is written. +argument-hint: "[feature to shape]" +--- + +## MANDATORY PREPARATION + +Invoke $impeccable, which contains design principles, anti-patterns, and the **Context Gathering Protocol**. Follow the protocol before proceeding. If no design context exists yet, you MUST run $impeccable teach first. + +--- + +Shape the UX and UI for a feature before any code is written. This skill produces a **design brief**: a structured artifact that guides implementation through discovery, not guesswork. + +**Scope**: Design planning only. This skill does NOT write code. It produces the thinking that makes code good. + +**Output**: A design brief that can be handed off to $impeccable craft, $impeccable, or any other implementation skill. + +## Philosophy + +Most AI-generated UIs fail not because of bad code, but because of skipped thinking. They jump to "here's a card grid" without asking "what is the user trying to accomplish?" This skill inverts that: understand deeply first, so implementation is precise. + +## Phase 1: Discovery Interview + +**Do NOT write any code or make any design decisions during this phase.** Your only job is to understand the feature deeply enough to make excellent design decisions later. + +Ask these questions in conversation, adapting based on answers. Don't dump them all at once; have a natural dialogue. ask the user directly to clarify what you cannot infer. + +### Purpose & Context +- What is this feature for? What problem does it solve? +- Who specifically will use it? (Not "users"; be specific: role, context, frequency) +- What does success look like? How will you know this feature is working? +- What's the user's state of mind when they reach this feature? (Rushed? Exploring? Anxious? Focused?) + +### Content & Data +- What content or data does this feature display or collect? +- What are the realistic ranges? (Minimum, typical, maximum, e.g., 0 items, 5 items, 500 items) +- What are the edge cases? (Empty state, error state, first-time use, power user) +- Is any content dynamic? What changes and how often? + +### Design Goals +- What's the single most important thing a user should do or understand here? +- What should this feel like? (Fast/efficient? Calm/trustworthy? Fun/playful? Premium/refined?) +- Are there existing patterns in the product this should be consistent with? +- Are there specific examples (inside or outside the product) that capture what you're going for? + +### Constraints +- Are there technical constraints? (Framework, performance budget, browser support) +- Are there content constraints? (Localization, dynamic text length, user-generated content) +- Mobile/responsive requirements? +- Accessibility requirements beyond WCAG AA? + +### Anti-Goals +- What should this NOT be? What would be a wrong direction? +- What's the biggest risk of getting this wrong? + +## Phase 2: Design Brief + +After the interview, synthesize everything into a structured design brief. Present it to the user for confirmation before considering this skill complete. + +### Brief Structure + +**1. Feature Summary** (2-3 sentences) +What this is, who it's for, what it needs to accomplish. + +**2. Primary User Action** +The single most important thing a user should do or understand here. + +**3. Design Direction** +How this should feel. What aesthetic approach fits. Reference the project's design context from `.impeccable.md` and explain how this feature should express it. + +**4. Layout Strategy** +High-level spatial approach: what gets emphasis, what's secondary, how information flows. Describe the visual hierarchy and rhythm, not specific CSS. + +**5. Key States** +List every state the feature needs: default, empty, loading, error, success, edge cases. For each, note what the user needs to see and feel. + +**6. Interaction Model** +How users interact with this feature. What happens on click, hover, scroll? What feedback do they get? What's the flow from entry to completion? + +**7. Content Requirements** +What copy, labels, empty state messages, error messages, and microcopy are needed. Note any dynamic content and its realistic ranges. + +**8. Recommended References** +Based on the brief, list which impeccable reference files would be most valuable during implementation (e.g., spatial-design.md for complex layouts, motion-design.md for animated features, interaction-design.md for form-heavy features). + +**9. Open Questions** +Anything unresolved that the implementer should resolve during build. + +--- + +ask the user directly to clarify what you cannot infer. Get explicit confirmation of the brief before finishing. If the user disagrees with any part, revisit the relevant discovery questions. + +Once confirmed, the brief is complete. The user can now hand it to $impeccable craft to build the feature, or use it to guide any other implementation approach. \ No newline at end of file diff --git a/.codex/skills/validate/SKILL.md b/.codex/skills/validate/SKILL.md index 88332dc24..be2568d5b 100644 --- a/.codex/skills/validate/SKILL.md +++ b/.codex/skills/validate/SKILL.md @@ -6,11 +6,11 @@ argument-hint: "[area to validate]" ## MANDATORY PREPARATION -Invoke $impeccable -- it contains design principles, anti-patterns, and the **Context Gathering Protocol**. Follow the protocol before proceeding -- if no design context exists yet, you MUST run $impeccable teach first. +Invoke $impeccable, which contains design principles, anti-patterns, and the **Context Gathering Protocol**. Follow the protocol before proceeding. If no design context exists yet, you MUST run $impeccable teach first. --- -A fast, focused quality gate. Not a full audit or critique -- this is the 2-minute check you run after every UI change to catch the most common and damaging issues before they ship. +A fast, focused quality gate. Not a full audit or critique; this is the 2-minute check you run after every UI change to catch the most common and damaging issues before they ship. Think of this as a design linter: opinionated, fast, and actionable. Flag what's wrong, say how to fix it, move on. @@ -70,10 +70,10 @@ Check against ALL **DON'T** guidelines in the impeccable skill. The most common Report findings as a flat list, grouped by severity: **Severity levels:** -- **P0 -- Broken**: Visually broken, inaccessible, or fundamentally wrong. Fix before shipping. -- **P1 -- Anti-pattern**: Clear design anti-pattern that undermines quality. Fix now. -- **P2 -- Inconsistency**: Spacing, token, or style drift from the design system. Fix soon. -- **P3 -- Polish**: Minor refinement opportunity. Fix if time allows. +- **P0 (Broken)**: Visually broken, inaccessible, or fundamentally wrong. Fix before shipping. +- **P1 (Anti-pattern)**: Clear design anti-pattern that undermines quality. Fix now. +- **P2 (Inconsistency)**: Spacing, token, or style drift from the design system. Fix soon. +- **P3 (Polish)**: Minor refinement opportunity. Fix if time allows. For each finding: ``` @@ -81,7 +81,7 @@ For each finding: → Fix: Concrete action to take (file:line if applicable) ``` -Keep the total list short. If everything looks good, say so -- don't invent issues. +Keep the total list short. If everything looks good, say so. Don't invent issues. ## After Validation diff --git a/.cursor/skills/audit/SKILL.md b/.cursor/skills/audit/SKILL.md index b482d344e..f944d6111 100644 --- a/.cursor/skills/audit/SKILL.md +++ b/.cursor/skills/audit/SKILL.md @@ -106,7 +106,7 @@ For each issue, document: - **Impact**: How it affects users - **WCAG/Standard**: Which standard it violates (if applicable) - **Recommendation**: How to fix it -- **Suggested command**: Which command to use (prefer: /animate, /validate, /quieter, /craft, /optimize, /adapt, /clarify, /distill, /delight, /onboard, /normalize, /audit, /harden, /polish, /extract, /bolder, /arrange, /typeset, /critique, /colorize, /overdrive) +- **Suggested command**: Which command to use (prefer: /animate, /validate, /quieter, /shape, /optimize, /adapt, /clarify, /distill, /delight, /onboard, /normalize, /audit, /harden, /polish, /extract, /bolder, /arrange, /typeset, /critique, /colorize, /overdrive) ### Patterns & Systemic Issues @@ -125,7 +125,7 @@ List recommended commands in priority order (P0 first, then P1, then P2): 1. **[P?] `/command-name`** — Brief description (specific context from audit findings) 2. **[P?] `/command-name`** — Brief description (specific context) -**Rules**: Only recommend commands from: /animate, /validate, /quieter, /craft, /optimize, /adapt, /clarify, /distill, /delight, /onboard, /normalize, /audit, /harden, /polish, /extract, /bolder, /arrange, /typeset, /critique, /colorize, /overdrive. Map findings to the most appropriate command. End with `/polish` as the final step if any fixes were recommended. +**Rules**: Only recommend commands from: /animate, /validate, /quieter, /shape, /optimize, /adapt, /clarify, /distill, /delight, /onboard, /normalize, /audit, /harden, /polish, /extract, /bolder, /arrange, /typeset, /critique, /colorize, /overdrive. Map findings to the most appropriate command. End with `/polish` as the final step if any fixes were recommended. After presenting the summary, tell the user: diff --git a/.cursor/skills/craft/SKILL.md b/.cursor/skills/craft/SKILL.md deleted file mode 100644 index 1dde45c9b..000000000 --- a/.cursor/skills/craft/SKILL.md +++ /dev/null @@ -1,95 +0,0 @@ ---- -name: craft -description: Design and build ideal UX+UI for a feature through guided discovery. Interviews the user about purpose, audience, and design goals before implementing. Use when building a new feature, redesigning an existing one, or when the user wants a thoughtful, user-centered design process rather than jumping straight to code. ---- - -## MANDATORY PREPARATION - -Invoke /impeccable -- it contains design principles, anti-patterns, and the **Context Gathering Protocol**. Follow the protocol before proceeding -- if no design context exists yet, you MUST run /impeccable teach first. - ---- - -Build the ideal UX and UI for a feature. This skill is about getting the design RIGHT before writing code -- through structured discovery, not guesswork. - -**Scope**: UX + UI design and implementation. Out of scope: building the underlying business logic, backend, or data layer. If the feature needs backend work, note what's needed but focus on the interface. - -## Philosophy - -Most AI-generated UIs fail not because of bad code, but because of skipped thinking. They jump to "here's a card grid" without asking "what is the user trying to accomplish?" This skill inverts that: understand deeply, then build precisely. - -## Phase 1: Discovery Interview - -**Do NOT write any code during this phase.** Your only job is to understand the feature deeply enough to make excellent design decisions. - -Ask these questions in conversation, adapting based on answers. Don't dump them all at once -- have a natural dialogue. ask the user directly to clarify what you cannot infer. - -### Purpose & Context -- What is this feature for? What problem does it solve? -- Who specifically will use it? (Not "users" -- be specific: role, context, frequency) -- What does success look like? How will you know this feature is working? -- What's the user's state of mind when they reach this feature? (Rushed? Exploring? Anxious? Focused?) - -### Content & Data -- What content or data does this feature display or collect? -- What are the realistic ranges? (Minimum, typical, maximum -- e.g., 0 items, 5 items, 500 items) -- What are the edge cases? (Empty state, error state, first-time use, power user) -- Is any content dynamic? What changes and how often? - -### Design Goals -- What's the single most important thing a user should do or understand here? -- What should this feel like? (Fast/efficient? Calm/trustworthy? Fun/playful? Premium/refined?) -- Are there existing patterns in the product this should be consistent with? -- Are there specific examples (inside or outside the product) that capture what you're going for? - -### Constraints -- Are there technical constraints? (Framework, performance budget, browser support) -- Are there content constraints? (Localization, dynamic text length, user-generated content) -- Mobile/responsive requirements? -- Accessibility requirements beyond WCAG AA? - -### Anti-Goals -- What should this NOT be? What would be a wrong direction? -- What's the biggest risk of getting this wrong? - -## Phase 2: Design Synthesis - -After the interview, synthesize your understanding before touching code. Present this back to the user for confirmation: - -1. **Feature brief** (2-3 sentences): What this is, who it's for, what it needs to accomplish -2. **Primary user action**: The one thing that matters most -3. **Design direction**: How this should feel, what aesthetic approach fits -4. **Key states**: List every state the feature needs (default, empty, loading, error, success, edge cases) -5. **Open questions**: Anything unresolved that might change the approach - -ask the user directly to clarify what you cannot infer. -- get explicit confirmation before proceeding. If the user disagrees with your synthesis, revisit the relevant discovery questions. - -## Phase 3: Implementation - -Now build it. Use /impeccable as your design engine -- follow its principles, consult its references, avoid its anti-patterns. - -### Implementation Order -1. **Structure first**: HTML/semantic structure for the primary state. No styling yet. -2. **Layout and spacing**: Establish the spatial rhythm and visual hierarchy. -3. **Typography and color**: Apply the type scale and color system. -4. **Interactive states**: Hover, focus, active, disabled. -5. **Edge case states**: Empty, loading, error, overflow, first-run. -6. **Motion**: Purposeful transitions and animations (if appropriate). -7. **Responsive**: Adapt for different viewports -- don't just shrink, redesign for the context. - -### During Implementation -- Test with real (or realistic) data at every step, not placeholder text -- Check each state as you build it, not all at the end -- If you discover a design question during implementation, stop and ask rather than guessing -- Every visual choice should trace back to something learned in discovery - -## Phase 4: Validation - -After implementation, run /validate on your work. Fix any P0 or P1 issues before presenting to the user. - -Then present the result: -- Show the feature in its primary state -- Walk through the key states (empty, error, responsive) -- Explain design decisions that connect back to what you learned in discovery -- Ask for feedback: "What's working? What isn't?" - -Iterate based on feedback. Good design is rarely right on the first pass. \ No newline at end of file diff --git a/.cursor/skills/critique/SKILL.md b/.cursor/skills/critique/SKILL.md index b2a355e5c..d9793b008 100644 --- a/.cursor/skills/critique/SKILL.md +++ b/.cursor/skills/critique/SKILL.md @@ -7,21 +7,21 @@ description: Evaluate design from a UX perspective, assessing visual hierarchy, ### Step 1: Preparation -Invoke /impeccable -- it contains design principles, anti-patterns, and the **Context Gathering Protocol**. Follow the protocol before proceeding -- if no design context exists yet, you MUST run /impeccable teach first. Additionally gather: what the interface is trying to accomplish. +Invoke /impeccable, which contains design principles, anti-patterns, and the **Context Gathering Protocol**. Follow the protocol before proceeding. If no design context exists yet, you MUST run /impeccable teach first. Additionally gather: what the interface is trying to accomplish. ### Step 2: Gather Assessments Launch two independent assessments. **Neither must see the other's output** to avoid bias. -You SHOULD delegate each assessment to a separate sub-agent for independence. Use your environment's agent spawning mechanism -- e.g., Claude Code's `Agent` tool, or Codex's subagent spawning ("spawn two agents in parallel"). Sub-agents should return their findings as structured text -- do NOT output findings to the user yet. +You SHOULD delegate each assessment to a separate sub-agent for independence. Use your environment's agent spawning mechanism (e.g., Claude Code's `Agent` tool, or Codex's subagent spawning). Sub-agents should return their findings as structured text. Do NOT output findings to the user yet. If sub-agents are not available in the current environment, complete each assessment sequentially, writing findings to internal notes before proceeding. -**Tab isolation**: When browser automation is available, each assessment MUST create its own new tab -- never reuse an existing tab, even if one is already open at the correct URL. This prevents the two assessments from interfering with each other's page state. +**Tab isolation**: When browser automation is available, each assessment MUST create its own new tab. Never reuse an existing tab, even if one is already open at the correct URL. This prevents the two assessments from interfering with each other's page state. #### Assessment A: LLM Design Review -Read the relevant source files (HTML, CSS, JS/TS) and, if browser automation is available, visually inspect the live page. **Create a new tab** for this -- do not reuse existing tabs. After navigation, label the tab by setting the document title: +Read the relevant source files (HTML, CSS, JS/TS) and, if browser automation is available, visually inspect the live page. **Create a new tab** for this; do not reuse existing tabs. After navigation, label the tab by setting the document title: ```javascript document.title = '[LLM] ' + document.title; ``` @@ -32,8 +32,8 @@ Think like a design director. Evaluate: **Holistic Design Review**: 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). **Cognitive Load** (consult [cognitive-load](reference/cognitive-load.md)): -- Run the 8-item cognitive load checklist. Report failure count: 0--1 = low (good), 2--3 = moderate, 4+ = critical. -- Count visible options at each decision point -- if >4, flag it. +- Run the 8-item cognitive load checklist. Report failure count: 0-1 = low (good), 2-3 = moderate, 4+ = critical. +- Count visible options at each decision point. If >4, flag it. - Check for progressive disclosure: is complexity revealed only when needed? **Emotional Journey**: @@ -42,9 +42,9 @@ Think like a design director. Evaluate: - **Emotional valleys**: Check for anxiety spikes at high-stakes moments (payment, delete, commit). Are there design interventions (progress indicators, reassurance copy, undo options)? **Nielsen's Heuristics** (consult [heuristics-scoring](reference/heuristics-scoring.md)): -Score each of the 10 heuristics 0--4. This scoring will be presented in the report. +Score each of the 10 heuristics 0-4. This scoring will be presented in the report. -Return structured findings covering: AI slop verdict, heuristic scores, cognitive load assessment, what's working (2--3 items), priority issues (3--5 with what/why/fix), minor observations, and provocative questions. +Return structured findings covering: AI slop verdict, heuristic scores, cognitive load assessment, what's working (2-3 items), priority issues (3-5 with what/why/fix), minor observations, and provocative questions. #### Assessment B: Automated Detection @@ -63,37 +63,37 @@ npx impeccable --json [--fast] [target] **Browser visualization** (when browser automation tools are available AND the target is a viewable page): -The overlay is a **visual aid for the user** -- it highlights issues directly in their browser. Do NOT scroll through the page to screenshot overlays. Instead, read the console output to get the results programmatically. +The overlay is a **visual aid for the user**. It highlights issues directly in their browser. Do NOT scroll through the page to screenshot overlays. Instead, read the console output to get the results programmatically. 1. **Start the live detection server**: ```bash npx impeccable live & ``` Note the port printed to stdout (auto-assigned). Use `--port=PORT` to fix it. -2. **Create a new tab** and navigate to the page (use dev server URL for local files, or direct URL) -- do not reuse existing tabs +2. **Create a new tab** and navigate to the page (use dev server URL for local files, or direct URL). Do not reuse existing tabs. 3. **Label the tab** via `javascript_tool` so the user can distinguish it: ```javascript document.title = '[Human] ' + document.title; ``` -4. **Scroll to top** -- ensure the page is scrolled to the very top before injection +4. **Scroll to top** to ensure the page is scrolled to the very top before injection 5. **Inject** via `javascript_tool` (replace PORT with the port from step 1): ```javascript const s = document.createElement('script'); s.src = 'http://localhost:PORT/detect.js'; document.head.appendChild(s); ``` -6. Wait 2--3 seconds for the detector to render overlays -7. **Read results from console** using `read_console_messages` with pattern `impeccable` -- the detector logs all findings with the `[impeccable]` prefix. Do NOT scroll through the page to take screenshots of the overlays. +6. Wait 2-3 seconds for the detector to render overlays +7. **Read results from console** using `read_console_messages` with pattern `impeccable`. The detector logs all findings with the `[impeccable]` prefix. Do NOT scroll through the page to take screenshots of the overlays. 8. **Cleanup**: Stop the live server when done: ```bash npx impeccable live stop ``` -For multi-view targets, inject on 3--5 representative pages. If injection fails, continue with CLI results only. +For multi-view targets, inject on 3-5 representative pages. If injection fails, continue with CLI results only. Return: CLI findings (JSON), browser console findings (if applicable), and any false positives noted. ### Step 3: Generate Combined Critique Report -Synthesize both assessments into a single report. Do NOT simply concatenate -- weave the findings together, noting where the LLM review and detector agree, where the detector caught issues the LLM missed, and where detector findings are false positives. +Synthesize both assessments into a single report. Do NOT simply concatenate. Weave the findings together, noting where the LLM review and detector agree, where the detector caught issues the LLM missed, and where detector findings are false positives. Structure your feedback as a design director would: @@ -104,7 +104,7 @@ Present the Nielsen's 10 heuristics scores as a table: | # | Heuristic | Score | Key Issue | |---|-----------|-------|-----------| -| 1 | Visibility of System Status | ? | [specific finding or "--" if solid] | +| 1 | Visibility of System Status | ? | [specific finding or "n/a" if solid] | | 2 | Match System / Real World | ? | | | 3 | User Control and Freedom | ? | | | 4 | Consistency and Standards | ? | | @@ -116,7 +116,7 @@ Present the Nielsen's 10 heuristics scores as a table: | 10 | Help and Documentation | ? | | | **Total** | | **??/40** | **[Rating band]** | -Be honest with scores. A 4 means genuinely excellent. Most real interfaces score 20--32. +Be honest with scores. A 4 means genuinely excellent. Most real interfaces score 20-32. #### Anti-Patterns Verdict @@ -129,24 +129,24 @@ Be honest with scores. A 4 means genuinely excellent. Most real interfaces score **Visual overlays** (if browser was used): Tell the user that overlays are now visible in the **[Human]** tab in their browser, highlighting the detected issues. Summarize what the console output reported. #### Overall Impression -A brief gut reaction -- what works, what doesn't, and the single biggest opportunity. +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. +Highlight 2-3 things done well. Be specific about why they work. #### Priority Issues -The 3--5 most impactful design problems, ordered by importance. +The 3-5 most impactful design problems, ordered by importance. -For each issue, tag with **P0--P3 severity** (consult [heuristics-scoring](reference/heuristics-scoring.md) for severity definitions): +For each issue, tag with **P0-P3 severity** (consult [heuristics-scoring](reference/heuristics-scoring.md) for severity definitions): - **[P?] What**: Name the problem clearly - **Why it matters**: How this hurts users or undermines goals - **Fix**: What to do about it (be concrete) -- **Suggested command**: Which command could address this (from: /animate, /validate, /quieter, /craft, /optimize, /adapt, /clarify, /distill, /delight, /onboard, /normalize, /audit, /harden, /polish, /extract, /bolder, /arrange, /typeset, /critique, /colorize, /overdrive) +- **Suggested command**: Which command could address this (from: /animate, /validate, /quieter, /shape, /optimize, /adapt, /clarify, /distill, /delight, /onboard, /normalize, /audit, /harden, /polish, /extract, /bolder, /arrange, /typeset, /critique, /colorize, /overdrive) #### Persona Red Flags > *Consult [personas](reference/personas.md)* -Auto-select 2--3 personas most relevant to this interface type (use the selection table in the reference). If `.cursorrules` contains a `## Design Context` section from `impeccable teach`, also generate 1--2 project-specific personas from the audience/brand info. +Auto-select 2-3 personas most relevant to this interface type (use the selection table in the reference). If `.cursorrules` contains a `## Design Context` section from `impeccable teach`, also generate 1-2 project-specific personas from the audience/brand info. For each selected persona, walk through the primary user action and list specific red flags found: @@ -154,7 +154,7 @@ For each selected persona, walk through the primary user action and list specifi **Jordan (First-Timer)**: Icon-only nav in sidebar. Technical jargon in error messages ("404 Not Found"). No visible help. Will abandon at step 2. -Be specific -- name the exact elements and interactions that fail each persona. Don't write generic persona descriptions; write what broke for them. +Be specific. Name the exact elements and interactions that fail each persona. Don't write generic persona descriptions; write what broke for them. #### Minor Observations Quick notes on smaller issues worth addressing. @@ -166,32 +166,32 @@ Provocative questions that might unlock better solutions: - "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 +- 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 +- Prioritize ruthlessly. If everything is important, nothing is. +- Don't soften criticism. Developers need honest feedback to ship great design. ### Step 4: Ask the User **After presenting findings**, use targeted questions based on what was actually found. ask the user directly to clarify what you cannot infer. These answers will shape the action plan. -Ask questions along these lines (adapt to the specific findings -- do NOT ask generic questions): +Ask questions along these lines (adapt to the specific findings; do NOT ask generic questions): -1. **Priority direction**: Based on the issues found, ask which category matters most to the user right now. For example: "I found problems with visual hierarchy, color usage, and information overload. Which area should we tackle first?" Offer the top 2--3 issue categories as options. +1. **Priority direction**: Based on the issues found, ask which category matters most to the user right now. For example: "I found problems with visual hierarchy, color usage, and information overload. Which area should we tackle first?" Offer the top 2-3 issue categories as options. -2. **Design intent**: If the critique found a tonal mismatch, ask whether it was intentional. For example: "The interface feels clinical and corporate. Is that the intended tone, or should it feel warmer/bolder/more playful?" Offer 2--3 tonal directions as options based on what would fix the issues found. +2. **Design intent**: If the critique found a tonal mismatch, ask whether it was intentional. For example: "The interface feels clinical and corporate. Is that the intended tone, or should it feel warmer/bolder/more playful?" Offer 2-3 tonal directions as options based on what would fix the issues found. 3. **Scope**: Ask how much the user wants to take on. For example: "I found N issues. Want to address everything, or focus on the top 3?" Offer scope options like "Top 3 only", "All issues", "Critical issues only". -4. **Constraints** (optional -- only ask if relevant): If the findings touch many areas, ask if anything is off-limits. For example: "Should any sections stay as-is?" This prevents the plan from touching things the user considers done. +4. **Constraints** (optional; only ask if relevant): If the findings touch many areas, ask if anything is off-limits. For example: "Should any sections stay as-is?" This prevents the plan from touching things the user considers done. **Rules for questions**: -- Every question must reference specific findings from the report -- never ask generic "who is your audience?" questions -- Keep it to 2--4 questions maximum -- respect the user's time -- Offer concrete options, not open-ended prompts -- If findings are straightforward (e.g., only 1--2 clear issues), skip questions and go directly to Step 5 +- Every question must reference specific findings from the report. Never ask generic "who is your audience?" questions. +- Keep it to 2-4 questions maximum. Respect the user's time. +- Offer concrete options, not open-ended prompts. +- If findings are straightforward (e.g., only 1-2 clear issues), skip questions and go directly to Step 5. ### Step 5: Recommended Actions @@ -201,12 +201,12 @@ Ask questions along these lines (adapt to the specific findings -- do NOT ask ge List recommended commands in priority order, based on the user's answers: -1. **`/command-name`** -- Brief description of what to fix (specific context from critique findings) -2. **`/command-name`** -- Brief description (specific context) +1. **`/command-name`**: Brief description of what to fix (specific context from critique findings) +2. **`/command-name`**: Brief description (specific context) ... **Rules for recommendations**: -- Only recommend commands from: /animate, /validate, /quieter, /craft, /optimize, /adapt, /clarify, /distill, /delight, /onboard, /normalize, /audit, /harden, /polish, /extract, /bolder, /arrange, /typeset, /critique, /colorize, /overdrive +- Only recommend commands from: /animate, /validate, /quieter, /shape, /optimize, /adapt, /clarify, /distill, /delight, /onboard, /normalize, /audit, /harden, /polish, /extract, /bolder, /arrange, /typeset, /critique, /colorize, /overdrive - Order by the user's stated priorities first, then by impact - Each item's description should carry enough context that the command knows what to focus on - Map each Priority Issue to the appropriate command diff --git a/.cursor/skills/impeccable/SKILL.md b/.cursor/skills/impeccable/SKILL.md index 5330034a7..f2f9eb138 100644 --- a/.cursor/skills/impeccable/SKILL.md +++ b/.cursor/skills/impeccable/SKILL.md @@ -1,6 +1,6 @@ --- name: impeccable -description: Create distinctive, production-grade frontend interfaces with high design quality. Generates creative, polished code that avoids generic AI aesthetics. Use when the user asks to build web components, pages, artifacts, posters, or applications, or when any design skill requires project context. Call with 'teach' argument to run design context setup. +description: Create distinctive, production-grade frontend interfaces with high design quality. Generates creative, polished code that avoids generic AI aesthetics. Use when the user asks to build web components, pages, artifacts, posters, or applications, or when any design skill requires project context. Call with 'craft' to run the full shape-then-build flow, or 'teach' for design context setup. license: Apache 2.0. Based on Anthropic's frontend-design skill. See NOTICE.md for attribution. --- @@ -148,6 +148,12 @@ Remember: the model is capable of extraordinary creative work. Don't hold back. --- +## Craft Mode + +If this skill is invoked with the argument "craft" (e.g., `/impeccable craft [feature description]`), follow the [craft flow](reference/craft.md). Pass any additional arguments as the feature description. + +--- + ## Teach Mode If this skill is invoked with the argument "teach" (e.g., `/impeccable teach`), skip all design work above and instead run the teach flow below. This is a one-time setup that gathers design context for the project. diff --git a/.cursor/skills/impeccable/reference/craft.md b/.cursor/skills/impeccable/reference/craft.md new file mode 100644 index 000000000..d2961057f --- /dev/null +++ b/.cursor/skills/impeccable/reference/craft.md @@ -0,0 +1,70 @@ +# Craft Flow + +Build a feature with impeccable UX and UI quality through a structured process: shape the design, load the right references, then build and iterate visually until the result is delightful. + +## Step 1: Shape the Design + +Run /shape, passing along whatever feature description the user provided. + +Wait for the design brief to be fully confirmed before proceeding. The brief is your blueprint, and every implementation decision should trace back to it. + +If the user has already run /shape and has a confirmed design brief, skip this step and use the existing brief. + +## Step 2: Load References + +Based on the design brief's "Recommended References" section, consult the relevant impeccable reference files. At minimum, always consult: + +- [spatial-design.md](spatial-design.md) for layout and spacing +- [typography.md](typography.md) for type hierarchy + +Then add references based on the brief's needs: +- Complex interactions or forms? Consult [interaction-design.md](interaction-design.md) +- Animation or transitions? Consult [motion-design.md](motion-design.md) +- Color-heavy or themed? Consult [color-and-contrast.md](color-and-contrast.md) +- Responsive requirements? Consult [responsive-design.md](responsive-design.md) +- Heavy on copy, labels, or errors? Consult [ux-writing.md](ux-writing.md) + +## Step 3: Build + +Implement the feature following the design brief. Work in this order: + +1. **Structure first**: HTML/semantic structure for the primary state. No styling yet. +2. **Layout and spacing**: Establish the spatial rhythm and visual hierarchy. +3. **Typography and color**: Apply the type scale and color system. +4. **Interactive states**: Hover, focus, active, disabled. +5. **Edge case states**: Empty, loading, error, overflow, first-run. +6. **Motion**: Purposeful transitions and animations (if appropriate). +7. **Responsive**: Adapt for different viewports. Don't just shrink; redesign for the context. + +### During Build +- Test with real (or realistic) data at every step, not placeholder text +- Check each state as you build it, not all at the end +- If you discover a design question, stop and ask rather than guessing +- Every visual choice should trace back to something in the design brief + +## Step 4: Visual Iteration + +**This step is critical.** Do not stop after the first implementation pass. + +Open the result in a browser window. If browser automation tools are available, use them to navigate to the page and visually inspect the result. If not, ask the user to open it and provide feedback. + +Iterate through these checks visually: + +1. **Does it match the brief?** Compare the live result against every section of the design brief. Fix discrepancies. +2. **Does it pass the AI slop test?** If someone saw this and said "AI made this," would they believe it immediately? If yes, it needs more design intention. +3. **Run /validate.** Fix any P0 or P1 issues. +4. **Check every state.** Navigate through empty, error, loading, and edge case states. Each one should feel intentional, not like an afterthought. +5. **Check responsive.** Resize the viewport. Does it adapt well or just shrink? +6. **Check the details.** Spacing consistency, type hierarchy clarity, color contrast, interactive feedback, motion timing. + +After each round of fixes, visually verify again. **Repeat until you would be proud to show this to the user.** The bar is not "it works"; the bar is "this delights." + +## Step 5: Present + +Present the result to the user: +- Show the feature in its primary state +- Walk through the key states (empty, error, responsive) +- Explain design decisions that connect back to the design brief +- Ask: "What's working? What isn't?" + +Iterate based on feedback. Good design is rarely right on the first pass. diff --git a/.cursor/skills/shape/SKILL.md b/.cursor/skills/shape/SKILL.md new file mode 100644 index 000000000..7e520562f --- /dev/null +++ b/.cursor/skills/shape/SKILL.md @@ -0,0 +1,93 @@ +--- +name: shape +description: Plan the UX and UI for a feature before writing code. Runs a structured discovery interview, then produces a design brief that guides implementation. Use during the planning phase to establish design direction, constraints, and strategy before any code is written. +--- + +## MANDATORY PREPARATION + +Invoke /impeccable, which contains design principles, anti-patterns, and the **Context Gathering Protocol**. Follow the protocol before proceeding. If no design context exists yet, you MUST run /impeccable teach first. + +--- + +Shape the UX and UI for a feature before any code is written. This skill produces a **design brief**: a structured artifact that guides implementation through discovery, not guesswork. + +**Scope**: Design planning only. This skill does NOT write code. It produces the thinking that makes code good. + +**Output**: A design brief that can be handed off to /impeccable craft, /impeccable, or any other implementation skill. + +## Philosophy + +Most AI-generated UIs fail not because of bad code, but because of skipped thinking. They jump to "here's a card grid" without asking "what is the user trying to accomplish?" This skill inverts that: understand deeply first, so implementation is precise. + +## Phase 1: Discovery Interview + +**Do NOT write any code or make any design decisions during this phase.** Your only job is to understand the feature deeply enough to make excellent design decisions later. + +Ask these questions in conversation, adapting based on answers. Don't dump them all at once; have a natural dialogue. ask the user directly to clarify what you cannot infer. + +### Purpose & Context +- What is this feature for? What problem does it solve? +- Who specifically will use it? (Not "users"; be specific: role, context, frequency) +- What does success look like? How will you know this feature is working? +- What's the user's state of mind when they reach this feature? (Rushed? Exploring? Anxious? Focused?) + +### Content & Data +- What content or data does this feature display or collect? +- What are the realistic ranges? (Minimum, typical, maximum, e.g., 0 items, 5 items, 500 items) +- What are the edge cases? (Empty state, error state, first-time use, power user) +- Is any content dynamic? What changes and how often? + +### Design Goals +- What's the single most important thing a user should do or understand here? +- What should this feel like? (Fast/efficient? Calm/trustworthy? Fun/playful? Premium/refined?) +- Are there existing patterns in the product this should be consistent with? +- Are there specific examples (inside or outside the product) that capture what you're going for? + +### Constraints +- Are there technical constraints? (Framework, performance budget, browser support) +- Are there content constraints? (Localization, dynamic text length, user-generated content) +- Mobile/responsive requirements? +- Accessibility requirements beyond WCAG AA? + +### Anti-Goals +- What should this NOT be? What would be a wrong direction? +- What's the biggest risk of getting this wrong? + +## Phase 2: Design Brief + +After the interview, synthesize everything into a structured design brief. Present it to the user for confirmation before considering this skill complete. + +### Brief Structure + +**1. Feature Summary** (2-3 sentences) +What this is, who it's for, what it needs to accomplish. + +**2. Primary User Action** +The single most important thing a user should do or understand here. + +**3. Design Direction** +How this should feel. What aesthetic approach fits. Reference the project's design context from `.impeccable.md` and explain how this feature should express it. + +**4. Layout Strategy** +High-level spatial approach: what gets emphasis, what's secondary, how information flows. Describe the visual hierarchy and rhythm, not specific CSS. + +**5. Key States** +List every state the feature needs: default, empty, loading, error, success, edge cases. For each, note what the user needs to see and feel. + +**6. Interaction Model** +How users interact with this feature. What happens on click, hover, scroll? What feedback do they get? What's the flow from entry to completion? + +**7. Content Requirements** +What copy, labels, empty state messages, error messages, and microcopy are needed. Note any dynamic content and its realistic ranges. + +**8. Recommended References** +Based on the brief, list which impeccable reference files would be most valuable during implementation (e.g., spatial-design.md for complex layouts, motion-design.md for animated features, interaction-design.md for form-heavy features). + +**9. Open Questions** +Anything unresolved that the implementer should resolve during build. + +--- + +ask the user directly to clarify what you cannot infer. Get explicit confirmation of the brief before finishing. If the user disagrees with any part, revisit the relevant discovery questions. + +Once confirmed, the brief is complete. The user can now hand it to /impeccable craft to build the feature, or use it to guide any other implementation approach. \ No newline at end of file diff --git a/.cursor/skills/validate/SKILL.md b/.cursor/skills/validate/SKILL.md index f711dcb7c..b4c183888 100644 --- a/.cursor/skills/validate/SKILL.md +++ b/.cursor/skills/validate/SKILL.md @@ -5,11 +5,11 @@ description: Fast visual validation after UX/UI changes. Checks anti-patterns, s ## MANDATORY PREPARATION -Invoke /impeccable -- it contains design principles, anti-patterns, and the **Context Gathering Protocol**. Follow the protocol before proceeding -- if no design context exists yet, you MUST run /impeccable teach first. +Invoke /impeccable, which contains design principles, anti-patterns, and the **Context Gathering Protocol**. Follow the protocol before proceeding. If no design context exists yet, you MUST run /impeccable teach first. --- -A fast, focused quality gate. Not a full audit or critique -- this is the 2-minute check you run after every UI change to catch the most common and damaging issues before they ship. +A fast, focused quality gate. Not a full audit or critique; this is the 2-minute check you run after every UI change to catch the most common and damaging issues before they ship. Think of this as a design linter: opinionated, fast, and actionable. Flag what's wrong, say how to fix it, move on. @@ -69,10 +69,10 @@ Check against ALL **DON'T** guidelines in the impeccable skill. The most common Report findings as a flat list, grouped by severity: **Severity levels:** -- **P0 -- Broken**: Visually broken, inaccessible, or fundamentally wrong. Fix before shipping. -- **P1 -- Anti-pattern**: Clear design anti-pattern that undermines quality. Fix now. -- **P2 -- Inconsistency**: Spacing, token, or style drift from the design system. Fix soon. -- **P3 -- Polish**: Minor refinement opportunity. Fix if time allows. +- **P0 (Broken)**: Visually broken, inaccessible, or fundamentally wrong. Fix before shipping. +- **P1 (Anti-pattern)**: Clear design anti-pattern that undermines quality. Fix now. +- **P2 (Inconsistency)**: Spacing, token, or style drift from the design system. Fix soon. +- **P3 (Polish)**: Minor refinement opportunity. Fix if time allows. For each finding: ``` @@ -80,7 +80,7 @@ For each finding: → Fix: Concrete action to take (file:line if applicable) ``` -Keep the total list short. If everything looks good, say so -- don't invent issues. +Keep the total list short. If everything looks good, say so. Don't invent issues. ## After Validation diff --git a/.gemini/skills/audit/SKILL.md b/.gemini/skills/audit/SKILL.md index b482d344e..f944d6111 100644 --- a/.gemini/skills/audit/SKILL.md +++ b/.gemini/skills/audit/SKILL.md @@ -106,7 +106,7 @@ For each issue, document: - **Impact**: How it affects users - **WCAG/Standard**: Which standard it violates (if applicable) - **Recommendation**: How to fix it -- **Suggested command**: Which command to use (prefer: /animate, /validate, /quieter, /craft, /optimize, /adapt, /clarify, /distill, /delight, /onboard, /normalize, /audit, /harden, /polish, /extract, /bolder, /arrange, /typeset, /critique, /colorize, /overdrive) +- **Suggested command**: Which command to use (prefer: /animate, /validate, /quieter, /shape, /optimize, /adapt, /clarify, /distill, /delight, /onboard, /normalize, /audit, /harden, /polish, /extract, /bolder, /arrange, /typeset, /critique, /colorize, /overdrive) ### Patterns & Systemic Issues @@ -125,7 +125,7 @@ List recommended commands in priority order (P0 first, then P1, then P2): 1. **[P?] `/command-name`** — Brief description (specific context from audit findings) 2. **[P?] `/command-name`** — Brief description (specific context) -**Rules**: Only recommend commands from: /animate, /validate, /quieter, /craft, /optimize, /adapt, /clarify, /distill, /delight, /onboard, /normalize, /audit, /harden, /polish, /extract, /bolder, /arrange, /typeset, /critique, /colorize, /overdrive. Map findings to the most appropriate command. End with `/polish` as the final step if any fixes were recommended. +**Rules**: Only recommend commands from: /animate, /validate, /quieter, /shape, /optimize, /adapt, /clarify, /distill, /delight, /onboard, /normalize, /audit, /harden, /polish, /extract, /bolder, /arrange, /typeset, /critique, /colorize, /overdrive. Map findings to the most appropriate command. End with `/polish` as the final step if any fixes were recommended. After presenting the summary, tell the user: diff --git a/.gemini/skills/craft/SKILL.md b/.gemini/skills/craft/SKILL.md deleted file mode 100644 index 1dde45c9b..000000000 --- a/.gemini/skills/craft/SKILL.md +++ /dev/null @@ -1,95 +0,0 @@ ---- -name: craft -description: Design and build ideal UX+UI for a feature through guided discovery. Interviews the user about purpose, audience, and design goals before implementing. Use when building a new feature, redesigning an existing one, or when the user wants a thoughtful, user-centered design process rather than jumping straight to code. ---- - -## MANDATORY PREPARATION - -Invoke /impeccable -- it contains design principles, anti-patterns, and the **Context Gathering Protocol**. Follow the protocol before proceeding -- if no design context exists yet, you MUST run /impeccable teach first. - ---- - -Build the ideal UX and UI for a feature. This skill is about getting the design RIGHT before writing code -- through structured discovery, not guesswork. - -**Scope**: UX + UI design and implementation. Out of scope: building the underlying business logic, backend, or data layer. If the feature needs backend work, note what's needed but focus on the interface. - -## Philosophy - -Most AI-generated UIs fail not because of bad code, but because of skipped thinking. They jump to "here's a card grid" without asking "what is the user trying to accomplish?" This skill inverts that: understand deeply, then build precisely. - -## Phase 1: Discovery Interview - -**Do NOT write any code during this phase.** Your only job is to understand the feature deeply enough to make excellent design decisions. - -Ask these questions in conversation, adapting based on answers. Don't dump them all at once -- have a natural dialogue. ask the user directly to clarify what you cannot infer. - -### Purpose & Context -- What is this feature for? What problem does it solve? -- Who specifically will use it? (Not "users" -- be specific: role, context, frequency) -- What does success look like? How will you know this feature is working? -- What's the user's state of mind when they reach this feature? (Rushed? Exploring? Anxious? Focused?) - -### Content & Data -- What content or data does this feature display or collect? -- What are the realistic ranges? (Minimum, typical, maximum -- e.g., 0 items, 5 items, 500 items) -- What are the edge cases? (Empty state, error state, first-time use, power user) -- Is any content dynamic? What changes and how often? - -### Design Goals -- What's the single most important thing a user should do or understand here? -- What should this feel like? (Fast/efficient? Calm/trustworthy? Fun/playful? Premium/refined?) -- Are there existing patterns in the product this should be consistent with? -- Are there specific examples (inside or outside the product) that capture what you're going for? - -### Constraints -- Are there technical constraints? (Framework, performance budget, browser support) -- Are there content constraints? (Localization, dynamic text length, user-generated content) -- Mobile/responsive requirements? -- Accessibility requirements beyond WCAG AA? - -### Anti-Goals -- What should this NOT be? What would be a wrong direction? -- What's the biggest risk of getting this wrong? - -## Phase 2: Design Synthesis - -After the interview, synthesize your understanding before touching code. Present this back to the user for confirmation: - -1. **Feature brief** (2-3 sentences): What this is, who it's for, what it needs to accomplish -2. **Primary user action**: The one thing that matters most -3. **Design direction**: How this should feel, what aesthetic approach fits -4. **Key states**: List every state the feature needs (default, empty, loading, error, success, edge cases) -5. **Open questions**: Anything unresolved that might change the approach - -ask the user directly to clarify what you cannot infer. -- get explicit confirmation before proceeding. If the user disagrees with your synthesis, revisit the relevant discovery questions. - -## Phase 3: Implementation - -Now build it. Use /impeccable as your design engine -- follow its principles, consult its references, avoid its anti-patterns. - -### Implementation Order -1. **Structure first**: HTML/semantic structure for the primary state. No styling yet. -2. **Layout and spacing**: Establish the spatial rhythm and visual hierarchy. -3. **Typography and color**: Apply the type scale and color system. -4. **Interactive states**: Hover, focus, active, disabled. -5. **Edge case states**: Empty, loading, error, overflow, first-run. -6. **Motion**: Purposeful transitions and animations (if appropriate). -7. **Responsive**: Adapt for different viewports -- don't just shrink, redesign for the context. - -### During Implementation -- Test with real (or realistic) data at every step, not placeholder text -- Check each state as you build it, not all at the end -- If you discover a design question during implementation, stop and ask rather than guessing -- Every visual choice should trace back to something learned in discovery - -## Phase 4: Validation - -After implementation, run /validate on your work. Fix any P0 or P1 issues before presenting to the user. - -Then present the result: -- Show the feature in its primary state -- Walk through the key states (empty, error, responsive) -- Explain design decisions that connect back to what you learned in discovery -- Ask for feedback: "What's working? What isn't?" - -Iterate based on feedback. Good design is rarely right on the first pass. \ No newline at end of file diff --git a/.gemini/skills/critique/SKILL.md b/.gemini/skills/critique/SKILL.md index 386ed527d..6a2ca17dd 100644 --- a/.gemini/skills/critique/SKILL.md +++ b/.gemini/skills/critique/SKILL.md @@ -7,21 +7,21 @@ description: Evaluate design from a UX perspective, assessing visual hierarchy, ### Step 1: Preparation -Invoke /impeccable -- it contains design principles, anti-patterns, and the **Context Gathering Protocol**. Follow the protocol before proceeding -- if no design context exists yet, you MUST run /impeccable teach first. Additionally gather: what the interface is trying to accomplish. +Invoke /impeccable, which contains design principles, anti-patterns, and the **Context Gathering Protocol**. Follow the protocol before proceeding. If no design context exists yet, you MUST run /impeccable teach first. Additionally gather: what the interface is trying to accomplish. ### Step 2: Gather Assessments Launch two independent assessments. **Neither must see the other's output** to avoid bias. -You SHOULD delegate each assessment to a separate sub-agent for independence. Use your environment's agent spawning mechanism -- e.g., Claude Code's `Agent` tool, or Codex's subagent spawning ("spawn two agents in parallel"). Sub-agents should return their findings as structured text -- do NOT output findings to the user yet. +You SHOULD delegate each assessment to a separate sub-agent for independence. Use your environment's agent spawning mechanism (e.g., Claude Code's `Agent` tool, or Codex's subagent spawning). Sub-agents should return their findings as structured text. Do NOT output findings to the user yet. If sub-agents are not available in the current environment, complete each assessment sequentially, writing findings to internal notes before proceeding. -**Tab isolation**: When browser automation is available, each assessment MUST create its own new tab -- never reuse an existing tab, even if one is already open at the correct URL. This prevents the two assessments from interfering with each other's page state. +**Tab isolation**: When browser automation is available, each assessment MUST create its own new tab. Never reuse an existing tab, even if one is already open at the correct URL. This prevents the two assessments from interfering with each other's page state. #### Assessment A: LLM Design Review -Read the relevant source files (HTML, CSS, JS/TS) and, if browser automation is available, visually inspect the live page. **Create a new tab** for this -- do not reuse existing tabs. After navigation, label the tab by setting the document title: +Read the relevant source files (HTML, CSS, JS/TS) and, if browser automation is available, visually inspect the live page. **Create a new tab** for this; do not reuse existing tabs. After navigation, label the tab by setting the document title: ```javascript document.title = '[LLM] ' + document.title; ``` @@ -32,8 +32,8 @@ Think like a design director. Evaluate: **Holistic Design Review**: 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). **Cognitive Load** (consult [cognitive-load](reference/cognitive-load.md)): -- Run the 8-item cognitive load checklist. Report failure count: 0--1 = low (good), 2--3 = moderate, 4+ = critical. -- Count visible options at each decision point -- if >4, flag it. +- Run the 8-item cognitive load checklist. Report failure count: 0-1 = low (good), 2-3 = moderate, 4+ = critical. +- Count visible options at each decision point. If >4, flag it. - Check for progressive disclosure: is complexity revealed only when needed? **Emotional Journey**: @@ -42,9 +42,9 @@ Think like a design director. Evaluate: - **Emotional valleys**: Check for anxiety spikes at high-stakes moments (payment, delete, commit). Are there design interventions (progress indicators, reassurance copy, undo options)? **Nielsen's Heuristics** (consult [heuristics-scoring](reference/heuristics-scoring.md)): -Score each of the 10 heuristics 0--4. This scoring will be presented in the report. +Score each of the 10 heuristics 0-4. This scoring will be presented in the report. -Return structured findings covering: AI slop verdict, heuristic scores, cognitive load assessment, what's working (2--3 items), priority issues (3--5 with what/why/fix), minor observations, and provocative questions. +Return structured findings covering: AI slop verdict, heuristic scores, cognitive load assessment, what's working (2-3 items), priority issues (3-5 with what/why/fix), minor observations, and provocative questions. #### Assessment B: Automated Detection @@ -63,37 +63,37 @@ npx impeccable --json [--fast] [target] **Browser visualization** (when browser automation tools are available AND the target is a viewable page): -The overlay is a **visual aid for the user** -- it highlights issues directly in their browser. Do NOT scroll through the page to screenshot overlays. Instead, read the console output to get the results programmatically. +The overlay is a **visual aid for the user**. It highlights issues directly in their browser. Do NOT scroll through the page to screenshot overlays. Instead, read the console output to get the results programmatically. 1. **Start the live detection server**: ```bash npx impeccable live & ``` Note the port printed to stdout (auto-assigned). Use `--port=PORT` to fix it. -2. **Create a new tab** and navigate to the page (use dev server URL for local files, or direct URL) -- do not reuse existing tabs +2. **Create a new tab** and navigate to the page (use dev server URL for local files, or direct URL). Do not reuse existing tabs. 3. **Label the tab** via `javascript_tool` so the user can distinguish it: ```javascript document.title = '[Human] ' + document.title; ``` -4. **Scroll to top** -- ensure the page is scrolled to the very top before injection +4. **Scroll to top** to ensure the page is scrolled to the very top before injection 5. **Inject** via `javascript_tool` (replace PORT with the port from step 1): ```javascript const s = document.createElement('script'); s.src = 'http://localhost:PORT/detect.js'; document.head.appendChild(s); ``` -6. Wait 2--3 seconds for the detector to render overlays -7. **Read results from console** using `read_console_messages` with pattern `impeccable` -- the detector logs all findings with the `[impeccable]` prefix. Do NOT scroll through the page to take screenshots of the overlays. +6. Wait 2-3 seconds for the detector to render overlays +7. **Read results from console** using `read_console_messages` with pattern `impeccable`. The detector logs all findings with the `[impeccable]` prefix. Do NOT scroll through the page to take screenshots of the overlays. 8. **Cleanup**: Stop the live server when done: ```bash npx impeccable live stop ``` -For multi-view targets, inject on 3--5 representative pages. If injection fails, continue with CLI results only. +For multi-view targets, inject on 3-5 representative pages. If injection fails, continue with CLI results only. Return: CLI findings (JSON), browser console findings (if applicable), and any false positives noted. ### Step 3: Generate Combined Critique Report -Synthesize both assessments into a single report. Do NOT simply concatenate -- weave the findings together, noting where the LLM review and detector agree, where the detector caught issues the LLM missed, and where detector findings are false positives. +Synthesize both assessments into a single report. Do NOT simply concatenate. Weave the findings together, noting where the LLM review and detector agree, where the detector caught issues the LLM missed, and where detector findings are false positives. Structure your feedback as a design director would: @@ -104,7 +104,7 @@ Present the Nielsen's 10 heuristics scores as a table: | # | Heuristic | Score | Key Issue | |---|-----------|-------|-----------| -| 1 | Visibility of System Status | ? | [specific finding or "--" if solid] | +| 1 | Visibility of System Status | ? | [specific finding or "n/a" if solid] | | 2 | Match System / Real World | ? | | | 3 | User Control and Freedom | ? | | | 4 | Consistency and Standards | ? | | @@ -116,7 +116,7 @@ Present the Nielsen's 10 heuristics scores as a table: | 10 | Help and Documentation | ? | | | **Total** | | **??/40** | **[Rating band]** | -Be honest with scores. A 4 means genuinely excellent. Most real interfaces score 20--32. +Be honest with scores. A 4 means genuinely excellent. Most real interfaces score 20-32. #### Anti-Patterns Verdict @@ -129,24 +129,24 @@ Be honest with scores. A 4 means genuinely excellent. Most real interfaces score **Visual overlays** (if browser was used): Tell the user that overlays are now visible in the **[Human]** tab in their browser, highlighting the detected issues. Summarize what the console output reported. #### Overall Impression -A brief gut reaction -- what works, what doesn't, and the single biggest opportunity. +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. +Highlight 2-3 things done well. Be specific about why they work. #### Priority Issues -The 3--5 most impactful design problems, ordered by importance. +The 3-5 most impactful design problems, ordered by importance. -For each issue, tag with **P0--P3 severity** (consult [heuristics-scoring](reference/heuristics-scoring.md) for severity definitions): +For each issue, tag with **P0-P3 severity** (consult [heuristics-scoring](reference/heuristics-scoring.md) for severity definitions): - **[P?] What**: Name the problem clearly - **Why it matters**: How this hurts users or undermines goals - **Fix**: What to do about it (be concrete) -- **Suggested command**: Which command could address this (from: /animate, /validate, /quieter, /craft, /optimize, /adapt, /clarify, /distill, /delight, /onboard, /normalize, /audit, /harden, /polish, /extract, /bolder, /arrange, /typeset, /critique, /colorize, /overdrive) +- **Suggested command**: Which command could address this (from: /animate, /validate, /quieter, /shape, /optimize, /adapt, /clarify, /distill, /delight, /onboard, /normalize, /audit, /harden, /polish, /extract, /bolder, /arrange, /typeset, /critique, /colorize, /overdrive) #### Persona Red Flags > *Consult [personas](reference/personas.md)* -Auto-select 2--3 personas most relevant to this interface type (use the selection table in the reference). If `GEMINI.md` contains a `## Design Context` section from `impeccable teach`, also generate 1--2 project-specific personas from the audience/brand info. +Auto-select 2-3 personas most relevant to this interface type (use the selection table in the reference). If `GEMINI.md` contains a `## Design Context` section from `impeccable teach`, also generate 1-2 project-specific personas from the audience/brand info. For each selected persona, walk through the primary user action and list specific red flags found: @@ -154,7 +154,7 @@ For each selected persona, walk through the primary user action and list specifi **Jordan (First-Timer)**: Icon-only nav in sidebar. Technical jargon in error messages ("404 Not Found"). No visible help. Will abandon at step 2. -Be specific -- name the exact elements and interactions that fail each persona. Don't write generic persona descriptions; write what broke for them. +Be specific. Name the exact elements and interactions that fail each persona. Don't write generic persona descriptions; write what broke for them. #### Minor Observations Quick notes on smaller issues worth addressing. @@ -166,32 +166,32 @@ Provocative questions that might unlock better solutions: - "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 +- 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 +- Prioritize ruthlessly. If everything is important, nothing is. +- Don't soften criticism. Developers need honest feedback to ship great design. ### Step 4: Ask the User **After presenting findings**, use targeted questions based on what was actually found. ask the user directly to clarify what you cannot infer. These answers will shape the action plan. -Ask questions along these lines (adapt to the specific findings -- do NOT ask generic questions): +Ask questions along these lines (adapt to the specific findings; do NOT ask generic questions): -1. **Priority direction**: Based on the issues found, ask which category matters most to the user right now. For example: "I found problems with visual hierarchy, color usage, and information overload. Which area should we tackle first?" Offer the top 2--3 issue categories as options. +1. **Priority direction**: Based on the issues found, ask which category matters most to the user right now. For example: "I found problems with visual hierarchy, color usage, and information overload. Which area should we tackle first?" Offer the top 2-3 issue categories as options. -2. **Design intent**: If the critique found a tonal mismatch, ask whether it was intentional. For example: "The interface feels clinical and corporate. Is that the intended tone, or should it feel warmer/bolder/more playful?" Offer 2--3 tonal directions as options based on what would fix the issues found. +2. **Design intent**: If the critique found a tonal mismatch, ask whether it was intentional. For example: "The interface feels clinical and corporate. Is that the intended tone, or should it feel warmer/bolder/more playful?" Offer 2-3 tonal directions as options based on what would fix the issues found. 3. **Scope**: Ask how much the user wants to take on. For example: "I found N issues. Want to address everything, or focus on the top 3?" Offer scope options like "Top 3 only", "All issues", "Critical issues only". -4. **Constraints** (optional -- only ask if relevant): If the findings touch many areas, ask if anything is off-limits. For example: "Should any sections stay as-is?" This prevents the plan from touching things the user considers done. +4. **Constraints** (optional; only ask if relevant): If the findings touch many areas, ask if anything is off-limits. For example: "Should any sections stay as-is?" This prevents the plan from touching things the user considers done. **Rules for questions**: -- Every question must reference specific findings from the report -- never ask generic "who is your audience?" questions -- Keep it to 2--4 questions maximum -- respect the user's time -- Offer concrete options, not open-ended prompts -- If findings are straightforward (e.g., only 1--2 clear issues), skip questions and go directly to Step 5 +- Every question must reference specific findings from the report. Never ask generic "who is your audience?" questions. +- Keep it to 2-4 questions maximum. Respect the user's time. +- Offer concrete options, not open-ended prompts. +- If findings are straightforward (e.g., only 1-2 clear issues), skip questions and go directly to Step 5. ### Step 5: Recommended Actions @@ -201,12 +201,12 @@ Ask questions along these lines (adapt to the specific findings -- do NOT ask ge List recommended commands in priority order, based on the user's answers: -1. **`/command-name`** -- Brief description of what to fix (specific context from critique findings) -2. **`/command-name`** -- Brief description (specific context) +1. **`/command-name`**: Brief description of what to fix (specific context from critique findings) +2. **`/command-name`**: Brief description (specific context) ... **Rules for recommendations**: -- Only recommend commands from: /animate, /validate, /quieter, /craft, /optimize, /adapt, /clarify, /distill, /delight, /onboard, /normalize, /audit, /harden, /polish, /extract, /bolder, /arrange, /typeset, /critique, /colorize, /overdrive +- Only recommend commands from: /animate, /validate, /quieter, /shape, /optimize, /adapt, /clarify, /distill, /delight, /onboard, /normalize, /audit, /harden, /polish, /extract, /bolder, /arrange, /typeset, /critique, /colorize, /overdrive - Order by the user's stated priorities first, then by impact - Each item's description should carry enough context that the command knows what to focus on - Map each Priority Issue to the appropriate command diff --git a/.gemini/skills/impeccable/SKILL.md b/.gemini/skills/impeccable/SKILL.md index 5932578e2..c577cefa2 100644 --- a/.gemini/skills/impeccable/SKILL.md +++ b/.gemini/skills/impeccable/SKILL.md @@ -1,6 +1,6 @@ --- name: impeccable -description: Create distinctive, production-grade frontend interfaces with high design quality. Generates creative, polished code that avoids generic AI aesthetics. Use when the user asks to build web components, pages, artifacts, posters, or applications, or when any design skill requires project context. Call with 'teach' argument to run design context setup. +description: Create distinctive, production-grade frontend interfaces with high design quality. Generates creative, polished code that avoids generic AI aesthetics. Use when the user asks to build web components, pages, artifacts, posters, or applications, or when any design skill requires project context. Call with 'craft' to run the full shape-then-build flow, or 'teach' for design context setup. --- This skill guides creation of distinctive, production-grade frontend interfaces that avoid generic "AI slop" aesthetics. Implement real working code with exceptional attention to aesthetic details and creative choices. @@ -147,6 +147,12 @@ Remember: Gemini is capable of extraordinary creative work. Don't hold back. Sho --- +## Craft Mode + +If this skill is invoked with the argument "craft" (e.g., `/impeccable craft [feature description]`), follow the [craft flow](reference/craft.md). Pass any additional arguments as the feature description. + +--- + ## Teach Mode If this skill is invoked with the argument "teach" (e.g., `/impeccable teach`), skip all design work above and instead run the teach flow below. This is a one-time setup that gathers design context for the project. diff --git a/.gemini/skills/impeccable/reference/craft.md b/.gemini/skills/impeccable/reference/craft.md new file mode 100644 index 000000000..d2961057f --- /dev/null +++ b/.gemini/skills/impeccable/reference/craft.md @@ -0,0 +1,70 @@ +# Craft Flow + +Build a feature with impeccable UX and UI quality through a structured process: shape the design, load the right references, then build and iterate visually until the result is delightful. + +## Step 1: Shape the Design + +Run /shape, passing along whatever feature description the user provided. + +Wait for the design brief to be fully confirmed before proceeding. The brief is your blueprint, and every implementation decision should trace back to it. + +If the user has already run /shape and has a confirmed design brief, skip this step and use the existing brief. + +## Step 2: Load References + +Based on the design brief's "Recommended References" section, consult the relevant impeccable reference files. At minimum, always consult: + +- [spatial-design.md](spatial-design.md) for layout and spacing +- [typography.md](typography.md) for type hierarchy + +Then add references based on the brief's needs: +- Complex interactions or forms? Consult [interaction-design.md](interaction-design.md) +- Animation or transitions? Consult [motion-design.md](motion-design.md) +- Color-heavy or themed? Consult [color-and-contrast.md](color-and-contrast.md) +- Responsive requirements? Consult [responsive-design.md](responsive-design.md) +- Heavy on copy, labels, or errors? Consult [ux-writing.md](ux-writing.md) + +## Step 3: Build + +Implement the feature following the design brief. Work in this order: + +1. **Structure first**: HTML/semantic structure for the primary state. No styling yet. +2. **Layout and spacing**: Establish the spatial rhythm and visual hierarchy. +3. **Typography and color**: Apply the type scale and color system. +4. **Interactive states**: Hover, focus, active, disabled. +5. **Edge case states**: Empty, loading, error, overflow, first-run. +6. **Motion**: Purposeful transitions and animations (if appropriate). +7. **Responsive**: Adapt for different viewports. Don't just shrink; redesign for the context. + +### During Build +- Test with real (or realistic) data at every step, not placeholder text +- Check each state as you build it, not all at the end +- If you discover a design question, stop and ask rather than guessing +- Every visual choice should trace back to something in the design brief + +## Step 4: Visual Iteration + +**This step is critical.** Do not stop after the first implementation pass. + +Open the result in a browser window. If browser automation tools are available, use them to navigate to the page and visually inspect the result. If not, ask the user to open it and provide feedback. + +Iterate through these checks visually: + +1. **Does it match the brief?** Compare the live result against every section of the design brief. Fix discrepancies. +2. **Does it pass the AI slop test?** If someone saw this and said "AI made this," would they believe it immediately? If yes, it needs more design intention. +3. **Run /validate.** Fix any P0 or P1 issues. +4. **Check every state.** Navigate through empty, error, loading, and edge case states. Each one should feel intentional, not like an afterthought. +5. **Check responsive.** Resize the viewport. Does it adapt well or just shrink? +6. **Check the details.** Spacing consistency, type hierarchy clarity, color contrast, interactive feedback, motion timing. + +After each round of fixes, visually verify again. **Repeat until you would be proud to show this to the user.** The bar is not "it works"; the bar is "this delights." + +## Step 5: Present + +Present the result to the user: +- Show the feature in its primary state +- Walk through the key states (empty, error, responsive) +- Explain design decisions that connect back to the design brief +- Ask: "What's working? What isn't?" + +Iterate based on feedback. Good design is rarely right on the first pass. diff --git a/.gemini/skills/shape/SKILL.md b/.gemini/skills/shape/SKILL.md new file mode 100644 index 000000000..7e520562f --- /dev/null +++ b/.gemini/skills/shape/SKILL.md @@ -0,0 +1,93 @@ +--- +name: shape +description: Plan the UX and UI for a feature before writing code. Runs a structured discovery interview, then produces a design brief that guides implementation. Use during the planning phase to establish design direction, constraints, and strategy before any code is written. +--- + +## MANDATORY PREPARATION + +Invoke /impeccable, which contains design principles, anti-patterns, and the **Context Gathering Protocol**. Follow the protocol before proceeding. If no design context exists yet, you MUST run /impeccable teach first. + +--- + +Shape the UX and UI for a feature before any code is written. This skill produces a **design brief**: a structured artifact that guides implementation through discovery, not guesswork. + +**Scope**: Design planning only. This skill does NOT write code. It produces the thinking that makes code good. + +**Output**: A design brief that can be handed off to /impeccable craft, /impeccable, or any other implementation skill. + +## Philosophy + +Most AI-generated UIs fail not because of bad code, but because of skipped thinking. They jump to "here's a card grid" without asking "what is the user trying to accomplish?" This skill inverts that: understand deeply first, so implementation is precise. + +## Phase 1: Discovery Interview + +**Do NOT write any code or make any design decisions during this phase.** Your only job is to understand the feature deeply enough to make excellent design decisions later. + +Ask these questions in conversation, adapting based on answers. Don't dump them all at once; have a natural dialogue. ask the user directly to clarify what you cannot infer. + +### Purpose & Context +- What is this feature for? What problem does it solve? +- Who specifically will use it? (Not "users"; be specific: role, context, frequency) +- What does success look like? How will you know this feature is working? +- What's the user's state of mind when they reach this feature? (Rushed? Exploring? Anxious? Focused?) + +### Content & Data +- What content or data does this feature display or collect? +- What are the realistic ranges? (Minimum, typical, maximum, e.g., 0 items, 5 items, 500 items) +- What are the edge cases? (Empty state, error state, first-time use, power user) +- Is any content dynamic? What changes and how often? + +### Design Goals +- What's the single most important thing a user should do or understand here? +- What should this feel like? (Fast/efficient? Calm/trustworthy? Fun/playful? Premium/refined?) +- Are there existing patterns in the product this should be consistent with? +- Are there specific examples (inside or outside the product) that capture what you're going for? + +### Constraints +- Are there technical constraints? (Framework, performance budget, browser support) +- Are there content constraints? (Localization, dynamic text length, user-generated content) +- Mobile/responsive requirements? +- Accessibility requirements beyond WCAG AA? + +### Anti-Goals +- What should this NOT be? What would be a wrong direction? +- What's the biggest risk of getting this wrong? + +## Phase 2: Design Brief + +After the interview, synthesize everything into a structured design brief. Present it to the user for confirmation before considering this skill complete. + +### Brief Structure + +**1. Feature Summary** (2-3 sentences) +What this is, who it's for, what it needs to accomplish. + +**2. Primary User Action** +The single most important thing a user should do or understand here. + +**3. Design Direction** +How this should feel. What aesthetic approach fits. Reference the project's design context from `.impeccable.md` and explain how this feature should express it. + +**4. Layout Strategy** +High-level spatial approach: what gets emphasis, what's secondary, how information flows. Describe the visual hierarchy and rhythm, not specific CSS. + +**5. Key States** +List every state the feature needs: default, empty, loading, error, success, edge cases. For each, note what the user needs to see and feel. + +**6. Interaction Model** +How users interact with this feature. What happens on click, hover, scroll? What feedback do they get? What's the flow from entry to completion? + +**7. Content Requirements** +What copy, labels, empty state messages, error messages, and microcopy are needed. Note any dynamic content and its realistic ranges. + +**8. Recommended References** +Based on the brief, list which impeccable reference files would be most valuable during implementation (e.g., spatial-design.md for complex layouts, motion-design.md for animated features, interaction-design.md for form-heavy features). + +**9. Open Questions** +Anything unresolved that the implementer should resolve during build. + +--- + +ask the user directly to clarify what you cannot infer. Get explicit confirmation of the brief before finishing. If the user disagrees with any part, revisit the relevant discovery questions. + +Once confirmed, the brief is complete. The user can now hand it to /impeccable craft to build the feature, or use it to guide any other implementation approach. \ No newline at end of file diff --git a/.gemini/skills/validate/SKILL.md b/.gemini/skills/validate/SKILL.md index f711dcb7c..b4c183888 100644 --- a/.gemini/skills/validate/SKILL.md +++ b/.gemini/skills/validate/SKILL.md @@ -5,11 +5,11 @@ description: Fast visual validation after UX/UI changes. Checks anti-patterns, s ## MANDATORY PREPARATION -Invoke /impeccable -- it contains design principles, anti-patterns, and the **Context Gathering Protocol**. Follow the protocol before proceeding -- if no design context exists yet, you MUST run /impeccable teach first. +Invoke /impeccable, which contains design principles, anti-patterns, and the **Context Gathering Protocol**. Follow the protocol before proceeding. If no design context exists yet, you MUST run /impeccable teach first. --- -A fast, focused quality gate. Not a full audit or critique -- this is the 2-minute check you run after every UI change to catch the most common and damaging issues before they ship. +A fast, focused quality gate. Not a full audit or critique; this is the 2-minute check you run after every UI change to catch the most common and damaging issues before they ship. Think of this as a design linter: opinionated, fast, and actionable. Flag what's wrong, say how to fix it, move on. @@ -69,10 +69,10 @@ Check against ALL **DON'T** guidelines in the impeccable skill. The most common Report findings as a flat list, grouped by severity: **Severity levels:** -- **P0 -- Broken**: Visually broken, inaccessible, or fundamentally wrong. Fix before shipping. -- **P1 -- Anti-pattern**: Clear design anti-pattern that undermines quality. Fix now. -- **P2 -- Inconsistency**: Spacing, token, or style drift from the design system. Fix soon. -- **P3 -- Polish**: Minor refinement opportunity. Fix if time allows. +- **P0 (Broken)**: Visually broken, inaccessible, or fundamentally wrong. Fix before shipping. +- **P1 (Anti-pattern)**: Clear design anti-pattern that undermines quality. Fix now. +- **P2 (Inconsistency)**: Spacing, token, or style drift from the design system. Fix soon. +- **P3 (Polish)**: Minor refinement opportunity. Fix if time allows. For each finding: ``` @@ -80,7 +80,7 @@ For each finding: → Fix: Concrete action to take (file:line if applicable) ``` -Keep the total list short. If everything looks good, say so -- don't invent issues. +Keep the total list short. If everything looks good, say so. Don't invent issues. ## After Validation diff --git a/.kiro/skills/audit/SKILL.md b/.kiro/skills/audit/SKILL.md index b482d344e..f944d6111 100644 --- a/.kiro/skills/audit/SKILL.md +++ b/.kiro/skills/audit/SKILL.md @@ -106,7 +106,7 @@ For each issue, document: - **Impact**: How it affects users - **WCAG/Standard**: Which standard it violates (if applicable) - **Recommendation**: How to fix it -- **Suggested command**: Which command to use (prefer: /animate, /validate, /quieter, /craft, /optimize, /adapt, /clarify, /distill, /delight, /onboard, /normalize, /audit, /harden, /polish, /extract, /bolder, /arrange, /typeset, /critique, /colorize, /overdrive) +- **Suggested command**: Which command to use (prefer: /animate, /validate, /quieter, /shape, /optimize, /adapt, /clarify, /distill, /delight, /onboard, /normalize, /audit, /harden, /polish, /extract, /bolder, /arrange, /typeset, /critique, /colorize, /overdrive) ### Patterns & Systemic Issues @@ -125,7 +125,7 @@ List recommended commands in priority order (P0 first, then P1, then P2): 1. **[P?] `/command-name`** — Brief description (specific context from audit findings) 2. **[P?] `/command-name`** — Brief description (specific context) -**Rules**: Only recommend commands from: /animate, /validate, /quieter, /craft, /optimize, /adapt, /clarify, /distill, /delight, /onboard, /normalize, /audit, /harden, /polish, /extract, /bolder, /arrange, /typeset, /critique, /colorize, /overdrive. Map findings to the most appropriate command. End with `/polish` as the final step if any fixes were recommended. +**Rules**: Only recommend commands from: /animate, /validate, /quieter, /shape, /optimize, /adapt, /clarify, /distill, /delight, /onboard, /normalize, /audit, /harden, /polish, /extract, /bolder, /arrange, /typeset, /critique, /colorize, /overdrive. Map findings to the most appropriate command. End with `/polish` as the final step if any fixes were recommended. After presenting the summary, tell the user: diff --git a/.kiro/skills/craft/SKILL.md b/.kiro/skills/craft/SKILL.md deleted file mode 100644 index 1dde45c9b..000000000 --- a/.kiro/skills/craft/SKILL.md +++ /dev/null @@ -1,95 +0,0 @@ ---- -name: craft -description: Design and build ideal UX+UI for a feature through guided discovery. Interviews the user about purpose, audience, and design goals before implementing. Use when building a new feature, redesigning an existing one, or when the user wants a thoughtful, user-centered design process rather than jumping straight to code. ---- - -## MANDATORY PREPARATION - -Invoke /impeccable -- it contains design principles, anti-patterns, and the **Context Gathering Protocol**. Follow the protocol before proceeding -- if no design context exists yet, you MUST run /impeccable teach first. - ---- - -Build the ideal UX and UI for a feature. This skill is about getting the design RIGHT before writing code -- through structured discovery, not guesswork. - -**Scope**: UX + UI design and implementation. Out of scope: building the underlying business logic, backend, or data layer. If the feature needs backend work, note what's needed but focus on the interface. - -## Philosophy - -Most AI-generated UIs fail not because of bad code, but because of skipped thinking. They jump to "here's a card grid" without asking "what is the user trying to accomplish?" This skill inverts that: understand deeply, then build precisely. - -## Phase 1: Discovery Interview - -**Do NOT write any code during this phase.** Your only job is to understand the feature deeply enough to make excellent design decisions. - -Ask these questions in conversation, adapting based on answers. Don't dump them all at once -- have a natural dialogue. ask the user directly to clarify what you cannot infer. - -### Purpose & Context -- What is this feature for? What problem does it solve? -- Who specifically will use it? (Not "users" -- be specific: role, context, frequency) -- What does success look like? How will you know this feature is working? -- What's the user's state of mind when they reach this feature? (Rushed? Exploring? Anxious? Focused?) - -### Content & Data -- What content or data does this feature display or collect? -- What are the realistic ranges? (Minimum, typical, maximum -- e.g., 0 items, 5 items, 500 items) -- What are the edge cases? (Empty state, error state, first-time use, power user) -- Is any content dynamic? What changes and how often? - -### Design Goals -- What's the single most important thing a user should do or understand here? -- What should this feel like? (Fast/efficient? Calm/trustworthy? Fun/playful? Premium/refined?) -- Are there existing patterns in the product this should be consistent with? -- Are there specific examples (inside or outside the product) that capture what you're going for? - -### Constraints -- Are there technical constraints? (Framework, performance budget, browser support) -- Are there content constraints? (Localization, dynamic text length, user-generated content) -- Mobile/responsive requirements? -- Accessibility requirements beyond WCAG AA? - -### Anti-Goals -- What should this NOT be? What would be a wrong direction? -- What's the biggest risk of getting this wrong? - -## Phase 2: Design Synthesis - -After the interview, synthesize your understanding before touching code. Present this back to the user for confirmation: - -1. **Feature brief** (2-3 sentences): What this is, who it's for, what it needs to accomplish -2. **Primary user action**: The one thing that matters most -3. **Design direction**: How this should feel, what aesthetic approach fits -4. **Key states**: List every state the feature needs (default, empty, loading, error, success, edge cases) -5. **Open questions**: Anything unresolved that might change the approach - -ask the user directly to clarify what you cannot infer. -- get explicit confirmation before proceeding. If the user disagrees with your synthesis, revisit the relevant discovery questions. - -## Phase 3: Implementation - -Now build it. Use /impeccable as your design engine -- follow its principles, consult its references, avoid its anti-patterns. - -### Implementation Order -1. **Structure first**: HTML/semantic structure for the primary state. No styling yet. -2. **Layout and spacing**: Establish the spatial rhythm and visual hierarchy. -3. **Typography and color**: Apply the type scale and color system. -4. **Interactive states**: Hover, focus, active, disabled. -5. **Edge case states**: Empty, loading, error, overflow, first-run. -6. **Motion**: Purposeful transitions and animations (if appropriate). -7. **Responsive**: Adapt for different viewports -- don't just shrink, redesign for the context. - -### During Implementation -- Test with real (or realistic) data at every step, not placeholder text -- Check each state as you build it, not all at the end -- If you discover a design question during implementation, stop and ask rather than guessing -- Every visual choice should trace back to something learned in discovery - -## Phase 4: Validation - -After implementation, run /validate on your work. Fix any P0 or P1 issues before presenting to the user. - -Then present the result: -- Show the feature in its primary state -- Walk through the key states (empty, error, responsive) -- Explain design decisions that connect back to what you learned in discovery -- Ask for feedback: "What's working? What isn't?" - -Iterate based on feedback. Good design is rarely right on the first pass. \ No newline at end of file diff --git a/.kiro/skills/critique/SKILL.md b/.kiro/skills/critique/SKILL.md index c3f072ae3..ff002dc40 100644 --- a/.kiro/skills/critique/SKILL.md +++ b/.kiro/skills/critique/SKILL.md @@ -7,21 +7,21 @@ description: Evaluate design from a UX perspective, assessing visual hierarchy, ### Step 1: Preparation -Invoke /impeccable -- it contains design principles, anti-patterns, and the **Context Gathering Protocol**. Follow the protocol before proceeding -- if no design context exists yet, you MUST run /impeccable teach first. Additionally gather: what the interface is trying to accomplish. +Invoke /impeccable, which contains design principles, anti-patterns, and the **Context Gathering Protocol**. Follow the protocol before proceeding. If no design context exists yet, you MUST run /impeccable teach first. Additionally gather: what the interface is trying to accomplish. ### Step 2: Gather Assessments Launch two independent assessments. **Neither must see the other's output** to avoid bias. -You SHOULD delegate each assessment to a separate sub-agent for independence. Use your environment's agent spawning mechanism -- e.g., Claude Code's `Agent` tool, or Codex's subagent spawning ("spawn two agents in parallel"). Sub-agents should return their findings as structured text -- do NOT output findings to the user yet. +You SHOULD delegate each assessment to a separate sub-agent for independence. Use your environment's agent spawning mechanism (e.g., Claude Code's `Agent` tool, or Codex's subagent spawning). Sub-agents should return their findings as structured text. Do NOT output findings to the user yet. If sub-agents are not available in the current environment, complete each assessment sequentially, writing findings to internal notes before proceeding. -**Tab isolation**: When browser automation is available, each assessment MUST create its own new tab -- never reuse an existing tab, even if one is already open at the correct URL. This prevents the two assessments from interfering with each other's page state. +**Tab isolation**: When browser automation is available, each assessment MUST create its own new tab. Never reuse an existing tab, even if one is already open at the correct URL. This prevents the two assessments from interfering with each other's page state. #### Assessment A: LLM Design Review -Read the relevant source files (HTML, CSS, JS/TS) and, if browser automation is available, visually inspect the live page. **Create a new tab** for this -- do not reuse existing tabs. After navigation, label the tab by setting the document title: +Read the relevant source files (HTML, CSS, JS/TS) and, if browser automation is available, visually inspect the live page. **Create a new tab** for this; do not reuse existing tabs. After navigation, label the tab by setting the document title: ```javascript document.title = '[LLM] ' + document.title; ``` @@ -32,8 +32,8 @@ Think like a design director. Evaluate: **Holistic Design Review**: 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). **Cognitive Load** (consult [cognitive-load](reference/cognitive-load.md)): -- Run the 8-item cognitive load checklist. Report failure count: 0--1 = low (good), 2--3 = moderate, 4+ = critical. -- Count visible options at each decision point -- if >4, flag it. +- Run the 8-item cognitive load checklist. Report failure count: 0-1 = low (good), 2-3 = moderate, 4+ = critical. +- Count visible options at each decision point. If >4, flag it. - Check for progressive disclosure: is complexity revealed only when needed? **Emotional Journey**: @@ -42,9 +42,9 @@ Think like a design director. Evaluate: - **Emotional valleys**: Check for anxiety spikes at high-stakes moments (payment, delete, commit). Are there design interventions (progress indicators, reassurance copy, undo options)? **Nielsen's Heuristics** (consult [heuristics-scoring](reference/heuristics-scoring.md)): -Score each of the 10 heuristics 0--4. This scoring will be presented in the report. +Score each of the 10 heuristics 0-4. This scoring will be presented in the report. -Return structured findings covering: AI slop verdict, heuristic scores, cognitive load assessment, what's working (2--3 items), priority issues (3--5 with what/why/fix), minor observations, and provocative questions. +Return structured findings covering: AI slop verdict, heuristic scores, cognitive load assessment, what's working (2-3 items), priority issues (3-5 with what/why/fix), minor observations, and provocative questions. #### Assessment B: Automated Detection @@ -63,37 +63,37 @@ npx impeccable --json [--fast] [target] **Browser visualization** (when browser automation tools are available AND the target is a viewable page): -The overlay is a **visual aid for the user** -- it highlights issues directly in their browser. Do NOT scroll through the page to screenshot overlays. Instead, read the console output to get the results programmatically. +The overlay is a **visual aid for the user**. It highlights issues directly in their browser. Do NOT scroll through the page to screenshot overlays. Instead, read the console output to get the results programmatically. 1. **Start the live detection server**: ```bash npx impeccable live & ``` Note the port printed to stdout (auto-assigned). Use `--port=PORT` to fix it. -2. **Create a new tab** and navigate to the page (use dev server URL for local files, or direct URL) -- do not reuse existing tabs +2. **Create a new tab** and navigate to the page (use dev server URL for local files, or direct URL). Do not reuse existing tabs. 3. **Label the tab** via `javascript_tool` so the user can distinguish it: ```javascript document.title = '[Human] ' + document.title; ``` -4. **Scroll to top** -- ensure the page is scrolled to the very top before injection +4. **Scroll to top** to ensure the page is scrolled to the very top before injection 5. **Inject** via `javascript_tool` (replace PORT with the port from step 1): ```javascript const s = document.createElement('script'); s.src = 'http://localhost:PORT/detect.js'; document.head.appendChild(s); ``` -6. Wait 2--3 seconds for the detector to render overlays -7. **Read results from console** using `read_console_messages` with pattern `impeccable` -- the detector logs all findings with the `[impeccable]` prefix. Do NOT scroll through the page to take screenshots of the overlays. +6. Wait 2-3 seconds for the detector to render overlays +7. **Read results from console** using `read_console_messages` with pattern `impeccable`. The detector logs all findings with the `[impeccable]` prefix. Do NOT scroll through the page to take screenshots of the overlays. 8. **Cleanup**: Stop the live server when done: ```bash npx impeccable live stop ``` -For multi-view targets, inject on 3--5 representative pages. If injection fails, continue with CLI results only. +For multi-view targets, inject on 3-5 representative pages. If injection fails, continue with CLI results only. Return: CLI findings (JSON), browser console findings (if applicable), and any false positives noted. ### Step 3: Generate Combined Critique Report -Synthesize both assessments into a single report. Do NOT simply concatenate -- weave the findings together, noting where the LLM review and detector agree, where the detector caught issues the LLM missed, and where detector findings are false positives. +Synthesize both assessments into a single report. Do NOT simply concatenate. Weave the findings together, noting where the LLM review and detector agree, where the detector caught issues the LLM missed, and where detector findings are false positives. Structure your feedback as a design director would: @@ -104,7 +104,7 @@ Present the Nielsen's 10 heuristics scores as a table: | # | Heuristic | Score | Key Issue | |---|-----------|-------|-----------| -| 1 | Visibility of System Status | ? | [specific finding or "--" if solid] | +| 1 | Visibility of System Status | ? | [specific finding or "n/a" if solid] | | 2 | Match System / Real World | ? | | | 3 | User Control and Freedom | ? | | | 4 | Consistency and Standards | ? | | @@ -116,7 +116,7 @@ Present the Nielsen's 10 heuristics scores as a table: | 10 | Help and Documentation | ? | | | **Total** | | **??/40** | **[Rating band]** | -Be honest with scores. A 4 means genuinely excellent. Most real interfaces score 20--32. +Be honest with scores. A 4 means genuinely excellent. Most real interfaces score 20-32. #### Anti-Patterns Verdict @@ -129,24 +129,24 @@ Be honest with scores. A 4 means genuinely excellent. Most real interfaces score **Visual overlays** (if browser was used): Tell the user that overlays are now visible in the **[Human]** tab in their browser, highlighting the detected issues. Summarize what the console output reported. #### Overall Impression -A brief gut reaction -- what works, what doesn't, and the single biggest opportunity. +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. +Highlight 2-3 things done well. Be specific about why they work. #### Priority Issues -The 3--5 most impactful design problems, ordered by importance. +The 3-5 most impactful design problems, ordered by importance. -For each issue, tag with **P0--P3 severity** (consult [heuristics-scoring](reference/heuristics-scoring.md) for severity definitions): +For each issue, tag with **P0-P3 severity** (consult [heuristics-scoring](reference/heuristics-scoring.md) for severity definitions): - **[P?] What**: Name the problem clearly - **Why it matters**: How this hurts users or undermines goals - **Fix**: What to do about it (be concrete) -- **Suggested command**: Which command could address this (from: /animate, /validate, /quieter, /craft, /optimize, /adapt, /clarify, /distill, /delight, /onboard, /normalize, /audit, /harden, /polish, /extract, /bolder, /arrange, /typeset, /critique, /colorize, /overdrive) +- **Suggested command**: Which command could address this (from: /animate, /validate, /quieter, /shape, /optimize, /adapt, /clarify, /distill, /delight, /onboard, /normalize, /audit, /harden, /polish, /extract, /bolder, /arrange, /typeset, /critique, /colorize, /overdrive) #### Persona Red Flags > *Consult [personas](reference/personas.md)* -Auto-select 2--3 personas most relevant to this interface type (use the selection table in the reference). If `.kiro/settings.json` contains a `## Design Context` section from `impeccable teach`, also generate 1--2 project-specific personas from the audience/brand info. +Auto-select 2-3 personas most relevant to this interface type (use the selection table in the reference). If `.kiro/settings.json` contains a `## Design Context` section from `impeccable teach`, also generate 1-2 project-specific personas from the audience/brand info. For each selected persona, walk through the primary user action and list specific red flags found: @@ -154,7 +154,7 @@ For each selected persona, walk through the primary user action and list specifi **Jordan (First-Timer)**: Icon-only nav in sidebar. Technical jargon in error messages ("404 Not Found"). No visible help. Will abandon at step 2. -Be specific -- name the exact elements and interactions that fail each persona. Don't write generic persona descriptions; write what broke for them. +Be specific. Name the exact elements and interactions that fail each persona. Don't write generic persona descriptions; write what broke for them. #### Minor Observations Quick notes on smaller issues worth addressing. @@ -166,32 +166,32 @@ Provocative questions that might unlock better solutions: - "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 +- 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 +- Prioritize ruthlessly. If everything is important, nothing is. +- Don't soften criticism. Developers need honest feedback to ship great design. ### Step 4: Ask the User **After presenting findings**, use targeted questions based on what was actually found. ask the user directly to clarify what you cannot infer. These answers will shape the action plan. -Ask questions along these lines (adapt to the specific findings -- do NOT ask generic questions): +Ask questions along these lines (adapt to the specific findings; do NOT ask generic questions): -1. **Priority direction**: Based on the issues found, ask which category matters most to the user right now. For example: "I found problems with visual hierarchy, color usage, and information overload. Which area should we tackle first?" Offer the top 2--3 issue categories as options. +1. **Priority direction**: Based on the issues found, ask which category matters most to the user right now. For example: "I found problems with visual hierarchy, color usage, and information overload. Which area should we tackle first?" Offer the top 2-3 issue categories as options. -2. **Design intent**: If the critique found a tonal mismatch, ask whether it was intentional. For example: "The interface feels clinical and corporate. Is that the intended tone, or should it feel warmer/bolder/more playful?" Offer 2--3 tonal directions as options based on what would fix the issues found. +2. **Design intent**: If the critique found a tonal mismatch, ask whether it was intentional. For example: "The interface feels clinical and corporate. Is that the intended tone, or should it feel warmer/bolder/more playful?" Offer 2-3 tonal directions as options based on what would fix the issues found. 3. **Scope**: Ask how much the user wants to take on. For example: "I found N issues. Want to address everything, or focus on the top 3?" Offer scope options like "Top 3 only", "All issues", "Critical issues only". -4. **Constraints** (optional -- only ask if relevant): If the findings touch many areas, ask if anything is off-limits. For example: "Should any sections stay as-is?" This prevents the plan from touching things the user considers done. +4. **Constraints** (optional; only ask if relevant): If the findings touch many areas, ask if anything is off-limits. For example: "Should any sections stay as-is?" This prevents the plan from touching things the user considers done. **Rules for questions**: -- Every question must reference specific findings from the report -- never ask generic "who is your audience?" questions -- Keep it to 2--4 questions maximum -- respect the user's time -- Offer concrete options, not open-ended prompts -- If findings are straightforward (e.g., only 1--2 clear issues), skip questions and go directly to Step 5 +- Every question must reference specific findings from the report. Never ask generic "who is your audience?" questions. +- Keep it to 2-4 questions maximum. Respect the user's time. +- Offer concrete options, not open-ended prompts. +- If findings are straightforward (e.g., only 1-2 clear issues), skip questions and go directly to Step 5. ### Step 5: Recommended Actions @@ -201,12 +201,12 @@ Ask questions along these lines (adapt to the specific findings -- do NOT ask ge List recommended commands in priority order, based on the user's answers: -1. **`/command-name`** -- Brief description of what to fix (specific context from critique findings) -2. **`/command-name`** -- Brief description (specific context) +1. **`/command-name`**: Brief description of what to fix (specific context from critique findings) +2. **`/command-name`**: Brief description (specific context) ... **Rules for recommendations**: -- Only recommend commands from: /animate, /validate, /quieter, /craft, /optimize, /adapt, /clarify, /distill, /delight, /onboard, /normalize, /audit, /harden, /polish, /extract, /bolder, /arrange, /typeset, /critique, /colorize, /overdrive +- Only recommend commands from: /animate, /validate, /quieter, /shape, /optimize, /adapt, /clarify, /distill, /delight, /onboard, /normalize, /audit, /harden, /polish, /extract, /bolder, /arrange, /typeset, /critique, /colorize, /overdrive - Order by the user's stated priorities first, then by impact - Each item's description should carry enough context that the command knows what to focus on - Map each Priority Issue to the appropriate command diff --git a/.kiro/skills/impeccable/SKILL.md b/.kiro/skills/impeccable/SKILL.md index 43c688767..a1ee415de 100644 --- a/.kiro/skills/impeccable/SKILL.md +++ b/.kiro/skills/impeccable/SKILL.md @@ -1,6 +1,6 @@ --- name: impeccable -description: Create distinctive, production-grade frontend interfaces with high design quality. Generates creative, polished code that avoids generic AI aesthetics. Use when the user asks to build web components, pages, artifacts, posters, or applications, or when any design skill requires project context. Call with 'teach' argument to run design context setup. +description: Create distinctive, production-grade frontend interfaces with high design quality. Generates creative, polished code that avoids generic AI aesthetics. Use when the user asks to build web components, pages, artifacts, posters, or applications, or when any design skill requires project context. Call with 'craft' to run the full shape-then-build flow, or 'teach' for design context setup. license: Apache 2.0. Based on Anthropic's frontend-design skill. See NOTICE.md for attribution. --- @@ -148,6 +148,12 @@ Remember: Claude is capable of extraordinary creative work. Don't hold back. Sho --- +## Craft Mode + +If this skill is invoked with the argument "craft" (e.g., `/impeccable craft [feature description]`), follow the [craft flow](reference/craft.md). Pass any additional arguments as the feature description. + +--- + ## Teach Mode If this skill is invoked with the argument "teach" (e.g., `/impeccable teach`), skip all design work above and instead run the teach flow below. This is a one-time setup that gathers design context for the project. diff --git a/.kiro/skills/impeccable/reference/craft.md b/.kiro/skills/impeccable/reference/craft.md new file mode 100644 index 000000000..d2961057f --- /dev/null +++ b/.kiro/skills/impeccable/reference/craft.md @@ -0,0 +1,70 @@ +# Craft Flow + +Build a feature with impeccable UX and UI quality through a structured process: shape the design, load the right references, then build and iterate visually until the result is delightful. + +## Step 1: Shape the Design + +Run /shape, passing along whatever feature description the user provided. + +Wait for the design brief to be fully confirmed before proceeding. The brief is your blueprint, and every implementation decision should trace back to it. + +If the user has already run /shape and has a confirmed design brief, skip this step and use the existing brief. + +## Step 2: Load References + +Based on the design brief's "Recommended References" section, consult the relevant impeccable reference files. At minimum, always consult: + +- [spatial-design.md](spatial-design.md) for layout and spacing +- [typography.md](typography.md) for type hierarchy + +Then add references based on the brief's needs: +- Complex interactions or forms? Consult [interaction-design.md](interaction-design.md) +- Animation or transitions? Consult [motion-design.md](motion-design.md) +- Color-heavy or themed? Consult [color-and-contrast.md](color-and-contrast.md) +- Responsive requirements? Consult [responsive-design.md](responsive-design.md) +- Heavy on copy, labels, or errors? Consult [ux-writing.md](ux-writing.md) + +## Step 3: Build + +Implement the feature following the design brief. Work in this order: + +1. **Structure first**: HTML/semantic structure for the primary state. No styling yet. +2. **Layout and spacing**: Establish the spatial rhythm and visual hierarchy. +3. **Typography and color**: Apply the type scale and color system. +4. **Interactive states**: Hover, focus, active, disabled. +5. **Edge case states**: Empty, loading, error, overflow, first-run. +6. **Motion**: Purposeful transitions and animations (if appropriate). +7. **Responsive**: Adapt for different viewports. Don't just shrink; redesign for the context. + +### During Build +- Test with real (or realistic) data at every step, not placeholder text +- Check each state as you build it, not all at the end +- If you discover a design question, stop and ask rather than guessing +- Every visual choice should trace back to something in the design brief + +## Step 4: Visual Iteration + +**This step is critical.** Do not stop after the first implementation pass. + +Open the result in a browser window. If browser automation tools are available, use them to navigate to the page and visually inspect the result. If not, ask the user to open it and provide feedback. + +Iterate through these checks visually: + +1. **Does it match the brief?** Compare the live result against every section of the design brief. Fix discrepancies. +2. **Does it pass the AI slop test?** If someone saw this and said "AI made this," would they believe it immediately? If yes, it needs more design intention. +3. **Run /validate.** Fix any P0 or P1 issues. +4. **Check every state.** Navigate through empty, error, loading, and edge case states. Each one should feel intentional, not like an afterthought. +5. **Check responsive.** Resize the viewport. Does it adapt well or just shrink? +6. **Check the details.** Spacing consistency, type hierarchy clarity, color contrast, interactive feedback, motion timing. + +After each round of fixes, visually verify again. **Repeat until you would be proud to show this to the user.** The bar is not "it works"; the bar is "this delights." + +## Step 5: Present + +Present the result to the user: +- Show the feature in its primary state +- Walk through the key states (empty, error, responsive) +- Explain design decisions that connect back to the design brief +- Ask: "What's working? What isn't?" + +Iterate based on feedback. Good design is rarely right on the first pass. diff --git a/.kiro/skills/shape/SKILL.md b/.kiro/skills/shape/SKILL.md new file mode 100644 index 000000000..7e520562f --- /dev/null +++ b/.kiro/skills/shape/SKILL.md @@ -0,0 +1,93 @@ +--- +name: shape +description: Plan the UX and UI for a feature before writing code. Runs a structured discovery interview, then produces a design brief that guides implementation. Use during the planning phase to establish design direction, constraints, and strategy before any code is written. +--- + +## MANDATORY PREPARATION + +Invoke /impeccable, which contains design principles, anti-patterns, and the **Context Gathering Protocol**. Follow the protocol before proceeding. If no design context exists yet, you MUST run /impeccable teach first. + +--- + +Shape the UX and UI for a feature before any code is written. This skill produces a **design brief**: a structured artifact that guides implementation through discovery, not guesswork. + +**Scope**: Design planning only. This skill does NOT write code. It produces the thinking that makes code good. + +**Output**: A design brief that can be handed off to /impeccable craft, /impeccable, or any other implementation skill. + +## Philosophy + +Most AI-generated UIs fail not because of bad code, but because of skipped thinking. They jump to "here's a card grid" without asking "what is the user trying to accomplish?" This skill inverts that: understand deeply first, so implementation is precise. + +## Phase 1: Discovery Interview + +**Do NOT write any code or make any design decisions during this phase.** Your only job is to understand the feature deeply enough to make excellent design decisions later. + +Ask these questions in conversation, adapting based on answers. Don't dump them all at once; have a natural dialogue. ask the user directly to clarify what you cannot infer. + +### Purpose & Context +- What is this feature for? What problem does it solve? +- Who specifically will use it? (Not "users"; be specific: role, context, frequency) +- What does success look like? How will you know this feature is working? +- What's the user's state of mind when they reach this feature? (Rushed? Exploring? Anxious? Focused?) + +### Content & Data +- What content or data does this feature display or collect? +- What are the realistic ranges? (Minimum, typical, maximum, e.g., 0 items, 5 items, 500 items) +- What are the edge cases? (Empty state, error state, first-time use, power user) +- Is any content dynamic? What changes and how often? + +### Design Goals +- What's the single most important thing a user should do or understand here? +- What should this feel like? (Fast/efficient? Calm/trustworthy? Fun/playful? Premium/refined?) +- Are there existing patterns in the product this should be consistent with? +- Are there specific examples (inside or outside the product) that capture what you're going for? + +### Constraints +- Are there technical constraints? (Framework, performance budget, browser support) +- Are there content constraints? (Localization, dynamic text length, user-generated content) +- Mobile/responsive requirements? +- Accessibility requirements beyond WCAG AA? + +### Anti-Goals +- What should this NOT be? What would be a wrong direction? +- What's the biggest risk of getting this wrong? + +## Phase 2: Design Brief + +After the interview, synthesize everything into a structured design brief. Present it to the user for confirmation before considering this skill complete. + +### Brief Structure + +**1. Feature Summary** (2-3 sentences) +What this is, who it's for, what it needs to accomplish. + +**2. Primary User Action** +The single most important thing a user should do or understand here. + +**3. Design Direction** +How this should feel. What aesthetic approach fits. Reference the project's design context from `.impeccable.md` and explain how this feature should express it. + +**4. Layout Strategy** +High-level spatial approach: what gets emphasis, what's secondary, how information flows. Describe the visual hierarchy and rhythm, not specific CSS. + +**5. Key States** +List every state the feature needs: default, empty, loading, error, success, edge cases. For each, note what the user needs to see and feel. + +**6. Interaction Model** +How users interact with this feature. What happens on click, hover, scroll? What feedback do they get? What's the flow from entry to completion? + +**7. Content Requirements** +What copy, labels, empty state messages, error messages, and microcopy are needed. Note any dynamic content and its realistic ranges. + +**8. Recommended References** +Based on the brief, list which impeccable reference files would be most valuable during implementation (e.g., spatial-design.md for complex layouts, motion-design.md for animated features, interaction-design.md for form-heavy features). + +**9. Open Questions** +Anything unresolved that the implementer should resolve during build. + +--- + +ask the user directly to clarify what you cannot infer. Get explicit confirmation of the brief before finishing. If the user disagrees with any part, revisit the relevant discovery questions. + +Once confirmed, the brief is complete. The user can now hand it to /impeccable craft to build the feature, or use it to guide any other implementation approach. \ No newline at end of file diff --git a/.kiro/skills/validate/SKILL.md b/.kiro/skills/validate/SKILL.md index f711dcb7c..b4c183888 100644 --- a/.kiro/skills/validate/SKILL.md +++ b/.kiro/skills/validate/SKILL.md @@ -5,11 +5,11 @@ description: Fast visual validation after UX/UI changes. Checks anti-patterns, s ## MANDATORY PREPARATION -Invoke /impeccable -- it contains design principles, anti-patterns, and the **Context Gathering Protocol**. Follow the protocol before proceeding -- if no design context exists yet, you MUST run /impeccable teach first. +Invoke /impeccable, which contains design principles, anti-patterns, and the **Context Gathering Protocol**. Follow the protocol before proceeding. If no design context exists yet, you MUST run /impeccable teach first. --- -A fast, focused quality gate. Not a full audit or critique -- this is the 2-minute check you run after every UI change to catch the most common and damaging issues before they ship. +A fast, focused quality gate. Not a full audit or critique; this is the 2-minute check you run after every UI change to catch the most common and damaging issues before they ship. Think of this as a design linter: opinionated, fast, and actionable. Flag what's wrong, say how to fix it, move on. @@ -69,10 +69,10 @@ Check against ALL **DON'T** guidelines in the impeccable skill. The most common Report findings as a flat list, grouped by severity: **Severity levels:** -- **P0 -- Broken**: Visually broken, inaccessible, or fundamentally wrong. Fix before shipping. -- **P1 -- Anti-pattern**: Clear design anti-pattern that undermines quality. Fix now. -- **P2 -- Inconsistency**: Spacing, token, or style drift from the design system. Fix soon. -- **P3 -- Polish**: Minor refinement opportunity. Fix if time allows. +- **P0 (Broken)**: Visually broken, inaccessible, or fundamentally wrong. Fix before shipping. +- **P1 (Anti-pattern)**: Clear design anti-pattern that undermines quality. Fix now. +- **P2 (Inconsistency)**: Spacing, token, or style drift from the design system. Fix soon. +- **P3 (Polish)**: Minor refinement opportunity. Fix if time allows. For each finding: ``` @@ -80,7 +80,7 @@ For each finding: → Fix: Concrete action to take (file:line if applicable) ``` -Keep the total list short. If everything looks good, say so -- don't invent issues. +Keep the total list short. If everything looks good, say so. Don't invent issues. ## After Validation diff --git a/.opencode/skills/audit/SKILL.md b/.opencode/skills/audit/SKILL.md index dcabe5eea..fa777e5c0 100644 --- a/.opencode/skills/audit/SKILL.md +++ b/.opencode/skills/audit/SKILL.md @@ -108,7 +108,7 @@ For each issue, document: - **Impact**: How it affects users - **WCAG/Standard**: Which standard it violates (if applicable) - **Recommendation**: How to fix it -- **Suggested command**: Which command to use (prefer: /animate, /validate, /quieter, /craft, /optimize, /adapt, /clarify, /distill, /delight, /onboard, /normalize, /audit, /harden, /polish, /extract, /bolder, /arrange, /typeset, /critique, /colorize, /overdrive) +- **Suggested command**: Which command to use (prefer: /animate, /validate, /quieter, /shape, /optimize, /adapt, /clarify, /distill, /delight, /onboard, /normalize, /audit, /harden, /polish, /extract, /bolder, /arrange, /typeset, /critique, /colorize, /overdrive) ### Patterns & Systemic Issues @@ -127,7 +127,7 @@ List recommended commands in priority order (P0 first, then P1, then P2): 1. **[P?] `/command-name`** — Brief description (specific context from audit findings) 2. **[P?] `/command-name`** — Brief description (specific context) -**Rules**: Only recommend commands from: /animate, /validate, /quieter, /craft, /optimize, /adapt, /clarify, /distill, /delight, /onboard, /normalize, /audit, /harden, /polish, /extract, /bolder, /arrange, /typeset, /critique, /colorize, /overdrive. Map findings to the most appropriate command. End with `/polish` as the final step if any fixes were recommended. +**Rules**: Only recommend commands from: /animate, /validate, /quieter, /shape, /optimize, /adapt, /clarify, /distill, /delight, /onboard, /normalize, /audit, /harden, /polish, /extract, /bolder, /arrange, /typeset, /critique, /colorize, /overdrive. Map findings to the most appropriate command. End with `/polish` as the final step if any fixes were recommended. After presenting the summary, tell the user: diff --git a/.opencode/skills/craft/SKILL.md b/.opencode/skills/craft/SKILL.md deleted file mode 100644 index dac226066..000000000 --- a/.opencode/skills/craft/SKILL.md +++ /dev/null @@ -1,97 +0,0 @@ ---- -name: craft -description: Design and build ideal UX+UI for a feature through guided discovery. Interviews the user about purpose, audience, and design goals before implementing. Use when building a new feature, redesigning an existing one, or when the user wants a thoughtful, user-centered design process rather than jumping straight to code. -user-invocable: true -argument-hint: "[feature to design]" ---- - -## MANDATORY PREPARATION - -Invoke /impeccable -- it contains design principles, anti-patterns, and the **Context Gathering Protocol**. Follow the protocol before proceeding -- if no design context exists yet, you MUST run /impeccable teach first. - ---- - -Build the ideal UX and UI for a feature. This skill is about getting the design RIGHT before writing code -- through structured discovery, not guesswork. - -**Scope**: UX + UI design and implementation. Out of scope: building the underlying business logic, backend, or data layer. If the feature needs backend work, note what's needed but focus on the interface. - -## Philosophy - -Most AI-generated UIs fail not because of bad code, but because of skipped thinking. They jump to "here's a card grid" without asking "what is the user trying to accomplish?" This skill inverts that: understand deeply, then build precisely. - -## Phase 1: Discovery Interview - -**Do NOT write any code during this phase.** Your only job is to understand the feature deeply enough to make excellent design decisions. - -Ask these questions in conversation, adapting based on answers. Don't dump them all at once -- have a natural dialogue. STOP and call the `question` tool to clarify. - -### Purpose & Context -- What is this feature for? What problem does it solve? -- Who specifically will use it? (Not "users" -- be specific: role, context, frequency) -- What does success look like? How will you know this feature is working? -- What's the user's state of mind when they reach this feature? (Rushed? Exploring? Anxious? Focused?) - -### Content & Data -- What content or data does this feature display or collect? -- What are the realistic ranges? (Minimum, typical, maximum -- e.g., 0 items, 5 items, 500 items) -- What are the edge cases? (Empty state, error state, first-time use, power user) -- Is any content dynamic? What changes and how often? - -### Design Goals -- What's the single most important thing a user should do or understand here? -- What should this feel like? (Fast/efficient? Calm/trustworthy? Fun/playful? Premium/refined?) -- Are there existing patterns in the product this should be consistent with? -- Are there specific examples (inside or outside the product) that capture what you're going for? - -### Constraints -- Are there technical constraints? (Framework, performance budget, browser support) -- Are there content constraints? (Localization, dynamic text length, user-generated content) -- Mobile/responsive requirements? -- Accessibility requirements beyond WCAG AA? - -### Anti-Goals -- What should this NOT be? What would be a wrong direction? -- What's the biggest risk of getting this wrong? - -## Phase 2: Design Synthesis - -After the interview, synthesize your understanding before touching code. Present this back to the user for confirmation: - -1. **Feature brief** (2-3 sentences): What this is, who it's for, what it needs to accomplish -2. **Primary user action**: The one thing that matters most -3. **Design direction**: How this should feel, what aesthetic approach fits -4. **Key states**: List every state the feature needs (default, empty, loading, error, success, edge cases) -5. **Open questions**: Anything unresolved that might change the approach - -STOP and call the `question` tool to clarify. -- get explicit confirmation before proceeding. If the user disagrees with your synthesis, revisit the relevant discovery questions. - -## Phase 3: Implementation - -Now build it. Use /impeccable as your design engine -- follow its principles, consult its references, avoid its anti-patterns. - -### Implementation Order -1. **Structure first**: HTML/semantic structure for the primary state. No styling yet. -2. **Layout and spacing**: Establish the spatial rhythm and visual hierarchy. -3. **Typography and color**: Apply the type scale and color system. -4. **Interactive states**: Hover, focus, active, disabled. -5. **Edge case states**: Empty, loading, error, overflow, first-run. -6. **Motion**: Purposeful transitions and animations (if appropriate). -7. **Responsive**: Adapt for different viewports -- don't just shrink, redesign for the context. - -### During Implementation -- Test with real (or realistic) data at every step, not placeholder text -- Check each state as you build it, not all at the end -- If you discover a design question during implementation, stop and ask rather than guessing -- Every visual choice should trace back to something learned in discovery - -## Phase 4: Validation - -After implementation, run /validate on your work. Fix any P0 or P1 issues before presenting to the user. - -Then present the result: -- Show the feature in its primary state -- Walk through the key states (empty, error, responsive) -- Explain design decisions that connect back to what you learned in discovery -- Ask for feedback: "What's working? What isn't?" - -Iterate based on feedback. Good design is rarely right on the first pass. \ No newline at end of file diff --git a/.opencode/skills/critique/SKILL.md b/.opencode/skills/critique/SKILL.md index 87e22f15d..5b02968d4 100644 --- a/.opencode/skills/critique/SKILL.md +++ b/.opencode/skills/critique/SKILL.md @@ -11,21 +11,21 @@ allowed-tools: ### Step 1: Preparation -Invoke /impeccable -- it contains design principles, anti-patterns, and the **Context Gathering Protocol**. Follow the protocol before proceeding -- if no design context exists yet, you MUST run /impeccable teach first. Additionally gather: what the interface is trying to accomplish. +Invoke /impeccable, which contains design principles, anti-patterns, and the **Context Gathering Protocol**. Follow the protocol before proceeding. If no design context exists yet, you MUST run /impeccable teach first. Additionally gather: what the interface is trying to accomplish. ### Step 2: Gather Assessments Launch two independent assessments. **Neither must see the other's output** to avoid bias. -You SHOULD delegate each assessment to a separate sub-agent for independence. Use your environment's agent spawning mechanism -- e.g., Claude Code's `Agent` tool, or Codex's subagent spawning ("spawn two agents in parallel"). Sub-agents should return their findings as structured text -- do NOT output findings to the user yet. +You SHOULD delegate each assessment to a separate sub-agent for independence. Use your environment's agent spawning mechanism (e.g., Claude Code's `Agent` tool, or Codex's subagent spawning). Sub-agents should return their findings as structured text. Do NOT output findings to the user yet. If sub-agents are not available in the current environment, complete each assessment sequentially, writing findings to internal notes before proceeding. -**Tab isolation**: When browser automation is available, each assessment MUST create its own new tab -- never reuse an existing tab, even if one is already open at the correct URL. This prevents the two assessments from interfering with each other's page state. +**Tab isolation**: When browser automation is available, each assessment MUST create its own new tab. Never reuse an existing tab, even if one is already open at the correct URL. This prevents the two assessments from interfering with each other's page state. #### Assessment A: LLM Design Review -Read the relevant source files (HTML, CSS, JS/TS) and, if browser automation is available, visually inspect the live page. **Create a new tab** for this -- do not reuse existing tabs. After navigation, label the tab by setting the document title: +Read the relevant source files (HTML, CSS, JS/TS) and, if browser automation is available, visually inspect the live page. **Create a new tab** for this; do not reuse existing tabs. After navigation, label the tab by setting the document title: ```javascript document.title = '[LLM] ' + document.title; ``` @@ -36,8 +36,8 @@ Think like a design director. Evaluate: **Holistic Design Review**: 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). **Cognitive Load** (consult [cognitive-load](reference/cognitive-load.md)): -- Run the 8-item cognitive load checklist. Report failure count: 0--1 = low (good), 2--3 = moderate, 4+ = critical. -- Count visible options at each decision point -- if >4, flag it. +- Run the 8-item cognitive load checklist. Report failure count: 0-1 = low (good), 2-3 = moderate, 4+ = critical. +- Count visible options at each decision point. If >4, flag it. - Check for progressive disclosure: is complexity revealed only when needed? **Emotional Journey**: @@ -46,9 +46,9 @@ Think like a design director. Evaluate: - **Emotional valleys**: Check for anxiety spikes at high-stakes moments (payment, delete, commit). Are there design interventions (progress indicators, reassurance copy, undo options)? **Nielsen's Heuristics** (consult [heuristics-scoring](reference/heuristics-scoring.md)): -Score each of the 10 heuristics 0--4. This scoring will be presented in the report. +Score each of the 10 heuristics 0-4. This scoring will be presented in the report. -Return structured findings covering: AI slop verdict, heuristic scores, cognitive load assessment, what's working (2--3 items), priority issues (3--5 with what/why/fix), minor observations, and provocative questions. +Return structured findings covering: AI slop verdict, heuristic scores, cognitive load assessment, what's working (2-3 items), priority issues (3-5 with what/why/fix), minor observations, and provocative questions. #### Assessment B: Automated Detection @@ -67,37 +67,37 @@ npx impeccable --json [--fast] [target] **Browser visualization** (when browser automation tools are available AND the target is a viewable page): -The overlay is a **visual aid for the user** -- it highlights issues directly in their browser. Do NOT scroll through the page to screenshot overlays. Instead, read the console output to get the results programmatically. +The overlay is a **visual aid for the user**. It highlights issues directly in their browser. Do NOT scroll through the page to screenshot overlays. Instead, read the console output to get the results programmatically. 1. **Start the live detection server**: ```bash npx impeccable live & ``` Note the port printed to stdout (auto-assigned). Use `--port=PORT` to fix it. -2. **Create a new tab** and navigate to the page (use dev server URL for local files, or direct URL) -- do not reuse existing tabs +2. **Create a new tab** and navigate to the page (use dev server URL for local files, or direct URL). Do not reuse existing tabs. 3. **Label the tab** via `javascript_tool` so the user can distinguish it: ```javascript document.title = '[Human] ' + document.title; ``` -4. **Scroll to top** -- ensure the page is scrolled to the very top before injection +4. **Scroll to top** to ensure the page is scrolled to the very top before injection 5. **Inject** via `javascript_tool` (replace PORT with the port from step 1): ```javascript const s = document.createElement('script'); s.src = 'http://localhost:PORT/detect.js'; document.head.appendChild(s); ``` -6. Wait 2--3 seconds for the detector to render overlays -7. **Read results from console** using `read_console_messages` with pattern `impeccable` -- the detector logs all findings with the `[impeccable]` prefix. Do NOT scroll through the page to take screenshots of the overlays. +6. Wait 2-3 seconds for the detector to render overlays +7. **Read results from console** using `read_console_messages` with pattern `impeccable`. The detector logs all findings with the `[impeccable]` prefix. Do NOT scroll through the page to take screenshots of the overlays. 8. **Cleanup**: Stop the live server when done: ```bash npx impeccable live stop ``` -For multi-view targets, inject on 3--5 representative pages. If injection fails, continue with CLI results only. +For multi-view targets, inject on 3-5 representative pages. If injection fails, continue with CLI results only. Return: CLI findings (JSON), browser console findings (if applicable), and any false positives noted. ### Step 3: Generate Combined Critique Report -Synthesize both assessments into a single report. Do NOT simply concatenate -- weave the findings together, noting where the LLM review and detector agree, where the detector caught issues the LLM missed, and where detector findings are false positives. +Synthesize both assessments into a single report. Do NOT simply concatenate. Weave the findings together, noting where the LLM review and detector agree, where the detector caught issues the LLM missed, and where detector findings are false positives. Structure your feedback as a design director would: @@ -108,7 +108,7 @@ Present the Nielsen's 10 heuristics scores as a table: | # | Heuristic | Score | Key Issue | |---|-----------|-------|-----------| -| 1 | Visibility of System Status | ? | [specific finding or "--" if solid] | +| 1 | Visibility of System Status | ? | [specific finding or "n/a" if solid] | | 2 | Match System / Real World | ? | | | 3 | User Control and Freedom | ? | | | 4 | Consistency and Standards | ? | | @@ -120,7 +120,7 @@ Present the Nielsen's 10 heuristics scores as a table: | 10 | Help and Documentation | ? | | | **Total** | | **??/40** | **[Rating band]** | -Be honest with scores. A 4 means genuinely excellent. Most real interfaces score 20--32. +Be honest with scores. A 4 means genuinely excellent. Most real interfaces score 20-32. #### Anti-Patterns Verdict @@ -133,24 +133,24 @@ Be honest with scores. A 4 means genuinely excellent. Most real interfaces score **Visual overlays** (if browser was used): Tell the user that overlays are now visible in the **[Human]** tab in their browser, highlighting the detected issues. Summarize what the console output reported. #### Overall Impression -A brief gut reaction -- what works, what doesn't, and the single biggest opportunity. +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. +Highlight 2-3 things done well. Be specific about why they work. #### Priority Issues -The 3--5 most impactful design problems, ordered by importance. +The 3-5 most impactful design problems, ordered by importance. -For each issue, tag with **P0--P3 severity** (consult [heuristics-scoring](reference/heuristics-scoring.md) for severity definitions): +For each issue, tag with **P0-P3 severity** (consult [heuristics-scoring](reference/heuristics-scoring.md) for severity definitions): - **[P?] What**: Name the problem clearly - **Why it matters**: How this hurts users or undermines goals - **Fix**: What to do about it (be concrete) -- **Suggested command**: Which command could address this (from: /animate, /validate, /quieter, /craft, /optimize, /adapt, /clarify, /distill, /delight, /onboard, /normalize, /audit, /harden, /polish, /extract, /bolder, /arrange, /typeset, /critique, /colorize, /overdrive) +- **Suggested command**: Which command could address this (from: /animate, /validate, /quieter, /shape, /optimize, /adapt, /clarify, /distill, /delight, /onboard, /normalize, /audit, /harden, /polish, /extract, /bolder, /arrange, /typeset, /critique, /colorize, /overdrive) #### Persona Red Flags > *Consult [personas](reference/personas.md)* -Auto-select 2--3 personas most relevant to this interface type (use the selection table in the reference). If `AGENTS.md` contains a `## Design Context` section from `impeccable teach`, also generate 1--2 project-specific personas from the audience/brand info. +Auto-select 2-3 personas most relevant to this interface type (use the selection table in the reference). If `AGENTS.md` contains a `## Design Context` section from `impeccable teach`, also generate 1-2 project-specific personas from the audience/brand info. For each selected persona, walk through the primary user action and list specific red flags found: @@ -158,7 +158,7 @@ For each selected persona, walk through the primary user action and list specifi **Jordan (First-Timer)**: Icon-only nav in sidebar. Technical jargon in error messages ("404 Not Found"). No visible help. Will abandon at step 2. -Be specific -- name the exact elements and interactions that fail each persona. Don't write generic persona descriptions; write what broke for them. +Be specific. Name the exact elements and interactions that fail each persona. Don't write generic persona descriptions; write what broke for them. #### Minor Observations Quick notes on smaller issues worth addressing. @@ -170,32 +170,32 @@ Provocative questions that might unlock better solutions: - "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 +- 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 +- Prioritize ruthlessly. If everything is important, nothing is. +- Don't soften criticism. Developers need honest feedback to ship great design. ### Step 4: Ask the User **After presenting findings**, use targeted questions based on what was actually found. STOP and call the `question` tool to clarify. These answers will shape the action plan. -Ask questions along these lines (adapt to the specific findings -- do NOT ask generic questions): +Ask questions along these lines (adapt to the specific findings; do NOT ask generic questions): -1. **Priority direction**: Based on the issues found, ask which category matters most to the user right now. For example: "I found problems with visual hierarchy, color usage, and information overload. Which area should we tackle first?" Offer the top 2--3 issue categories as options. +1. **Priority direction**: Based on the issues found, ask which category matters most to the user right now. For example: "I found problems with visual hierarchy, color usage, and information overload. Which area should we tackle first?" Offer the top 2-3 issue categories as options. -2. **Design intent**: If the critique found a tonal mismatch, ask whether it was intentional. For example: "The interface feels clinical and corporate. Is that the intended tone, or should it feel warmer/bolder/more playful?" Offer 2--3 tonal directions as options based on what would fix the issues found. +2. **Design intent**: If the critique found a tonal mismatch, ask whether it was intentional. For example: "The interface feels clinical and corporate. Is that the intended tone, or should it feel warmer/bolder/more playful?" Offer 2-3 tonal directions as options based on what would fix the issues found. 3. **Scope**: Ask how much the user wants to take on. For example: "I found N issues. Want to address everything, or focus on the top 3?" Offer scope options like "Top 3 only", "All issues", "Critical issues only". -4. **Constraints** (optional -- only ask if relevant): If the findings touch many areas, ask if anything is off-limits. For example: "Should any sections stay as-is?" This prevents the plan from touching things the user considers done. +4. **Constraints** (optional; only ask if relevant): If the findings touch many areas, ask if anything is off-limits. For example: "Should any sections stay as-is?" This prevents the plan from touching things the user considers done. **Rules for questions**: -- Every question must reference specific findings from the report -- never ask generic "who is your audience?" questions -- Keep it to 2--4 questions maximum -- respect the user's time -- Offer concrete options, not open-ended prompts -- If findings are straightforward (e.g., only 1--2 clear issues), skip questions and go directly to Step 5 +- Every question must reference specific findings from the report. Never ask generic "who is your audience?" questions. +- Keep it to 2-4 questions maximum. Respect the user's time. +- Offer concrete options, not open-ended prompts. +- If findings are straightforward (e.g., only 1-2 clear issues), skip questions and go directly to Step 5. ### Step 5: Recommended Actions @@ -205,12 +205,12 @@ Ask questions along these lines (adapt to the specific findings -- do NOT ask ge List recommended commands in priority order, based on the user's answers: -1. **`/command-name`** -- Brief description of what to fix (specific context from critique findings) -2. **`/command-name`** -- Brief description (specific context) +1. **`/command-name`**: Brief description of what to fix (specific context from critique findings) +2. **`/command-name`**: Brief description (specific context) ... **Rules for recommendations**: -- Only recommend commands from: /animate, /validate, /quieter, /craft, /optimize, /adapt, /clarify, /distill, /delight, /onboard, /normalize, /audit, /harden, /polish, /extract, /bolder, /arrange, /typeset, /critique, /colorize, /overdrive +- Only recommend commands from: /animate, /validate, /quieter, /shape, /optimize, /adapt, /clarify, /distill, /delight, /onboard, /normalize, /audit, /harden, /polish, /extract, /bolder, /arrange, /typeset, /critique, /colorize, /overdrive - Order by the user's stated priorities first, then by impact - Each item's description should carry enough context that the command knows what to focus on - Map each Priority Issue to the appropriate command diff --git a/.opencode/skills/impeccable/SKILL.md b/.opencode/skills/impeccable/SKILL.md index 3deb5092f..654297077 100644 --- a/.opencode/skills/impeccable/SKILL.md +++ b/.opencode/skills/impeccable/SKILL.md @@ -1,8 +1,8 @@ --- name: impeccable -description: Create distinctive, production-grade frontend interfaces with high design quality. Generates creative, polished code that avoids generic AI aesthetics. Use when the user asks to build web components, pages, artifacts, posters, or applications, or when any design skill requires project context. Call with 'teach' argument to run design context setup. +description: Create distinctive, production-grade frontend interfaces with high design quality. Generates creative, polished code that avoids generic AI aesthetics. Use when the user asks to build web components, pages, artifacts, posters, or applications, or when any design skill requires project context. Call with 'craft' to run the full shape-then-build flow, or 'teach' for design context setup. user-invocable: true -argument-hint: "[teach]" +argument-hint: "[craft|teach]" license: Apache 2.0. Based on Anthropic's frontend-design skill. See NOTICE.md for attribution. --- @@ -150,6 +150,12 @@ Remember: Claude is capable of extraordinary creative work. Don't hold back. Sho --- +## Craft Mode + +If this skill is invoked with the argument "craft" (e.g., `/impeccable craft [feature description]`), follow the [craft flow](reference/craft.md). Pass any additional arguments as the feature description. + +--- + ## Teach Mode If this skill is invoked with the argument "teach" (e.g., `/impeccable teach`), skip all design work above and instead run the teach flow below. This is a one-time setup that gathers design context for the project. diff --git a/.opencode/skills/impeccable/reference/craft.md b/.opencode/skills/impeccable/reference/craft.md new file mode 100644 index 000000000..d2961057f --- /dev/null +++ b/.opencode/skills/impeccable/reference/craft.md @@ -0,0 +1,70 @@ +# Craft Flow + +Build a feature with impeccable UX and UI quality through a structured process: shape the design, load the right references, then build and iterate visually until the result is delightful. + +## Step 1: Shape the Design + +Run /shape, passing along whatever feature description the user provided. + +Wait for the design brief to be fully confirmed before proceeding. The brief is your blueprint, and every implementation decision should trace back to it. + +If the user has already run /shape and has a confirmed design brief, skip this step and use the existing brief. + +## Step 2: Load References + +Based on the design brief's "Recommended References" section, consult the relevant impeccable reference files. At minimum, always consult: + +- [spatial-design.md](spatial-design.md) for layout and spacing +- [typography.md](typography.md) for type hierarchy + +Then add references based on the brief's needs: +- Complex interactions or forms? Consult [interaction-design.md](interaction-design.md) +- Animation or transitions? Consult [motion-design.md](motion-design.md) +- Color-heavy or themed? Consult [color-and-contrast.md](color-and-contrast.md) +- Responsive requirements? Consult [responsive-design.md](responsive-design.md) +- Heavy on copy, labels, or errors? Consult [ux-writing.md](ux-writing.md) + +## Step 3: Build + +Implement the feature following the design brief. Work in this order: + +1. **Structure first**: HTML/semantic structure for the primary state. No styling yet. +2. **Layout and spacing**: Establish the spatial rhythm and visual hierarchy. +3. **Typography and color**: Apply the type scale and color system. +4. **Interactive states**: Hover, focus, active, disabled. +5. **Edge case states**: Empty, loading, error, overflow, first-run. +6. **Motion**: Purposeful transitions and animations (if appropriate). +7. **Responsive**: Adapt for different viewports. Don't just shrink; redesign for the context. + +### During Build +- Test with real (or realistic) data at every step, not placeholder text +- Check each state as you build it, not all at the end +- If you discover a design question, stop and ask rather than guessing +- Every visual choice should trace back to something in the design brief + +## Step 4: Visual Iteration + +**This step is critical.** Do not stop after the first implementation pass. + +Open the result in a browser window. If browser automation tools are available, use them to navigate to the page and visually inspect the result. If not, ask the user to open it and provide feedback. + +Iterate through these checks visually: + +1. **Does it match the brief?** Compare the live result against every section of the design brief. Fix discrepancies. +2. **Does it pass the AI slop test?** If someone saw this and said "AI made this," would they believe it immediately? If yes, it needs more design intention. +3. **Run /validate.** Fix any P0 or P1 issues. +4. **Check every state.** Navigate through empty, error, loading, and edge case states. Each one should feel intentional, not like an afterthought. +5. **Check responsive.** Resize the viewport. Does it adapt well or just shrink? +6. **Check the details.** Spacing consistency, type hierarchy clarity, color contrast, interactive feedback, motion timing. + +After each round of fixes, visually verify again. **Repeat until you would be proud to show this to the user.** The bar is not "it works"; the bar is "this delights." + +## Step 5: Present + +Present the result to the user: +- Show the feature in its primary state +- Walk through the key states (empty, error, responsive) +- Explain design decisions that connect back to the design brief +- Ask: "What's working? What isn't?" + +Iterate based on feedback. Good design is rarely right on the first pass. diff --git a/.opencode/skills/shape/SKILL.md b/.opencode/skills/shape/SKILL.md new file mode 100644 index 000000000..f841906a6 --- /dev/null +++ b/.opencode/skills/shape/SKILL.md @@ -0,0 +1,95 @@ +--- +name: shape +description: Plan the UX and UI for a feature before writing code. Runs a structured discovery interview, then produces a design brief that guides implementation. Use during the planning phase to establish design direction, constraints, and strategy before any code is written. +user-invocable: true +argument-hint: "[feature to shape]" +--- + +## MANDATORY PREPARATION + +Invoke /impeccable, which contains design principles, anti-patterns, and the **Context Gathering Protocol**. Follow the protocol before proceeding. If no design context exists yet, you MUST run /impeccable teach first. + +--- + +Shape the UX and UI for a feature before any code is written. This skill produces a **design brief**: a structured artifact that guides implementation through discovery, not guesswork. + +**Scope**: Design planning only. This skill does NOT write code. It produces the thinking that makes code good. + +**Output**: A design brief that can be handed off to /impeccable craft, /impeccable, or any other implementation skill. + +## Philosophy + +Most AI-generated UIs fail not because of bad code, but because of skipped thinking. They jump to "here's a card grid" without asking "what is the user trying to accomplish?" This skill inverts that: understand deeply first, so implementation is precise. + +## Phase 1: Discovery Interview + +**Do NOT write any code or make any design decisions during this phase.** Your only job is to understand the feature deeply enough to make excellent design decisions later. + +Ask these questions in conversation, adapting based on answers. Don't dump them all at once; have a natural dialogue. STOP and call the `question` tool to clarify. + +### Purpose & Context +- What is this feature for? What problem does it solve? +- Who specifically will use it? (Not "users"; be specific: role, context, frequency) +- What does success look like? How will you know this feature is working? +- What's the user's state of mind when they reach this feature? (Rushed? Exploring? Anxious? Focused?) + +### Content & Data +- What content or data does this feature display or collect? +- What are the realistic ranges? (Minimum, typical, maximum, e.g., 0 items, 5 items, 500 items) +- What are the edge cases? (Empty state, error state, first-time use, power user) +- Is any content dynamic? What changes and how often? + +### Design Goals +- What's the single most important thing a user should do or understand here? +- What should this feel like? (Fast/efficient? Calm/trustworthy? Fun/playful? Premium/refined?) +- Are there existing patterns in the product this should be consistent with? +- Are there specific examples (inside or outside the product) that capture what you're going for? + +### Constraints +- Are there technical constraints? (Framework, performance budget, browser support) +- Are there content constraints? (Localization, dynamic text length, user-generated content) +- Mobile/responsive requirements? +- Accessibility requirements beyond WCAG AA? + +### Anti-Goals +- What should this NOT be? What would be a wrong direction? +- What's the biggest risk of getting this wrong? + +## Phase 2: Design Brief + +After the interview, synthesize everything into a structured design brief. Present it to the user for confirmation before considering this skill complete. + +### Brief Structure + +**1. Feature Summary** (2-3 sentences) +What this is, who it's for, what it needs to accomplish. + +**2. Primary User Action** +The single most important thing a user should do or understand here. + +**3. Design Direction** +How this should feel. What aesthetic approach fits. Reference the project's design context from `.impeccable.md` and explain how this feature should express it. + +**4. Layout Strategy** +High-level spatial approach: what gets emphasis, what's secondary, how information flows. Describe the visual hierarchy and rhythm, not specific CSS. + +**5. Key States** +List every state the feature needs: default, empty, loading, error, success, edge cases. For each, note what the user needs to see and feel. + +**6. Interaction Model** +How users interact with this feature. What happens on click, hover, scroll? What feedback do they get? What's the flow from entry to completion? + +**7. Content Requirements** +What copy, labels, empty state messages, error messages, and microcopy are needed. Note any dynamic content and its realistic ranges. + +**8. Recommended References** +Based on the brief, list which impeccable reference files would be most valuable during implementation (e.g., spatial-design.md for complex layouts, motion-design.md for animated features, interaction-design.md for form-heavy features). + +**9. Open Questions** +Anything unresolved that the implementer should resolve during build. + +--- + +STOP and call the `question` tool to clarify. Get explicit confirmation of the brief before finishing. If the user disagrees with any part, revisit the relevant discovery questions. + +Once confirmed, the brief is complete. The user can now hand it to /impeccable craft to build the feature, or use it to guide any other implementation approach. \ No newline at end of file diff --git a/.opencode/skills/validate/SKILL.md b/.opencode/skills/validate/SKILL.md index aeba85a03..c7b6b6433 100644 --- a/.opencode/skills/validate/SKILL.md +++ b/.opencode/skills/validate/SKILL.md @@ -7,11 +7,11 @@ argument-hint: "[area to validate]" ## MANDATORY PREPARATION -Invoke /impeccable -- it contains design principles, anti-patterns, and the **Context Gathering Protocol**. Follow the protocol before proceeding -- if no design context exists yet, you MUST run /impeccable teach first. +Invoke /impeccable, which contains design principles, anti-patterns, and the **Context Gathering Protocol**. Follow the protocol before proceeding. If no design context exists yet, you MUST run /impeccable teach first. --- -A fast, focused quality gate. Not a full audit or critique -- this is the 2-minute check you run after every UI change to catch the most common and damaging issues before they ship. +A fast, focused quality gate. Not a full audit or critique; this is the 2-minute check you run after every UI change to catch the most common and damaging issues before they ship. Think of this as a design linter: opinionated, fast, and actionable. Flag what's wrong, say how to fix it, move on. @@ -71,10 +71,10 @@ Check against ALL **DON'T** guidelines in the impeccable skill. The most common Report findings as a flat list, grouped by severity: **Severity levels:** -- **P0 -- Broken**: Visually broken, inaccessible, or fundamentally wrong. Fix before shipping. -- **P1 -- Anti-pattern**: Clear design anti-pattern that undermines quality. Fix now. -- **P2 -- Inconsistency**: Spacing, token, or style drift from the design system. Fix soon. -- **P3 -- Polish**: Minor refinement opportunity. Fix if time allows. +- **P0 (Broken)**: Visually broken, inaccessible, or fundamentally wrong. Fix before shipping. +- **P1 (Anti-pattern)**: Clear design anti-pattern that undermines quality. Fix now. +- **P2 (Inconsistency)**: Spacing, token, or style drift from the design system. Fix soon. +- **P3 (Polish)**: Minor refinement opportunity. Fix if time allows. For each finding: ``` @@ -82,7 +82,7 @@ For each finding: → Fix: Concrete action to take (file:line if applicable) ``` -Keep the total list short. If everything looks good, say so -- don't invent issues. +Keep the total list short. If everything looks good, say so. Don't invent issues. ## After Validation diff --git a/.pi/skills/audit/SKILL.md b/.pi/skills/audit/SKILL.md index b482d344e..f944d6111 100644 --- a/.pi/skills/audit/SKILL.md +++ b/.pi/skills/audit/SKILL.md @@ -106,7 +106,7 @@ For each issue, document: - **Impact**: How it affects users - **WCAG/Standard**: Which standard it violates (if applicable) - **Recommendation**: How to fix it -- **Suggested command**: Which command to use (prefer: /animate, /validate, /quieter, /craft, /optimize, /adapt, /clarify, /distill, /delight, /onboard, /normalize, /audit, /harden, /polish, /extract, /bolder, /arrange, /typeset, /critique, /colorize, /overdrive) +- **Suggested command**: Which command to use (prefer: /animate, /validate, /quieter, /shape, /optimize, /adapt, /clarify, /distill, /delight, /onboard, /normalize, /audit, /harden, /polish, /extract, /bolder, /arrange, /typeset, /critique, /colorize, /overdrive) ### Patterns & Systemic Issues @@ -125,7 +125,7 @@ List recommended commands in priority order (P0 first, then P1, then P2): 1. **[P?] `/command-name`** — Brief description (specific context from audit findings) 2. **[P?] `/command-name`** — Brief description (specific context) -**Rules**: Only recommend commands from: /animate, /validate, /quieter, /craft, /optimize, /adapt, /clarify, /distill, /delight, /onboard, /normalize, /audit, /harden, /polish, /extract, /bolder, /arrange, /typeset, /critique, /colorize, /overdrive. Map findings to the most appropriate command. End with `/polish` as the final step if any fixes were recommended. +**Rules**: Only recommend commands from: /animate, /validate, /quieter, /shape, /optimize, /adapt, /clarify, /distill, /delight, /onboard, /normalize, /audit, /harden, /polish, /extract, /bolder, /arrange, /typeset, /critique, /colorize, /overdrive. Map findings to the most appropriate command. End with `/polish` as the final step if any fixes were recommended. After presenting the summary, tell the user: diff --git a/.pi/skills/craft/SKILL.md b/.pi/skills/craft/SKILL.md deleted file mode 100644 index 1dde45c9b..000000000 --- a/.pi/skills/craft/SKILL.md +++ /dev/null @@ -1,95 +0,0 @@ ---- -name: craft -description: Design and build ideal UX+UI for a feature through guided discovery. Interviews the user about purpose, audience, and design goals before implementing. Use when building a new feature, redesigning an existing one, or when the user wants a thoughtful, user-centered design process rather than jumping straight to code. ---- - -## MANDATORY PREPARATION - -Invoke /impeccable -- it contains design principles, anti-patterns, and the **Context Gathering Protocol**. Follow the protocol before proceeding -- if no design context exists yet, you MUST run /impeccable teach first. - ---- - -Build the ideal UX and UI for a feature. This skill is about getting the design RIGHT before writing code -- through structured discovery, not guesswork. - -**Scope**: UX + UI design and implementation. Out of scope: building the underlying business logic, backend, or data layer. If the feature needs backend work, note what's needed but focus on the interface. - -## Philosophy - -Most AI-generated UIs fail not because of bad code, but because of skipped thinking. They jump to "here's a card grid" without asking "what is the user trying to accomplish?" This skill inverts that: understand deeply, then build precisely. - -## Phase 1: Discovery Interview - -**Do NOT write any code during this phase.** Your only job is to understand the feature deeply enough to make excellent design decisions. - -Ask these questions in conversation, adapting based on answers. Don't dump them all at once -- have a natural dialogue. ask the user directly to clarify what you cannot infer. - -### Purpose & Context -- What is this feature for? What problem does it solve? -- Who specifically will use it? (Not "users" -- be specific: role, context, frequency) -- What does success look like? How will you know this feature is working? -- What's the user's state of mind when they reach this feature? (Rushed? Exploring? Anxious? Focused?) - -### Content & Data -- What content or data does this feature display or collect? -- What are the realistic ranges? (Minimum, typical, maximum -- e.g., 0 items, 5 items, 500 items) -- What are the edge cases? (Empty state, error state, first-time use, power user) -- Is any content dynamic? What changes and how often? - -### Design Goals -- What's the single most important thing a user should do or understand here? -- What should this feel like? (Fast/efficient? Calm/trustworthy? Fun/playful? Premium/refined?) -- Are there existing patterns in the product this should be consistent with? -- Are there specific examples (inside or outside the product) that capture what you're going for? - -### Constraints -- Are there technical constraints? (Framework, performance budget, browser support) -- Are there content constraints? (Localization, dynamic text length, user-generated content) -- Mobile/responsive requirements? -- Accessibility requirements beyond WCAG AA? - -### Anti-Goals -- What should this NOT be? What would be a wrong direction? -- What's the biggest risk of getting this wrong? - -## Phase 2: Design Synthesis - -After the interview, synthesize your understanding before touching code. Present this back to the user for confirmation: - -1. **Feature brief** (2-3 sentences): What this is, who it's for, what it needs to accomplish -2. **Primary user action**: The one thing that matters most -3. **Design direction**: How this should feel, what aesthetic approach fits -4. **Key states**: List every state the feature needs (default, empty, loading, error, success, edge cases) -5. **Open questions**: Anything unresolved that might change the approach - -ask the user directly to clarify what you cannot infer. -- get explicit confirmation before proceeding. If the user disagrees with your synthesis, revisit the relevant discovery questions. - -## Phase 3: Implementation - -Now build it. Use /impeccable as your design engine -- follow its principles, consult its references, avoid its anti-patterns. - -### Implementation Order -1. **Structure first**: HTML/semantic structure for the primary state. No styling yet. -2. **Layout and spacing**: Establish the spatial rhythm and visual hierarchy. -3. **Typography and color**: Apply the type scale and color system. -4. **Interactive states**: Hover, focus, active, disabled. -5. **Edge case states**: Empty, loading, error, overflow, first-run. -6. **Motion**: Purposeful transitions and animations (if appropriate). -7. **Responsive**: Adapt for different viewports -- don't just shrink, redesign for the context. - -### During Implementation -- Test with real (or realistic) data at every step, not placeholder text -- Check each state as you build it, not all at the end -- If you discover a design question during implementation, stop and ask rather than guessing -- Every visual choice should trace back to something learned in discovery - -## Phase 4: Validation - -After implementation, run /validate on your work. Fix any P0 or P1 issues before presenting to the user. - -Then present the result: -- Show the feature in its primary state -- Walk through the key states (empty, error, responsive) -- Explain design decisions that connect back to what you learned in discovery -- Ask for feedback: "What's working? What isn't?" - -Iterate based on feedback. Good design is rarely right on the first pass. \ No newline at end of file diff --git a/.pi/skills/critique/SKILL.md b/.pi/skills/critique/SKILL.md index 8613500ed..20b81c1c0 100644 --- a/.pi/skills/critique/SKILL.md +++ b/.pi/skills/critique/SKILL.md @@ -9,21 +9,21 @@ allowed-tools: ### Step 1: Preparation -Invoke /impeccable -- it contains design principles, anti-patterns, and the **Context Gathering Protocol**. Follow the protocol before proceeding -- if no design context exists yet, you MUST run /impeccable teach first. Additionally gather: what the interface is trying to accomplish. +Invoke /impeccable, which contains design principles, anti-patterns, and the **Context Gathering Protocol**. Follow the protocol before proceeding. If no design context exists yet, you MUST run /impeccable teach first. Additionally gather: what the interface is trying to accomplish. ### Step 2: Gather Assessments Launch two independent assessments. **Neither must see the other's output** to avoid bias. -You SHOULD delegate each assessment to a separate sub-agent for independence. Use your environment's agent spawning mechanism -- e.g., Claude Code's `Agent` tool, or Codex's subagent spawning ("spawn two agents in parallel"). Sub-agents should return their findings as structured text -- do NOT output findings to the user yet. +You SHOULD delegate each assessment to a separate sub-agent for independence. Use your environment's agent spawning mechanism (e.g., Claude Code's `Agent` tool, or Codex's subagent spawning). Sub-agents should return their findings as structured text. Do NOT output findings to the user yet. If sub-agents are not available in the current environment, complete each assessment sequentially, writing findings to internal notes before proceeding. -**Tab isolation**: When browser automation is available, each assessment MUST create its own new tab -- never reuse an existing tab, even if one is already open at the correct URL. This prevents the two assessments from interfering with each other's page state. +**Tab isolation**: When browser automation is available, each assessment MUST create its own new tab. Never reuse an existing tab, even if one is already open at the correct URL. This prevents the two assessments from interfering with each other's page state. #### Assessment A: LLM Design Review -Read the relevant source files (HTML, CSS, JS/TS) and, if browser automation is available, visually inspect the live page. **Create a new tab** for this -- do not reuse existing tabs. After navigation, label the tab by setting the document title: +Read the relevant source files (HTML, CSS, JS/TS) and, if browser automation is available, visually inspect the live page. **Create a new tab** for this; do not reuse existing tabs. After navigation, label the tab by setting the document title: ```javascript document.title = '[LLM] ' + document.title; ``` @@ -34,8 +34,8 @@ Think like a design director. Evaluate: **Holistic Design Review**: 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). **Cognitive Load** (consult [cognitive-load](reference/cognitive-load.md)): -- Run the 8-item cognitive load checklist. Report failure count: 0--1 = low (good), 2--3 = moderate, 4+ = critical. -- Count visible options at each decision point -- if >4, flag it. +- Run the 8-item cognitive load checklist. Report failure count: 0-1 = low (good), 2-3 = moderate, 4+ = critical. +- Count visible options at each decision point. If >4, flag it. - Check for progressive disclosure: is complexity revealed only when needed? **Emotional Journey**: @@ -44,9 +44,9 @@ Think like a design director. Evaluate: - **Emotional valleys**: Check for anxiety spikes at high-stakes moments (payment, delete, commit). Are there design interventions (progress indicators, reassurance copy, undo options)? **Nielsen's Heuristics** (consult [heuristics-scoring](reference/heuristics-scoring.md)): -Score each of the 10 heuristics 0--4. This scoring will be presented in the report. +Score each of the 10 heuristics 0-4. This scoring will be presented in the report. -Return structured findings covering: AI slop verdict, heuristic scores, cognitive load assessment, what's working (2--3 items), priority issues (3--5 with what/why/fix), minor observations, and provocative questions. +Return structured findings covering: AI slop verdict, heuristic scores, cognitive load assessment, what's working (2-3 items), priority issues (3-5 with what/why/fix), minor observations, and provocative questions. #### Assessment B: Automated Detection @@ -65,37 +65,37 @@ npx impeccable --json [--fast] [target] **Browser visualization** (when browser automation tools are available AND the target is a viewable page): -The overlay is a **visual aid for the user** -- it highlights issues directly in their browser. Do NOT scroll through the page to screenshot overlays. Instead, read the console output to get the results programmatically. +The overlay is a **visual aid for the user**. It highlights issues directly in their browser. Do NOT scroll through the page to screenshot overlays. Instead, read the console output to get the results programmatically. 1. **Start the live detection server**: ```bash npx impeccable live & ``` Note the port printed to stdout (auto-assigned). Use `--port=PORT` to fix it. -2. **Create a new tab** and navigate to the page (use dev server URL for local files, or direct URL) -- do not reuse existing tabs +2. **Create a new tab** and navigate to the page (use dev server URL for local files, or direct URL). Do not reuse existing tabs. 3. **Label the tab** via `javascript_tool` so the user can distinguish it: ```javascript document.title = '[Human] ' + document.title; ``` -4. **Scroll to top** -- ensure the page is scrolled to the very top before injection +4. **Scroll to top** to ensure the page is scrolled to the very top before injection 5. **Inject** via `javascript_tool` (replace PORT with the port from step 1): ```javascript const s = document.createElement('script'); s.src = 'http://localhost:PORT/detect.js'; document.head.appendChild(s); ``` -6. Wait 2--3 seconds for the detector to render overlays -7. **Read results from console** using `read_console_messages` with pattern `impeccable` -- the detector logs all findings with the `[impeccable]` prefix. Do NOT scroll through the page to take screenshots of the overlays. +6. Wait 2-3 seconds for the detector to render overlays +7. **Read results from console** using `read_console_messages` with pattern `impeccable`. The detector logs all findings with the `[impeccable]` prefix. Do NOT scroll through the page to take screenshots of the overlays. 8. **Cleanup**: Stop the live server when done: ```bash npx impeccable live stop ``` -For multi-view targets, inject on 3--5 representative pages. If injection fails, continue with CLI results only. +For multi-view targets, inject on 3-5 representative pages. If injection fails, continue with CLI results only. Return: CLI findings (JSON), browser console findings (if applicable), and any false positives noted. ### Step 3: Generate Combined Critique Report -Synthesize both assessments into a single report. Do NOT simply concatenate -- weave the findings together, noting where the LLM review and detector agree, where the detector caught issues the LLM missed, and where detector findings are false positives. +Synthesize both assessments into a single report. Do NOT simply concatenate. Weave the findings together, noting where the LLM review and detector agree, where the detector caught issues the LLM missed, and where detector findings are false positives. Structure your feedback as a design director would: @@ -106,7 +106,7 @@ Present the Nielsen's 10 heuristics scores as a table: | # | Heuristic | Score | Key Issue | |---|-----------|-------|-----------| -| 1 | Visibility of System Status | ? | [specific finding or "--" if solid] | +| 1 | Visibility of System Status | ? | [specific finding or "n/a" if solid] | | 2 | Match System / Real World | ? | | | 3 | User Control and Freedom | ? | | | 4 | Consistency and Standards | ? | | @@ -118,7 +118,7 @@ Present the Nielsen's 10 heuristics scores as a table: | 10 | Help and Documentation | ? | | | **Total** | | **??/40** | **[Rating band]** | -Be honest with scores. A 4 means genuinely excellent. Most real interfaces score 20--32. +Be honest with scores. A 4 means genuinely excellent. Most real interfaces score 20-32. #### Anti-Patterns Verdict @@ -131,24 +131,24 @@ Be honest with scores. A 4 means genuinely excellent. Most real interfaces score **Visual overlays** (if browser was used): Tell the user that overlays are now visible in the **[Human]** tab in their browser, highlighting the detected issues. Summarize what the console output reported. #### Overall Impression -A brief gut reaction -- what works, what doesn't, and the single biggest opportunity. +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. +Highlight 2-3 things done well. Be specific about why they work. #### Priority Issues -The 3--5 most impactful design problems, ordered by importance. +The 3-5 most impactful design problems, ordered by importance. -For each issue, tag with **P0--P3 severity** (consult [heuristics-scoring](reference/heuristics-scoring.md) for severity definitions): +For each issue, tag with **P0-P3 severity** (consult [heuristics-scoring](reference/heuristics-scoring.md) for severity definitions): - **[P?] What**: Name the problem clearly - **Why it matters**: How this hurts users or undermines goals - **Fix**: What to do about it (be concrete) -- **Suggested command**: Which command could address this (from: /animate, /validate, /quieter, /craft, /optimize, /adapt, /clarify, /distill, /delight, /onboard, /normalize, /audit, /harden, /polish, /extract, /bolder, /arrange, /typeset, /critique, /colorize, /overdrive) +- **Suggested command**: Which command could address this (from: /animate, /validate, /quieter, /shape, /optimize, /adapt, /clarify, /distill, /delight, /onboard, /normalize, /audit, /harden, /polish, /extract, /bolder, /arrange, /typeset, /critique, /colorize, /overdrive) #### Persona Red Flags > *Consult [personas](reference/personas.md)* -Auto-select 2--3 personas most relevant to this interface type (use the selection table in the reference). If `AGENTS.md` contains a `## Design Context` section from `impeccable teach`, also generate 1--2 project-specific personas from the audience/brand info. +Auto-select 2-3 personas most relevant to this interface type (use the selection table in the reference). If `AGENTS.md` contains a `## Design Context` section from `impeccable teach`, also generate 1-2 project-specific personas from the audience/brand info. For each selected persona, walk through the primary user action and list specific red flags found: @@ -156,7 +156,7 @@ For each selected persona, walk through the primary user action and list specifi **Jordan (First-Timer)**: Icon-only nav in sidebar. Technical jargon in error messages ("404 Not Found"). No visible help. Will abandon at step 2. -Be specific -- name the exact elements and interactions that fail each persona. Don't write generic persona descriptions; write what broke for them. +Be specific. Name the exact elements and interactions that fail each persona. Don't write generic persona descriptions; write what broke for them. #### Minor Observations Quick notes on smaller issues worth addressing. @@ -168,32 +168,32 @@ Provocative questions that might unlock better solutions: - "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 +- 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 +- Prioritize ruthlessly. If everything is important, nothing is. +- Don't soften criticism. Developers need honest feedback to ship great design. ### Step 4: Ask the User **After presenting findings**, use targeted questions based on what was actually found. ask the user directly to clarify what you cannot infer. These answers will shape the action plan. -Ask questions along these lines (adapt to the specific findings -- do NOT ask generic questions): +Ask questions along these lines (adapt to the specific findings; do NOT ask generic questions): -1. **Priority direction**: Based on the issues found, ask which category matters most to the user right now. For example: "I found problems with visual hierarchy, color usage, and information overload. Which area should we tackle first?" Offer the top 2--3 issue categories as options. +1. **Priority direction**: Based on the issues found, ask which category matters most to the user right now. For example: "I found problems with visual hierarchy, color usage, and information overload. Which area should we tackle first?" Offer the top 2-3 issue categories as options. -2. **Design intent**: If the critique found a tonal mismatch, ask whether it was intentional. For example: "The interface feels clinical and corporate. Is that the intended tone, or should it feel warmer/bolder/more playful?" Offer 2--3 tonal directions as options based on what would fix the issues found. +2. **Design intent**: If the critique found a tonal mismatch, ask whether it was intentional. For example: "The interface feels clinical and corporate. Is that the intended tone, or should it feel warmer/bolder/more playful?" Offer 2-3 tonal directions as options based on what would fix the issues found. 3. **Scope**: Ask how much the user wants to take on. For example: "I found N issues. Want to address everything, or focus on the top 3?" Offer scope options like "Top 3 only", "All issues", "Critical issues only". -4. **Constraints** (optional -- only ask if relevant): If the findings touch many areas, ask if anything is off-limits. For example: "Should any sections stay as-is?" This prevents the plan from touching things the user considers done. +4. **Constraints** (optional; only ask if relevant): If the findings touch many areas, ask if anything is off-limits. For example: "Should any sections stay as-is?" This prevents the plan from touching things the user considers done. **Rules for questions**: -- Every question must reference specific findings from the report -- never ask generic "who is your audience?" questions -- Keep it to 2--4 questions maximum -- respect the user's time -- Offer concrete options, not open-ended prompts -- If findings are straightforward (e.g., only 1--2 clear issues), skip questions and go directly to Step 5 +- Every question must reference specific findings from the report. Never ask generic "who is your audience?" questions. +- Keep it to 2-4 questions maximum. Respect the user's time. +- Offer concrete options, not open-ended prompts. +- If findings are straightforward (e.g., only 1-2 clear issues), skip questions and go directly to Step 5. ### Step 5: Recommended Actions @@ -203,12 +203,12 @@ Ask questions along these lines (adapt to the specific findings -- do NOT ask ge List recommended commands in priority order, based on the user's answers: -1. **`/command-name`** -- Brief description of what to fix (specific context from critique findings) -2. **`/command-name`** -- Brief description (specific context) +1. **`/command-name`**: Brief description of what to fix (specific context from critique findings) +2. **`/command-name`**: Brief description (specific context) ... **Rules for recommendations**: -- Only recommend commands from: /animate, /validate, /quieter, /craft, /optimize, /adapt, /clarify, /distill, /delight, /onboard, /normalize, /audit, /harden, /polish, /extract, /bolder, /arrange, /typeset, /critique, /colorize, /overdrive +- Only recommend commands from: /animate, /validate, /quieter, /shape, /optimize, /adapt, /clarify, /distill, /delight, /onboard, /normalize, /audit, /harden, /polish, /extract, /bolder, /arrange, /typeset, /critique, /colorize, /overdrive - Order by the user's stated priorities first, then by impact - Each item's description should carry enough context that the command knows what to focus on - Map each Priority Issue to the appropriate command diff --git a/.pi/skills/impeccable/SKILL.md b/.pi/skills/impeccable/SKILL.md index 768198bf7..6811ac2d1 100644 --- a/.pi/skills/impeccable/SKILL.md +++ b/.pi/skills/impeccable/SKILL.md @@ -1,6 +1,6 @@ --- name: impeccable -description: Create distinctive, production-grade frontend interfaces with high design quality. Generates creative, polished code that avoids generic AI aesthetics. Use when the user asks to build web components, pages, artifacts, posters, or applications, or when any design skill requires project context. Call with 'teach' argument to run design context setup. +description: Create distinctive, production-grade frontend interfaces with high design quality. Generates creative, polished code that avoids generic AI aesthetics. Use when the user asks to build web components, pages, artifacts, posters, or applications, or when any design skill requires project context. Call with 'craft' to run the full shape-then-build flow, or 'teach' for design context setup. license: Apache 2.0. Based on Anthropic's frontend-design skill. See NOTICE.md for attribution. --- @@ -148,6 +148,12 @@ Remember: the model is capable of extraordinary creative work. Don't hold back. --- +## Craft Mode + +If this skill is invoked with the argument "craft" (e.g., `/impeccable craft [feature description]`), follow the [craft flow](reference/craft.md). Pass any additional arguments as the feature description. + +--- + ## Teach Mode If this skill is invoked with the argument "teach" (e.g., `/impeccable teach`), skip all design work above and instead run the teach flow below. This is a one-time setup that gathers design context for the project. diff --git a/.pi/skills/impeccable/reference/craft.md b/.pi/skills/impeccable/reference/craft.md new file mode 100644 index 000000000..d2961057f --- /dev/null +++ b/.pi/skills/impeccable/reference/craft.md @@ -0,0 +1,70 @@ +# Craft Flow + +Build a feature with impeccable UX and UI quality through a structured process: shape the design, load the right references, then build and iterate visually until the result is delightful. + +## Step 1: Shape the Design + +Run /shape, passing along whatever feature description the user provided. + +Wait for the design brief to be fully confirmed before proceeding. The brief is your blueprint, and every implementation decision should trace back to it. + +If the user has already run /shape and has a confirmed design brief, skip this step and use the existing brief. + +## Step 2: Load References + +Based on the design brief's "Recommended References" section, consult the relevant impeccable reference files. At minimum, always consult: + +- [spatial-design.md](spatial-design.md) for layout and spacing +- [typography.md](typography.md) for type hierarchy + +Then add references based on the brief's needs: +- Complex interactions or forms? Consult [interaction-design.md](interaction-design.md) +- Animation or transitions? Consult [motion-design.md](motion-design.md) +- Color-heavy or themed? Consult [color-and-contrast.md](color-and-contrast.md) +- Responsive requirements? Consult [responsive-design.md](responsive-design.md) +- Heavy on copy, labels, or errors? Consult [ux-writing.md](ux-writing.md) + +## Step 3: Build + +Implement the feature following the design brief. Work in this order: + +1. **Structure first**: HTML/semantic structure for the primary state. No styling yet. +2. **Layout and spacing**: Establish the spatial rhythm and visual hierarchy. +3. **Typography and color**: Apply the type scale and color system. +4. **Interactive states**: Hover, focus, active, disabled. +5. **Edge case states**: Empty, loading, error, overflow, first-run. +6. **Motion**: Purposeful transitions and animations (if appropriate). +7. **Responsive**: Adapt for different viewports. Don't just shrink; redesign for the context. + +### During Build +- Test with real (or realistic) data at every step, not placeholder text +- Check each state as you build it, not all at the end +- If you discover a design question, stop and ask rather than guessing +- Every visual choice should trace back to something in the design brief + +## Step 4: Visual Iteration + +**This step is critical.** Do not stop after the first implementation pass. + +Open the result in a browser window. If browser automation tools are available, use them to navigate to the page and visually inspect the result. If not, ask the user to open it and provide feedback. + +Iterate through these checks visually: + +1. **Does it match the brief?** Compare the live result against every section of the design brief. Fix discrepancies. +2. **Does it pass the AI slop test?** If someone saw this and said "AI made this," would they believe it immediately? If yes, it needs more design intention. +3. **Run /validate.** Fix any P0 or P1 issues. +4. **Check every state.** Navigate through empty, error, loading, and edge case states. Each one should feel intentional, not like an afterthought. +5. **Check responsive.** Resize the viewport. Does it adapt well or just shrink? +6. **Check the details.** Spacing consistency, type hierarchy clarity, color contrast, interactive feedback, motion timing. + +After each round of fixes, visually verify again. **Repeat until you would be proud to show this to the user.** The bar is not "it works"; the bar is "this delights." + +## Step 5: Present + +Present the result to the user: +- Show the feature in its primary state +- Walk through the key states (empty, error, responsive) +- Explain design decisions that connect back to the design brief +- Ask: "What's working? What isn't?" + +Iterate based on feedback. Good design is rarely right on the first pass. diff --git a/.pi/skills/shape/SKILL.md b/.pi/skills/shape/SKILL.md new file mode 100644 index 000000000..7e520562f --- /dev/null +++ b/.pi/skills/shape/SKILL.md @@ -0,0 +1,93 @@ +--- +name: shape +description: Plan the UX and UI for a feature before writing code. Runs a structured discovery interview, then produces a design brief that guides implementation. Use during the planning phase to establish design direction, constraints, and strategy before any code is written. +--- + +## MANDATORY PREPARATION + +Invoke /impeccable, which contains design principles, anti-patterns, and the **Context Gathering Protocol**. Follow the protocol before proceeding. If no design context exists yet, you MUST run /impeccable teach first. + +--- + +Shape the UX and UI for a feature before any code is written. This skill produces a **design brief**: a structured artifact that guides implementation through discovery, not guesswork. + +**Scope**: Design planning only. This skill does NOT write code. It produces the thinking that makes code good. + +**Output**: A design brief that can be handed off to /impeccable craft, /impeccable, or any other implementation skill. + +## Philosophy + +Most AI-generated UIs fail not because of bad code, but because of skipped thinking. They jump to "here's a card grid" without asking "what is the user trying to accomplish?" This skill inverts that: understand deeply first, so implementation is precise. + +## Phase 1: Discovery Interview + +**Do NOT write any code or make any design decisions during this phase.** Your only job is to understand the feature deeply enough to make excellent design decisions later. + +Ask these questions in conversation, adapting based on answers. Don't dump them all at once; have a natural dialogue. ask the user directly to clarify what you cannot infer. + +### Purpose & Context +- What is this feature for? What problem does it solve? +- Who specifically will use it? (Not "users"; be specific: role, context, frequency) +- What does success look like? How will you know this feature is working? +- What's the user's state of mind when they reach this feature? (Rushed? Exploring? Anxious? Focused?) + +### Content & Data +- What content or data does this feature display or collect? +- What are the realistic ranges? (Minimum, typical, maximum, e.g., 0 items, 5 items, 500 items) +- What are the edge cases? (Empty state, error state, first-time use, power user) +- Is any content dynamic? What changes and how often? + +### Design Goals +- What's the single most important thing a user should do or understand here? +- What should this feel like? (Fast/efficient? Calm/trustworthy? Fun/playful? Premium/refined?) +- Are there existing patterns in the product this should be consistent with? +- Are there specific examples (inside or outside the product) that capture what you're going for? + +### Constraints +- Are there technical constraints? (Framework, performance budget, browser support) +- Are there content constraints? (Localization, dynamic text length, user-generated content) +- Mobile/responsive requirements? +- Accessibility requirements beyond WCAG AA? + +### Anti-Goals +- What should this NOT be? What would be a wrong direction? +- What's the biggest risk of getting this wrong? + +## Phase 2: Design Brief + +After the interview, synthesize everything into a structured design brief. Present it to the user for confirmation before considering this skill complete. + +### Brief Structure + +**1. Feature Summary** (2-3 sentences) +What this is, who it's for, what it needs to accomplish. + +**2. Primary User Action** +The single most important thing a user should do or understand here. + +**3. Design Direction** +How this should feel. What aesthetic approach fits. Reference the project's design context from `.impeccable.md` and explain how this feature should express it. + +**4. Layout Strategy** +High-level spatial approach: what gets emphasis, what's secondary, how information flows. Describe the visual hierarchy and rhythm, not specific CSS. + +**5. Key States** +List every state the feature needs: default, empty, loading, error, success, edge cases. For each, note what the user needs to see and feel. + +**6. Interaction Model** +How users interact with this feature. What happens on click, hover, scroll? What feedback do they get? What's the flow from entry to completion? + +**7. Content Requirements** +What copy, labels, empty state messages, error messages, and microcopy are needed. Note any dynamic content and its realistic ranges. + +**8. Recommended References** +Based on the brief, list which impeccable reference files would be most valuable during implementation (e.g., spatial-design.md for complex layouts, motion-design.md for animated features, interaction-design.md for form-heavy features). + +**9. Open Questions** +Anything unresolved that the implementer should resolve during build. + +--- + +ask the user directly to clarify what you cannot infer. Get explicit confirmation of the brief before finishing. If the user disagrees with any part, revisit the relevant discovery questions. + +Once confirmed, the brief is complete. The user can now hand it to /impeccable craft to build the feature, or use it to guide any other implementation approach. \ No newline at end of file diff --git a/.pi/skills/validate/SKILL.md b/.pi/skills/validate/SKILL.md index f711dcb7c..b4c183888 100644 --- a/.pi/skills/validate/SKILL.md +++ b/.pi/skills/validate/SKILL.md @@ -5,11 +5,11 @@ description: Fast visual validation after UX/UI changes. Checks anti-patterns, s ## MANDATORY PREPARATION -Invoke /impeccable -- it contains design principles, anti-patterns, and the **Context Gathering Protocol**. Follow the protocol before proceeding -- if no design context exists yet, you MUST run /impeccable teach first. +Invoke /impeccable, which contains design principles, anti-patterns, and the **Context Gathering Protocol**. Follow the protocol before proceeding. If no design context exists yet, you MUST run /impeccable teach first. --- -A fast, focused quality gate. Not a full audit or critique -- this is the 2-minute check you run after every UI change to catch the most common and damaging issues before they ship. +A fast, focused quality gate. Not a full audit or critique; this is the 2-minute check you run after every UI change to catch the most common and damaging issues before they ship. Think of this as a design linter: opinionated, fast, and actionable. Flag what's wrong, say how to fix it, move on. @@ -69,10 +69,10 @@ Check against ALL **DON'T** guidelines in the impeccable skill. The most common Report findings as a flat list, grouped by severity: **Severity levels:** -- **P0 -- Broken**: Visually broken, inaccessible, or fundamentally wrong. Fix before shipping. -- **P1 -- Anti-pattern**: Clear design anti-pattern that undermines quality. Fix now. -- **P2 -- Inconsistency**: Spacing, token, or style drift from the design system. Fix soon. -- **P3 -- Polish**: Minor refinement opportunity. Fix if time allows. +- **P0 (Broken)**: Visually broken, inaccessible, or fundamentally wrong. Fix before shipping. +- **P1 (Anti-pattern)**: Clear design anti-pattern that undermines quality. Fix now. +- **P2 (Inconsistency)**: Spacing, token, or style drift from the design system. Fix soon. +- **P3 (Polish)**: Minor refinement opportunity. Fix if time allows. For each finding: ``` @@ -80,7 +80,7 @@ For each finding: → Fix: Concrete action to take (file:line if applicable) ``` -Keep the total list short. If everything looks good, say so -- don't invent issues. +Keep the total list short. If everything looks good, say so. Don't invent issues. ## After Validation diff --git a/.rovodev/skills/audit/SKILL.md b/.rovodev/skills/audit/SKILL.md index dcabe5eea..fa777e5c0 100644 --- a/.rovodev/skills/audit/SKILL.md +++ b/.rovodev/skills/audit/SKILL.md @@ -108,7 +108,7 @@ For each issue, document: - **Impact**: How it affects users - **WCAG/Standard**: Which standard it violates (if applicable) - **Recommendation**: How to fix it -- **Suggested command**: Which command to use (prefer: /animate, /validate, /quieter, /craft, /optimize, /adapt, /clarify, /distill, /delight, /onboard, /normalize, /audit, /harden, /polish, /extract, /bolder, /arrange, /typeset, /critique, /colorize, /overdrive) +- **Suggested command**: Which command to use (prefer: /animate, /validate, /quieter, /shape, /optimize, /adapt, /clarify, /distill, /delight, /onboard, /normalize, /audit, /harden, /polish, /extract, /bolder, /arrange, /typeset, /critique, /colorize, /overdrive) ### Patterns & Systemic Issues @@ -127,7 +127,7 @@ List recommended commands in priority order (P0 first, then P1, then P2): 1. **[P?] `/command-name`** — Brief description (specific context from audit findings) 2. **[P?] `/command-name`** — Brief description (specific context) -**Rules**: Only recommend commands from: /animate, /validate, /quieter, /craft, /optimize, /adapt, /clarify, /distill, /delight, /onboard, /normalize, /audit, /harden, /polish, /extract, /bolder, /arrange, /typeset, /critique, /colorize, /overdrive. Map findings to the most appropriate command. End with `/polish` as the final step if any fixes were recommended. +**Rules**: Only recommend commands from: /animate, /validate, /quieter, /shape, /optimize, /adapt, /clarify, /distill, /delight, /onboard, /normalize, /audit, /harden, /polish, /extract, /bolder, /arrange, /typeset, /critique, /colorize, /overdrive. Map findings to the most appropriate command. End with `/polish` as the final step if any fixes were recommended. After presenting the summary, tell the user: diff --git a/.rovodev/skills/craft/SKILL.md b/.rovodev/skills/craft/SKILL.md deleted file mode 100644 index 419dcd8ad..000000000 --- a/.rovodev/skills/craft/SKILL.md +++ /dev/null @@ -1,97 +0,0 @@ ---- -name: craft -description: Design and build ideal UX+UI for a feature through guided discovery. Interviews the user about purpose, audience, and design goals before implementing. Use when building a new feature, redesigning an existing one, or when the user wants a thoughtful, user-centered design process rather than jumping straight to code. -user-invocable: true -argument-hint: "[feature to design]" ---- - -## MANDATORY PREPARATION - -Invoke /impeccable -- it contains design principles, anti-patterns, and the **Context Gathering Protocol**. Follow the protocol before proceeding -- if no design context exists yet, you MUST run /impeccable teach first. - ---- - -Build the ideal UX and UI for a feature. This skill is about getting the design RIGHT before writing code -- through structured discovery, not guesswork. - -**Scope**: UX + UI design and implementation. Out of scope: building the underlying business logic, backend, or data layer. If the feature needs backend work, note what's needed but focus on the interface. - -## Philosophy - -Most AI-generated UIs fail not because of bad code, but because of skipped thinking. They jump to "here's a card grid" without asking "what is the user trying to accomplish?" This skill inverts that: understand deeply, then build precisely. - -## Phase 1: Discovery Interview - -**Do NOT write any code during this phase.** Your only job is to understand the feature deeply enough to make excellent design decisions. - -Ask these questions in conversation, adapting based on answers. Don't dump them all at once -- have a natural dialogue. ask the user directly to clarify what you cannot infer. - -### Purpose & Context -- What is this feature for? What problem does it solve? -- Who specifically will use it? (Not "users" -- be specific: role, context, frequency) -- What does success look like? How will you know this feature is working? -- What's the user's state of mind when they reach this feature? (Rushed? Exploring? Anxious? Focused?) - -### Content & Data -- What content or data does this feature display or collect? -- What are the realistic ranges? (Minimum, typical, maximum -- e.g., 0 items, 5 items, 500 items) -- What are the edge cases? (Empty state, error state, first-time use, power user) -- Is any content dynamic? What changes and how often? - -### Design Goals -- What's the single most important thing a user should do or understand here? -- What should this feel like? (Fast/efficient? Calm/trustworthy? Fun/playful? Premium/refined?) -- Are there existing patterns in the product this should be consistent with? -- Are there specific examples (inside or outside the product) that capture what you're going for? - -### Constraints -- Are there technical constraints? (Framework, performance budget, browser support) -- Are there content constraints? (Localization, dynamic text length, user-generated content) -- Mobile/responsive requirements? -- Accessibility requirements beyond WCAG AA? - -### Anti-Goals -- What should this NOT be? What would be a wrong direction? -- What's the biggest risk of getting this wrong? - -## Phase 2: Design Synthesis - -After the interview, synthesize your understanding before touching code. Present this back to the user for confirmation: - -1. **Feature brief** (2-3 sentences): What this is, who it's for, what it needs to accomplish -2. **Primary user action**: The one thing that matters most -3. **Design direction**: How this should feel, what aesthetic approach fits -4. **Key states**: List every state the feature needs (default, empty, loading, error, success, edge cases) -5. **Open questions**: Anything unresolved that might change the approach - -ask the user directly to clarify what you cannot infer. -- get explicit confirmation before proceeding. If the user disagrees with your synthesis, revisit the relevant discovery questions. - -## Phase 3: Implementation - -Now build it. Use /impeccable as your design engine -- follow its principles, consult its references, avoid its anti-patterns. - -### Implementation Order -1. **Structure first**: HTML/semantic structure for the primary state. No styling yet. -2. **Layout and spacing**: Establish the spatial rhythm and visual hierarchy. -3. **Typography and color**: Apply the type scale and color system. -4. **Interactive states**: Hover, focus, active, disabled. -5. **Edge case states**: Empty, loading, error, overflow, first-run. -6. **Motion**: Purposeful transitions and animations (if appropriate). -7. **Responsive**: Adapt for different viewports -- don't just shrink, redesign for the context. - -### During Implementation -- Test with real (or realistic) data at every step, not placeholder text -- Check each state as you build it, not all at the end -- If you discover a design question during implementation, stop and ask rather than guessing -- Every visual choice should trace back to something learned in discovery - -## Phase 4: Validation - -After implementation, run /validate on your work. Fix any P0 or P1 issues before presenting to the user. - -Then present the result: -- Show the feature in its primary state -- Walk through the key states (empty, error, responsive) -- Explain design decisions that connect back to what you learned in discovery -- Ask for feedback: "What's working? What isn't?" - -Iterate based on feedback. Good design is rarely right on the first pass. \ No newline at end of file diff --git a/.rovodev/skills/critique/SKILL.md b/.rovodev/skills/critique/SKILL.md index 30840103a..79d8f0cea 100644 --- a/.rovodev/skills/critique/SKILL.md +++ b/.rovodev/skills/critique/SKILL.md @@ -11,21 +11,21 @@ allowed-tools: ### Step 1: Preparation -Invoke /impeccable -- it contains design principles, anti-patterns, and the **Context Gathering Protocol**. Follow the protocol before proceeding -- if no design context exists yet, you MUST run /impeccable teach first. Additionally gather: what the interface is trying to accomplish. +Invoke /impeccable, which contains design principles, anti-patterns, and the **Context Gathering Protocol**. Follow the protocol before proceeding. If no design context exists yet, you MUST run /impeccable teach first. Additionally gather: what the interface is trying to accomplish. ### Step 2: Gather Assessments Launch two independent assessments. **Neither must see the other's output** to avoid bias. -You SHOULD delegate each assessment to a separate sub-agent for independence. Use your environment's agent spawning mechanism -- e.g., Claude Code's `Agent` tool, or Codex's subagent spawning ("spawn two agents in parallel"). Sub-agents should return their findings as structured text -- do NOT output findings to the user yet. +You SHOULD delegate each assessment to a separate sub-agent for independence. Use your environment's agent spawning mechanism (e.g., Claude Code's `Agent` tool, or Codex's subagent spawning). Sub-agents should return their findings as structured text. Do NOT output findings to the user yet. If sub-agents are not available in the current environment, complete each assessment sequentially, writing findings to internal notes before proceeding. -**Tab isolation**: When browser automation is available, each assessment MUST create its own new tab -- never reuse an existing tab, even if one is already open at the correct URL. This prevents the two assessments from interfering with each other's page state. +**Tab isolation**: When browser automation is available, each assessment MUST create its own new tab. Never reuse an existing tab, even if one is already open at the correct URL. This prevents the two assessments from interfering with each other's page state. #### Assessment A: LLM Design Review -Read the relevant source files (HTML, CSS, JS/TS) and, if browser automation is available, visually inspect the live page. **Create a new tab** for this -- do not reuse existing tabs. After navigation, label the tab by setting the document title: +Read the relevant source files (HTML, CSS, JS/TS) and, if browser automation is available, visually inspect the live page. **Create a new tab** for this; do not reuse existing tabs. After navigation, label the tab by setting the document title: ```javascript document.title = '[LLM] ' + document.title; ``` @@ -36,8 +36,8 @@ Think like a design director. Evaluate: **Holistic Design Review**: 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). **Cognitive Load** (consult [cognitive-load](reference/cognitive-load.md)): -- Run the 8-item cognitive load checklist. Report failure count: 0--1 = low (good), 2--3 = moderate, 4+ = critical. -- Count visible options at each decision point -- if >4, flag it. +- Run the 8-item cognitive load checklist. Report failure count: 0-1 = low (good), 2-3 = moderate, 4+ = critical. +- Count visible options at each decision point. If >4, flag it. - Check for progressive disclosure: is complexity revealed only when needed? **Emotional Journey**: @@ -46,9 +46,9 @@ Think like a design director. Evaluate: - **Emotional valleys**: Check for anxiety spikes at high-stakes moments (payment, delete, commit). Are there design interventions (progress indicators, reassurance copy, undo options)? **Nielsen's Heuristics** (consult [heuristics-scoring](reference/heuristics-scoring.md)): -Score each of the 10 heuristics 0--4. This scoring will be presented in the report. +Score each of the 10 heuristics 0-4. This scoring will be presented in the report. -Return structured findings covering: AI slop verdict, heuristic scores, cognitive load assessment, what's working (2--3 items), priority issues (3--5 with what/why/fix), minor observations, and provocative questions. +Return structured findings covering: AI slop verdict, heuristic scores, cognitive load assessment, what's working (2-3 items), priority issues (3-5 with what/why/fix), minor observations, and provocative questions. #### Assessment B: Automated Detection @@ -67,37 +67,37 @@ npx impeccable --json [--fast] [target] **Browser visualization** (when browser automation tools are available AND the target is a viewable page): -The overlay is a **visual aid for the user** -- it highlights issues directly in their browser. Do NOT scroll through the page to screenshot overlays. Instead, read the console output to get the results programmatically. +The overlay is a **visual aid for the user**. It highlights issues directly in their browser. Do NOT scroll through the page to screenshot overlays. Instead, read the console output to get the results programmatically. 1. **Start the live detection server**: ```bash npx impeccable live & ``` Note the port printed to stdout (auto-assigned). Use `--port=PORT` to fix it. -2. **Create a new tab** and navigate to the page (use dev server URL for local files, or direct URL) -- do not reuse existing tabs +2. **Create a new tab** and navigate to the page (use dev server URL for local files, or direct URL). Do not reuse existing tabs. 3. **Label the tab** via `javascript_tool` so the user can distinguish it: ```javascript document.title = '[Human] ' + document.title; ``` -4. **Scroll to top** -- ensure the page is scrolled to the very top before injection +4. **Scroll to top** to ensure the page is scrolled to the very top before injection 5. **Inject** via `javascript_tool` (replace PORT with the port from step 1): ```javascript const s = document.createElement('script'); s.src = 'http://localhost:PORT/detect.js'; document.head.appendChild(s); ``` -6. Wait 2--3 seconds for the detector to render overlays -7. **Read results from console** using `read_console_messages` with pattern `impeccable` -- the detector logs all findings with the `[impeccable]` prefix. Do NOT scroll through the page to take screenshots of the overlays. +6. Wait 2-3 seconds for the detector to render overlays +7. **Read results from console** using `read_console_messages` with pattern `impeccable`. The detector logs all findings with the `[impeccable]` prefix. Do NOT scroll through the page to take screenshots of the overlays. 8. **Cleanup**: Stop the live server when done: ```bash npx impeccable live stop ``` -For multi-view targets, inject on 3--5 representative pages. If injection fails, continue with CLI results only. +For multi-view targets, inject on 3-5 representative pages. If injection fails, continue with CLI results only. Return: CLI findings (JSON), browser console findings (if applicable), and any false positives noted. ### Step 3: Generate Combined Critique Report -Synthesize both assessments into a single report. Do NOT simply concatenate -- weave the findings together, noting where the LLM review and detector agree, where the detector caught issues the LLM missed, and where detector findings are false positives. +Synthesize both assessments into a single report. Do NOT simply concatenate. Weave the findings together, noting where the LLM review and detector agree, where the detector caught issues the LLM missed, and where detector findings are false positives. Structure your feedback as a design director would: @@ -108,7 +108,7 @@ Present the Nielsen's 10 heuristics scores as a table: | # | Heuristic | Score | Key Issue | |---|-----------|-------|-----------| -| 1 | Visibility of System Status | ? | [specific finding or "--" if solid] | +| 1 | Visibility of System Status | ? | [specific finding or "n/a" if solid] | | 2 | Match System / Real World | ? | | | 3 | User Control and Freedom | ? | | | 4 | Consistency and Standards | ? | | @@ -120,7 +120,7 @@ Present the Nielsen's 10 heuristics scores as a table: | 10 | Help and Documentation | ? | | | **Total** | | **??/40** | **[Rating band]** | -Be honest with scores. A 4 means genuinely excellent. Most real interfaces score 20--32. +Be honest with scores. A 4 means genuinely excellent. Most real interfaces score 20-32. #### Anti-Patterns Verdict @@ -133,24 +133,24 @@ Be honest with scores. A 4 means genuinely excellent. Most real interfaces score **Visual overlays** (if browser was used): Tell the user that overlays are now visible in the **[Human]** tab in their browser, highlighting the detected issues. Summarize what the console output reported. #### Overall Impression -A brief gut reaction -- what works, what doesn't, and the single biggest opportunity. +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. +Highlight 2-3 things done well. Be specific about why they work. #### Priority Issues -The 3--5 most impactful design problems, ordered by importance. +The 3-5 most impactful design problems, ordered by importance. -For each issue, tag with **P0--P3 severity** (consult [heuristics-scoring](reference/heuristics-scoring.md) for severity definitions): +For each issue, tag with **P0-P3 severity** (consult [heuristics-scoring](reference/heuristics-scoring.md) for severity definitions): - **[P?] What**: Name the problem clearly - **Why it matters**: How this hurts users or undermines goals - **Fix**: What to do about it (be concrete) -- **Suggested command**: Which command could address this (from: /animate, /validate, /quieter, /craft, /optimize, /adapt, /clarify, /distill, /delight, /onboard, /normalize, /audit, /harden, /polish, /extract, /bolder, /arrange, /typeset, /critique, /colorize, /overdrive) +- **Suggested command**: Which command could address this (from: /animate, /validate, /quieter, /shape, /optimize, /adapt, /clarify, /distill, /delight, /onboard, /normalize, /audit, /harden, /polish, /extract, /bolder, /arrange, /typeset, /critique, /colorize, /overdrive) #### Persona Red Flags > *Consult [personas](reference/personas.md)* -Auto-select 2--3 personas most relevant to this interface type (use the selection table in the reference). If `AGENTS.md` contains a `## Design Context` section from `impeccable teach`, also generate 1--2 project-specific personas from the audience/brand info. +Auto-select 2-3 personas most relevant to this interface type (use the selection table in the reference). If `AGENTS.md` contains a `## Design Context` section from `impeccable teach`, also generate 1-2 project-specific personas from the audience/brand info. For each selected persona, walk through the primary user action and list specific red flags found: @@ -158,7 +158,7 @@ For each selected persona, walk through the primary user action and list specifi **Jordan (First-Timer)**: Icon-only nav in sidebar. Technical jargon in error messages ("404 Not Found"). No visible help. Will abandon at step 2. -Be specific -- name the exact elements and interactions that fail each persona. Don't write generic persona descriptions; write what broke for them. +Be specific. Name the exact elements and interactions that fail each persona. Don't write generic persona descriptions; write what broke for them. #### Minor Observations Quick notes on smaller issues worth addressing. @@ -170,32 +170,32 @@ Provocative questions that might unlock better solutions: - "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 +- 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 +- Prioritize ruthlessly. If everything is important, nothing is. +- Don't soften criticism. Developers need honest feedback to ship great design. ### Step 4: Ask the User **After presenting findings**, use targeted questions based on what was actually found. ask the user directly to clarify what you cannot infer. These answers will shape the action plan. -Ask questions along these lines (adapt to the specific findings -- do NOT ask generic questions): +Ask questions along these lines (adapt to the specific findings; do NOT ask generic questions): -1. **Priority direction**: Based on the issues found, ask which category matters most to the user right now. For example: "I found problems with visual hierarchy, color usage, and information overload. Which area should we tackle first?" Offer the top 2--3 issue categories as options. +1. **Priority direction**: Based on the issues found, ask which category matters most to the user right now. For example: "I found problems with visual hierarchy, color usage, and information overload. Which area should we tackle first?" Offer the top 2-3 issue categories as options. -2. **Design intent**: If the critique found a tonal mismatch, ask whether it was intentional. For example: "The interface feels clinical and corporate. Is that the intended tone, or should it feel warmer/bolder/more playful?" Offer 2--3 tonal directions as options based on what would fix the issues found. +2. **Design intent**: If the critique found a tonal mismatch, ask whether it was intentional. For example: "The interface feels clinical and corporate. Is that the intended tone, or should it feel warmer/bolder/more playful?" Offer 2-3 tonal directions as options based on what would fix the issues found. 3. **Scope**: Ask how much the user wants to take on. For example: "I found N issues. Want to address everything, or focus on the top 3?" Offer scope options like "Top 3 only", "All issues", "Critical issues only". -4. **Constraints** (optional -- only ask if relevant): If the findings touch many areas, ask if anything is off-limits. For example: "Should any sections stay as-is?" This prevents the plan from touching things the user considers done. +4. **Constraints** (optional; only ask if relevant): If the findings touch many areas, ask if anything is off-limits. For example: "Should any sections stay as-is?" This prevents the plan from touching things the user considers done. **Rules for questions**: -- Every question must reference specific findings from the report -- never ask generic "who is your audience?" questions -- Keep it to 2--4 questions maximum -- respect the user's time -- Offer concrete options, not open-ended prompts -- If findings are straightforward (e.g., only 1--2 clear issues), skip questions and go directly to Step 5 +- Every question must reference specific findings from the report. Never ask generic "who is your audience?" questions. +- Keep it to 2-4 questions maximum. Respect the user's time. +- Offer concrete options, not open-ended prompts. +- If findings are straightforward (e.g., only 1-2 clear issues), skip questions and go directly to Step 5. ### Step 5: Recommended Actions @@ -205,12 +205,12 @@ Ask questions along these lines (adapt to the specific findings -- do NOT ask ge List recommended commands in priority order, based on the user's answers: -1. **`/command-name`** -- Brief description of what to fix (specific context from critique findings) -2. **`/command-name`** -- Brief description (specific context) +1. **`/command-name`**: Brief description of what to fix (specific context from critique findings) +2. **`/command-name`**: Brief description (specific context) ... **Rules for recommendations**: -- Only recommend commands from: /animate, /validate, /quieter, /craft, /optimize, /adapt, /clarify, /distill, /delight, /onboard, /normalize, /audit, /harden, /polish, /extract, /bolder, /arrange, /typeset, /critique, /colorize, /overdrive +- Only recommend commands from: /animate, /validate, /quieter, /shape, /optimize, /adapt, /clarify, /distill, /delight, /onboard, /normalize, /audit, /harden, /polish, /extract, /bolder, /arrange, /typeset, /critique, /colorize, /overdrive - Order by the user's stated priorities first, then by impact - Each item's description should carry enough context that the command knows what to focus on - Map each Priority Issue to the appropriate command diff --git a/.rovodev/skills/impeccable/SKILL.md b/.rovodev/skills/impeccable/SKILL.md index da3b7efa0..013ae41e9 100644 --- a/.rovodev/skills/impeccable/SKILL.md +++ b/.rovodev/skills/impeccable/SKILL.md @@ -1,8 +1,8 @@ --- name: impeccable -description: Create distinctive, production-grade frontend interfaces with high design quality. Generates creative, polished code that avoids generic AI aesthetics. Use when the user asks to build web components, pages, artifacts, posters, or applications, or when any design skill requires project context. Call with 'teach' argument to run design context setup. +description: Create distinctive, production-grade frontend interfaces with high design quality. Generates creative, polished code that avoids generic AI aesthetics. Use when the user asks to build web components, pages, artifacts, posters, or applications, or when any design skill requires project context. Call with 'craft' to run the full shape-then-build flow, or 'teach' for design context setup. user-invocable: true -argument-hint: "[teach]" +argument-hint: "[craft|teach]" license: Apache 2.0. Based on Anthropic's frontend-design skill. See NOTICE.md for attribution. --- @@ -150,6 +150,12 @@ Remember: Rovo Dev is capable of extraordinary creative work. Don't hold back. S --- +## Craft Mode + +If this skill is invoked with the argument "craft" (e.g., `/impeccable craft [feature description]`), follow the [craft flow](reference/craft.md). Pass any additional arguments as the feature description. + +--- + ## Teach Mode If this skill is invoked with the argument "teach" (e.g., `/impeccable teach`), skip all design work above and instead run the teach flow below. This is a one-time setup that gathers design context for the project. diff --git a/.rovodev/skills/impeccable/reference/craft.md b/.rovodev/skills/impeccable/reference/craft.md new file mode 100644 index 000000000..d2961057f --- /dev/null +++ b/.rovodev/skills/impeccable/reference/craft.md @@ -0,0 +1,70 @@ +# Craft Flow + +Build a feature with impeccable UX and UI quality through a structured process: shape the design, load the right references, then build and iterate visually until the result is delightful. + +## Step 1: Shape the Design + +Run /shape, passing along whatever feature description the user provided. + +Wait for the design brief to be fully confirmed before proceeding. The brief is your blueprint, and every implementation decision should trace back to it. + +If the user has already run /shape and has a confirmed design brief, skip this step and use the existing brief. + +## Step 2: Load References + +Based on the design brief's "Recommended References" section, consult the relevant impeccable reference files. At minimum, always consult: + +- [spatial-design.md](spatial-design.md) for layout and spacing +- [typography.md](typography.md) for type hierarchy + +Then add references based on the brief's needs: +- Complex interactions or forms? Consult [interaction-design.md](interaction-design.md) +- Animation or transitions? Consult [motion-design.md](motion-design.md) +- Color-heavy or themed? Consult [color-and-contrast.md](color-and-contrast.md) +- Responsive requirements? Consult [responsive-design.md](responsive-design.md) +- Heavy on copy, labels, or errors? Consult [ux-writing.md](ux-writing.md) + +## Step 3: Build + +Implement the feature following the design brief. Work in this order: + +1. **Structure first**: HTML/semantic structure for the primary state. No styling yet. +2. **Layout and spacing**: Establish the spatial rhythm and visual hierarchy. +3. **Typography and color**: Apply the type scale and color system. +4. **Interactive states**: Hover, focus, active, disabled. +5. **Edge case states**: Empty, loading, error, overflow, first-run. +6. **Motion**: Purposeful transitions and animations (if appropriate). +7. **Responsive**: Adapt for different viewports. Don't just shrink; redesign for the context. + +### During Build +- Test with real (or realistic) data at every step, not placeholder text +- Check each state as you build it, not all at the end +- If you discover a design question, stop and ask rather than guessing +- Every visual choice should trace back to something in the design brief + +## Step 4: Visual Iteration + +**This step is critical.** Do not stop after the first implementation pass. + +Open the result in a browser window. If browser automation tools are available, use them to navigate to the page and visually inspect the result. If not, ask the user to open it and provide feedback. + +Iterate through these checks visually: + +1. **Does it match the brief?** Compare the live result against every section of the design brief. Fix discrepancies. +2. **Does it pass the AI slop test?** If someone saw this and said "AI made this," would they believe it immediately? If yes, it needs more design intention. +3. **Run /validate.** Fix any P0 or P1 issues. +4. **Check every state.** Navigate through empty, error, loading, and edge case states. Each one should feel intentional, not like an afterthought. +5. **Check responsive.** Resize the viewport. Does it adapt well or just shrink? +6. **Check the details.** Spacing consistency, type hierarchy clarity, color contrast, interactive feedback, motion timing. + +After each round of fixes, visually verify again. **Repeat until you would be proud to show this to the user.** The bar is not "it works"; the bar is "this delights." + +## Step 5: Present + +Present the result to the user: +- Show the feature in its primary state +- Walk through the key states (empty, error, responsive) +- Explain design decisions that connect back to the design brief +- Ask: "What's working? What isn't?" + +Iterate based on feedback. Good design is rarely right on the first pass. diff --git a/.rovodev/skills/shape/SKILL.md b/.rovodev/skills/shape/SKILL.md new file mode 100644 index 000000000..330b9b02e --- /dev/null +++ b/.rovodev/skills/shape/SKILL.md @@ -0,0 +1,95 @@ +--- +name: shape +description: Plan the UX and UI for a feature before writing code. Runs a structured discovery interview, then produces a design brief that guides implementation. Use during the planning phase to establish design direction, constraints, and strategy before any code is written. +user-invocable: true +argument-hint: "[feature to shape]" +--- + +## MANDATORY PREPARATION + +Invoke /impeccable, which contains design principles, anti-patterns, and the **Context Gathering Protocol**. Follow the protocol before proceeding. If no design context exists yet, you MUST run /impeccable teach first. + +--- + +Shape the UX and UI for a feature before any code is written. This skill produces a **design brief**: a structured artifact that guides implementation through discovery, not guesswork. + +**Scope**: Design planning only. This skill does NOT write code. It produces the thinking that makes code good. + +**Output**: A design brief that can be handed off to /impeccable craft, /impeccable, or any other implementation skill. + +## Philosophy + +Most AI-generated UIs fail not because of bad code, but because of skipped thinking. They jump to "here's a card grid" without asking "what is the user trying to accomplish?" This skill inverts that: understand deeply first, so implementation is precise. + +## Phase 1: Discovery Interview + +**Do NOT write any code or make any design decisions during this phase.** Your only job is to understand the feature deeply enough to make excellent design decisions later. + +Ask these questions in conversation, adapting based on answers. Don't dump them all at once; have a natural dialogue. ask the user directly to clarify what you cannot infer. + +### Purpose & Context +- What is this feature for? What problem does it solve? +- Who specifically will use it? (Not "users"; be specific: role, context, frequency) +- What does success look like? How will you know this feature is working? +- What's the user's state of mind when they reach this feature? (Rushed? Exploring? Anxious? Focused?) + +### Content & Data +- What content or data does this feature display or collect? +- What are the realistic ranges? (Minimum, typical, maximum, e.g., 0 items, 5 items, 500 items) +- What are the edge cases? (Empty state, error state, first-time use, power user) +- Is any content dynamic? What changes and how often? + +### Design Goals +- What's the single most important thing a user should do or understand here? +- What should this feel like? (Fast/efficient? Calm/trustworthy? Fun/playful? Premium/refined?) +- Are there existing patterns in the product this should be consistent with? +- Are there specific examples (inside or outside the product) that capture what you're going for? + +### Constraints +- Are there technical constraints? (Framework, performance budget, browser support) +- Are there content constraints? (Localization, dynamic text length, user-generated content) +- Mobile/responsive requirements? +- Accessibility requirements beyond WCAG AA? + +### Anti-Goals +- What should this NOT be? What would be a wrong direction? +- What's the biggest risk of getting this wrong? + +## Phase 2: Design Brief + +After the interview, synthesize everything into a structured design brief. Present it to the user for confirmation before considering this skill complete. + +### Brief Structure + +**1. Feature Summary** (2-3 sentences) +What this is, who it's for, what it needs to accomplish. + +**2. Primary User Action** +The single most important thing a user should do or understand here. + +**3. Design Direction** +How this should feel. What aesthetic approach fits. Reference the project's design context from `.impeccable.md` and explain how this feature should express it. + +**4. Layout Strategy** +High-level spatial approach: what gets emphasis, what's secondary, how information flows. Describe the visual hierarchy and rhythm, not specific CSS. + +**5. Key States** +List every state the feature needs: default, empty, loading, error, success, edge cases. For each, note what the user needs to see and feel. + +**6. Interaction Model** +How users interact with this feature. What happens on click, hover, scroll? What feedback do they get? What's the flow from entry to completion? + +**7. Content Requirements** +What copy, labels, empty state messages, error messages, and microcopy are needed. Note any dynamic content and its realistic ranges. + +**8. Recommended References** +Based on the brief, list which impeccable reference files would be most valuable during implementation (e.g., spatial-design.md for complex layouts, motion-design.md for animated features, interaction-design.md for form-heavy features). + +**9. Open Questions** +Anything unresolved that the implementer should resolve during build. + +--- + +ask the user directly to clarify what you cannot infer. Get explicit confirmation of the brief before finishing. If the user disagrees with any part, revisit the relevant discovery questions. + +Once confirmed, the brief is complete. The user can now hand it to /impeccable craft to build the feature, or use it to guide any other implementation approach. \ No newline at end of file diff --git a/.rovodev/skills/validate/SKILL.md b/.rovodev/skills/validate/SKILL.md index a100bdf1f..62e4ac05d 100644 --- a/.rovodev/skills/validate/SKILL.md +++ b/.rovodev/skills/validate/SKILL.md @@ -7,11 +7,11 @@ argument-hint: "[area to validate]" ## MANDATORY PREPARATION -Invoke /impeccable -- it contains design principles, anti-patterns, and the **Context Gathering Protocol**. Follow the protocol before proceeding -- if no design context exists yet, you MUST run /impeccable teach first. +Invoke /impeccable, which contains design principles, anti-patterns, and the **Context Gathering Protocol**. Follow the protocol before proceeding. If no design context exists yet, you MUST run /impeccable teach first. --- -A fast, focused quality gate. Not a full audit or critique -- this is the 2-minute check you run after every UI change to catch the most common and damaging issues before they ship. +A fast, focused quality gate. Not a full audit or critique; this is the 2-minute check you run after every UI change to catch the most common and damaging issues before they ship. Think of this as a design linter: opinionated, fast, and actionable. Flag what's wrong, say how to fix it, move on. @@ -71,10 +71,10 @@ Check against ALL **DON'T** guidelines in the impeccable skill. The most common Report findings as a flat list, grouped by severity: **Severity levels:** -- **P0 -- Broken**: Visually broken, inaccessible, or fundamentally wrong. Fix before shipping. -- **P1 -- Anti-pattern**: Clear design anti-pattern that undermines quality. Fix now. -- **P2 -- Inconsistency**: Spacing, token, or style drift from the design system. Fix soon. -- **P3 -- Polish**: Minor refinement opportunity. Fix if time allows. +- **P0 (Broken)**: Visually broken, inaccessible, or fundamentally wrong. Fix before shipping. +- **P1 (Anti-pattern)**: Clear design anti-pattern that undermines quality. Fix now. +- **P2 (Inconsistency)**: Spacing, token, or style drift from the design system. Fix soon. +- **P3 (Polish)**: Minor refinement opportunity. Fix if time allows. For each finding: ``` @@ -82,7 +82,7 @@ For each finding: → Fix: Concrete action to take (file:line if applicable) ``` -Keep the total list short. If everything looks good, say so -- don't invent issues. +Keep the total list short. If everything looks good, say so. Don't invent issues. ## After Validation diff --git a/.trae-cn/skills/audit/SKILL.md b/.trae-cn/skills/audit/SKILL.md index dcabe5eea..fa777e5c0 100644 --- a/.trae-cn/skills/audit/SKILL.md +++ b/.trae-cn/skills/audit/SKILL.md @@ -108,7 +108,7 @@ For each issue, document: - **Impact**: How it affects users - **WCAG/Standard**: Which standard it violates (if applicable) - **Recommendation**: How to fix it -- **Suggested command**: Which command to use (prefer: /animate, /validate, /quieter, /craft, /optimize, /adapt, /clarify, /distill, /delight, /onboard, /normalize, /audit, /harden, /polish, /extract, /bolder, /arrange, /typeset, /critique, /colorize, /overdrive) +- **Suggested command**: Which command to use (prefer: /animate, /validate, /quieter, /shape, /optimize, /adapt, /clarify, /distill, /delight, /onboard, /normalize, /audit, /harden, /polish, /extract, /bolder, /arrange, /typeset, /critique, /colorize, /overdrive) ### Patterns & Systemic Issues @@ -127,7 +127,7 @@ List recommended commands in priority order (P0 first, then P1, then P2): 1. **[P?] `/command-name`** — Brief description (specific context from audit findings) 2. **[P?] `/command-name`** — Brief description (specific context) -**Rules**: Only recommend commands from: /animate, /validate, /quieter, /craft, /optimize, /adapt, /clarify, /distill, /delight, /onboard, /normalize, /audit, /harden, /polish, /extract, /bolder, /arrange, /typeset, /critique, /colorize, /overdrive. Map findings to the most appropriate command. End with `/polish` as the final step if any fixes were recommended. +**Rules**: Only recommend commands from: /animate, /validate, /quieter, /shape, /optimize, /adapt, /clarify, /distill, /delight, /onboard, /normalize, /audit, /harden, /polish, /extract, /bolder, /arrange, /typeset, /critique, /colorize, /overdrive. Map findings to the most appropriate command. End with `/polish` as the final step if any fixes were recommended. After presenting the summary, tell the user: diff --git a/.trae-cn/skills/craft/SKILL.md b/.trae-cn/skills/craft/SKILL.md deleted file mode 100644 index 419dcd8ad..000000000 --- a/.trae-cn/skills/craft/SKILL.md +++ /dev/null @@ -1,97 +0,0 @@ ---- -name: craft -description: Design and build ideal UX+UI for a feature through guided discovery. Interviews the user about purpose, audience, and design goals before implementing. Use when building a new feature, redesigning an existing one, or when the user wants a thoughtful, user-centered design process rather than jumping straight to code. -user-invocable: true -argument-hint: "[feature to design]" ---- - -## MANDATORY PREPARATION - -Invoke /impeccable -- it contains design principles, anti-patterns, and the **Context Gathering Protocol**. Follow the protocol before proceeding -- if no design context exists yet, you MUST run /impeccable teach first. - ---- - -Build the ideal UX and UI for a feature. This skill is about getting the design RIGHT before writing code -- through structured discovery, not guesswork. - -**Scope**: UX + UI design and implementation. Out of scope: building the underlying business logic, backend, or data layer. If the feature needs backend work, note what's needed but focus on the interface. - -## Philosophy - -Most AI-generated UIs fail not because of bad code, but because of skipped thinking. They jump to "here's a card grid" without asking "what is the user trying to accomplish?" This skill inverts that: understand deeply, then build precisely. - -## Phase 1: Discovery Interview - -**Do NOT write any code during this phase.** Your only job is to understand the feature deeply enough to make excellent design decisions. - -Ask these questions in conversation, adapting based on answers. Don't dump them all at once -- have a natural dialogue. ask the user directly to clarify what you cannot infer. - -### Purpose & Context -- What is this feature for? What problem does it solve? -- Who specifically will use it? (Not "users" -- be specific: role, context, frequency) -- What does success look like? How will you know this feature is working? -- What's the user's state of mind when they reach this feature? (Rushed? Exploring? Anxious? Focused?) - -### Content & Data -- What content or data does this feature display or collect? -- What are the realistic ranges? (Minimum, typical, maximum -- e.g., 0 items, 5 items, 500 items) -- What are the edge cases? (Empty state, error state, first-time use, power user) -- Is any content dynamic? What changes and how often? - -### Design Goals -- What's the single most important thing a user should do or understand here? -- What should this feel like? (Fast/efficient? Calm/trustworthy? Fun/playful? Premium/refined?) -- Are there existing patterns in the product this should be consistent with? -- Are there specific examples (inside or outside the product) that capture what you're going for? - -### Constraints -- Are there technical constraints? (Framework, performance budget, browser support) -- Are there content constraints? (Localization, dynamic text length, user-generated content) -- Mobile/responsive requirements? -- Accessibility requirements beyond WCAG AA? - -### Anti-Goals -- What should this NOT be? What would be a wrong direction? -- What's the biggest risk of getting this wrong? - -## Phase 2: Design Synthesis - -After the interview, synthesize your understanding before touching code. Present this back to the user for confirmation: - -1. **Feature brief** (2-3 sentences): What this is, who it's for, what it needs to accomplish -2. **Primary user action**: The one thing that matters most -3. **Design direction**: How this should feel, what aesthetic approach fits -4. **Key states**: List every state the feature needs (default, empty, loading, error, success, edge cases) -5. **Open questions**: Anything unresolved that might change the approach - -ask the user directly to clarify what you cannot infer. -- get explicit confirmation before proceeding. If the user disagrees with your synthesis, revisit the relevant discovery questions. - -## Phase 3: Implementation - -Now build it. Use /impeccable as your design engine -- follow its principles, consult its references, avoid its anti-patterns. - -### Implementation Order -1. **Structure first**: HTML/semantic structure for the primary state. No styling yet. -2. **Layout and spacing**: Establish the spatial rhythm and visual hierarchy. -3. **Typography and color**: Apply the type scale and color system. -4. **Interactive states**: Hover, focus, active, disabled. -5. **Edge case states**: Empty, loading, error, overflow, first-run. -6. **Motion**: Purposeful transitions and animations (if appropriate). -7. **Responsive**: Adapt for different viewports -- don't just shrink, redesign for the context. - -### During Implementation -- Test with real (or realistic) data at every step, not placeholder text -- Check each state as you build it, not all at the end -- If you discover a design question during implementation, stop and ask rather than guessing -- Every visual choice should trace back to something learned in discovery - -## Phase 4: Validation - -After implementation, run /validate on your work. Fix any P0 or P1 issues before presenting to the user. - -Then present the result: -- Show the feature in its primary state -- Walk through the key states (empty, error, responsive) -- Explain design decisions that connect back to what you learned in discovery -- Ask for feedback: "What's working? What isn't?" - -Iterate based on feedback. Good design is rarely right on the first pass. \ No newline at end of file diff --git a/.trae-cn/skills/critique/SKILL.md b/.trae-cn/skills/critique/SKILL.md index 7dfed6fa9..99347dc60 100644 --- a/.trae-cn/skills/critique/SKILL.md +++ b/.trae-cn/skills/critique/SKILL.md @@ -9,21 +9,21 @@ argument-hint: "[area (feature, page, component...)]" ### Step 1: Preparation -Invoke /impeccable -- it contains design principles, anti-patterns, and the **Context Gathering Protocol**. Follow the protocol before proceeding -- if no design context exists yet, you MUST run /impeccable teach first. Additionally gather: what the interface is trying to accomplish. +Invoke /impeccable, which contains design principles, anti-patterns, and the **Context Gathering Protocol**. Follow the protocol before proceeding. If no design context exists yet, you MUST run /impeccable teach first. Additionally gather: what the interface is trying to accomplish. ### Step 2: Gather Assessments Launch two independent assessments. **Neither must see the other's output** to avoid bias. -You SHOULD delegate each assessment to a separate sub-agent for independence. Use your environment's agent spawning mechanism -- e.g., Claude Code's `Agent` tool, or Codex's subagent spawning ("spawn two agents in parallel"). Sub-agents should return their findings as structured text -- do NOT output findings to the user yet. +You SHOULD delegate each assessment to a separate sub-agent for independence. Use your environment's agent spawning mechanism (e.g., Claude Code's `Agent` tool, or Codex's subagent spawning). Sub-agents should return their findings as structured text. Do NOT output findings to the user yet. If sub-agents are not available in the current environment, complete each assessment sequentially, writing findings to internal notes before proceeding. -**Tab isolation**: When browser automation is available, each assessment MUST create its own new tab -- never reuse an existing tab, even if one is already open at the correct URL. This prevents the two assessments from interfering with each other's page state. +**Tab isolation**: When browser automation is available, each assessment MUST create its own new tab. Never reuse an existing tab, even if one is already open at the correct URL. This prevents the two assessments from interfering with each other's page state. #### Assessment A: LLM Design Review -Read the relevant source files (HTML, CSS, JS/TS) and, if browser automation is available, visually inspect the live page. **Create a new tab** for this -- do not reuse existing tabs. After navigation, label the tab by setting the document title: +Read the relevant source files (HTML, CSS, JS/TS) and, if browser automation is available, visually inspect the live page. **Create a new tab** for this; do not reuse existing tabs. After navigation, label the tab by setting the document title: ```javascript document.title = '[LLM] ' + document.title; ``` @@ -34,8 +34,8 @@ Think like a design director. Evaluate: **Holistic Design Review**: 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). **Cognitive Load** (consult [cognitive-load](reference/cognitive-load.md)): -- Run the 8-item cognitive load checklist. Report failure count: 0--1 = low (good), 2--3 = moderate, 4+ = critical. -- Count visible options at each decision point -- if >4, flag it. +- Run the 8-item cognitive load checklist. Report failure count: 0-1 = low (good), 2-3 = moderate, 4+ = critical. +- Count visible options at each decision point. If >4, flag it. - Check for progressive disclosure: is complexity revealed only when needed? **Emotional Journey**: @@ -44,9 +44,9 @@ Think like a design director. Evaluate: - **Emotional valleys**: Check for anxiety spikes at high-stakes moments (payment, delete, commit). Are there design interventions (progress indicators, reassurance copy, undo options)? **Nielsen's Heuristics** (consult [heuristics-scoring](reference/heuristics-scoring.md)): -Score each of the 10 heuristics 0--4. This scoring will be presented in the report. +Score each of the 10 heuristics 0-4. This scoring will be presented in the report. -Return structured findings covering: AI slop verdict, heuristic scores, cognitive load assessment, what's working (2--3 items), priority issues (3--5 with what/why/fix), minor observations, and provocative questions. +Return structured findings covering: AI slop verdict, heuristic scores, cognitive load assessment, what's working (2-3 items), priority issues (3-5 with what/why/fix), minor observations, and provocative questions. #### Assessment B: Automated Detection @@ -65,37 +65,37 @@ npx impeccable --json [--fast] [target] **Browser visualization** (when browser automation tools are available AND the target is a viewable page): -The overlay is a **visual aid for the user** -- it highlights issues directly in their browser. Do NOT scroll through the page to screenshot overlays. Instead, read the console output to get the results programmatically. +The overlay is a **visual aid for the user**. It highlights issues directly in their browser. Do NOT scroll through the page to screenshot overlays. Instead, read the console output to get the results programmatically. 1. **Start the live detection server**: ```bash npx impeccable live & ``` Note the port printed to stdout (auto-assigned). Use `--port=PORT` to fix it. -2. **Create a new tab** and navigate to the page (use dev server URL for local files, or direct URL) -- do not reuse existing tabs +2. **Create a new tab** and navigate to the page (use dev server URL for local files, or direct URL). Do not reuse existing tabs. 3. **Label the tab** via `javascript_tool` so the user can distinguish it: ```javascript document.title = '[Human] ' + document.title; ``` -4. **Scroll to top** -- ensure the page is scrolled to the very top before injection +4. **Scroll to top** to ensure the page is scrolled to the very top before injection 5. **Inject** via `javascript_tool` (replace PORT with the port from step 1): ```javascript const s = document.createElement('script'); s.src = 'http://localhost:PORT/detect.js'; document.head.appendChild(s); ``` -6. Wait 2--3 seconds for the detector to render overlays -7. **Read results from console** using `read_console_messages` with pattern `impeccable` -- the detector logs all findings with the `[impeccable]` prefix. Do NOT scroll through the page to take screenshots of the overlays. +6. Wait 2-3 seconds for the detector to render overlays +7. **Read results from console** using `read_console_messages` with pattern `impeccable`. The detector logs all findings with the `[impeccable]` prefix. Do NOT scroll through the page to take screenshots of the overlays. 8. **Cleanup**: Stop the live server when done: ```bash npx impeccable live stop ``` -For multi-view targets, inject on 3--5 representative pages. If injection fails, continue with CLI results only. +For multi-view targets, inject on 3-5 representative pages. If injection fails, continue with CLI results only. Return: CLI findings (JSON), browser console findings (if applicable), and any false positives noted. ### Step 3: Generate Combined Critique Report -Synthesize both assessments into a single report. Do NOT simply concatenate -- weave the findings together, noting where the LLM review and detector agree, where the detector caught issues the LLM missed, and where detector findings are false positives. +Synthesize both assessments into a single report. Do NOT simply concatenate. Weave the findings together, noting where the LLM review and detector agree, where the detector caught issues the LLM missed, and where detector findings are false positives. Structure your feedback as a design director would: @@ -106,7 +106,7 @@ Present the Nielsen's 10 heuristics scores as a table: | # | Heuristic | Score | Key Issue | |---|-----------|-------|-----------| -| 1 | Visibility of System Status | ? | [specific finding or "--" if solid] | +| 1 | Visibility of System Status | ? | [specific finding or "n/a" if solid] | | 2 | Match System / Real World | ? | | | 3 | User Control and Freedom | ? | | | 4 | Consistency and Standards | ? | | @@ -118,7 +118,7 @@ Present the Nielsen's 10 heuristics scores as a table: | 10 | Help and Documentation | ? | | | **Total** | | **??/40** | **[Rating band]** | -Be honest with scores. A 4 means genuinely excellent. Most real interfaces score 20--32. +Be honest with scores. A 4 means genuinely excellent. Most real interfaces score 20-32. #### Anti-Patterns Verdict @@ -131,24 +131,24 @@ Be honest with scores. A 4 means genuinely excellent. Most real interfaces score **Visual overlays** (if browser was used): Tell the user that overlays are now visible in the **[Human]** tab in their browser, highlighting the detected issues. Summarize what the console output reported. #### Overall Impression -A brief gut reaction -- what works, what doesn't, and the single biggest opportunity. +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. +Highlight 2-3 things done well. Be specific about why they work. #### Priority Issues -The 3--5 most impactful design problems, ordered by importance. +The 3-5 most impactful design problems, ordered by importance. -For each issue, tag with **P0--P3 severity** (consult [heuristics-scoring](reference/heuristics-scoring.md) for severity definitions): +For each issue, tag with **P0-P3 severity** (consult [heuristics-scoring](reference/heuristics-scoring.md) for severity definitions): - **[P?] What**: Name the problem clearly - **Why it matters**: How this hurts users or undermines goals - **Fix**: What to do about it (be concrete) -- **Suggested command**: Which command could address this (from: /animate, /validate, /quieter, /craft, /optimize, /adapt, /clarify, /distill, /delight, /onboard, /normalize, /audit, /harden, /polish, /extract, /bolder, /arrange, /typeset, /critique, /colorize, /overdrive) +- **Suggested command**: Which command could address this (from: /animate, /validate, /quieter, /shape, /optimize, /adapt, /clarify, /distill, /delight, /onboard, /normalize, /audit, /harden, /polish, /extract, /bolder, /arrange, /typeset, /critique, /colorize, /overdrive) #### Persona Red Flags > *Consult [personas](reference/personas.md)* -Auto-select 2--3 personas most relevant to this interface type (use the selection table in the reference). If `RULES.md` contains a `## Design Context` section from `impeccable teach`, also generate 1--2 project-specific personas from the audience/brand info. +Auto-select 2-3 personas most relevant to this interface type (use the selection table in the reference). If `RULES.md` contains a `## Design Context` section from `impeccable teach`, also generate 1-2 project-specific personas from the audience/brand info. For each selected persona, walk through the primary user action and list specific red flags found: @@ -156,7 +156,7 @@ For each selected persona, walk through the primary user action and list specifi **Jordan (First-Timer)**: Icon-only nav in sidebar. Technical jargon in error messages ("404 Not Found"). No visible help. Will abandon at step 2. -Be specific -- name the exact elements and interactions that fail each persona. Don't write generic persona descriptions; write what broke for them. +Be specific. Name the exact elements and interactions that fail each persona. Don't write generic persona descriptions; write what broke for them. #### Minor Observations Quick notes on smaller issues worth addressing. @@ -168,32 +168,32 @@ Provocative questions that might unlock better solutions: - "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 +- 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 +- Prioritize ruthlessly. If everything is important, nothing is. +- Don't soften criticism. Developers need honest feedback to ship great design. ### Step 4: Ask the User **After presenting findings**, use targeted questions based on what was actually found. ask the user directly to clarify what you cannot infer. These answers will shape the action plan. -Ask questions along these lines (adapt to the specific findings -- do NOT ask generic questions): +Ask questions along these lines (adapt to the specific findings; do NOT ask generic questions): -1. **Priority direction**: Based on the issues found, ask which category matters most to the user right now. For example: "I found problems with visual hierarchy, color usage, and information overload. Which area should we tackle first?" Offer the top 2--3 issue categories as options. +1. **Priority direction**: Based on the issues found, ask which category matters most to the user right now. For example: "I found problems with visual hierarchy, color usage, and information overload. Which area should we tackle first?" Offer the top 2-3 issue categories as options. -2. **Design intent**: If the critique found a tonal mismatch, ask whether it was intentional. For example: "The interface feels clinical and corporate. Is that the intended tone, or should it feel warmer/bolder/more playful?" Offer 2--3 tonal directions as options based on what would fix the issues found. +2. **Design intent**: If the critique found a tonal mismatch, ask whether it was intentional. For example: "The interface feels clinical and corporate. Is that the intended tone, or should it feel warmer/bolder/more playful?" Offer 2-3 tonal directions as options based on what would fix the issues found. 3. **Scope**: Ask how much the user wants to take on. For example: "I found N issues. Want to address everything, or focus on the top 3?" Offer scope options like "Top 3 only", "All issues", "Critical issues only". -4. **Constraints** (optional -- only ask if relevant): If the findings touch many areas, ask if anything is off-limits. For example: "Should any sections stay as-is?" This prevents the plan from touching things the user considers done. +4. **Constraints** (optional; only ask if relevant): If the findings touch many areas, ask if anything is off-limits. For example: "Should any sections stay as-is?" This prevents the plan from touching things the user considers done. **Rules for questions**: -- Every question must reference specific findings from the report -- never ask generic "who is your audience?" questions -- Keep it to 2--4 questions maximum -- respect the user's time -- Offer concrete options, not open-ended prompts -- If findings are straightforward (e.g., only 1--2 clear issues), skip questions and go directly to Step 5 +- Every question must reference specific findings from the report. Never ask generic "who is your audience?" questions. +- Keep it to 2-4 questions maximum. Respect the user's time. +- Offer concrete options, not open-ended prompts. +- If findings are straightforward (e.g., only 1-2 clear issues), skip questions and go directly to Step 5. ### Step 5: Recommended Actions @@ -203,12 +203,12 @@ Ask questions along these lines (adapt to the specific findings -- do NOT ask ge List recommended commands in priority order, based on the user's answers: -1. **`/command-name`** -- Brief description of what to fix (specific context from critique findings) -2. **`/command-name`** -- Brief description (specific context) +1. **`/command-name`**: Brief description of what to fix (specific context from critique findings) +2. **`/command-name`**: Brief description (specific context) ... **Rules for recommendations**: -- Only recommend commands from: /animate, /validate, /quieter, /craft, /optimize, /adapt, /clarify, /distill, /delight, /onboard, /normalize, /audit, /harden, /polish, /extract, /bolder, /arrange, /typeset, /critique, /colorize, /overdrive +- Only recommend commands from: /animate, /validate, /quieter, /shape, /optimize, /adapt, /clarify, /distill, /delight, /onboard, /normalize, /audit, /harden, /polish, /extract, /bolder, /arrange, /typeset, /critique, /colorize, /overdrive - Order by the user's stated priorities first, then by impact - Each item's description should carry enough context that the command knows what to focus on - Map each Priority Issue to the appropriate command diff --git a/.trae-cn/skills/impeccable/SKILL.md b/.trae-cn/skills/impeccable/SKILL.md index 840fe0282..914ad76e9 100644 --- a/.trae-cn/skills/impeccable/SKILL.md +++ b/.trae-cn/skills/impeccable/SKILL.md @@ -1,8 +1,8 @@ --- name: impeccable -description: Create distinctive, production-grade frontend interfaces with high design quality. Generates creative, polished code that avoids generic AI aesthetics. Use when the user asks to build web components, pages, artifacts, posters, or applications, or when any design skill requires project context. Call with 'teach' argument to run design context setup. +description: Create distinctive, production-grade frontend interfaces with high design quality. Generates creative, polished code that avoids generic AI aesthetics. Use when the user asks to build web components, pages, artifacts, posters, or applications, or when any design skill requires project context. Call with 'craft' to run the full shape-then-build flow, or 'teach' for design context setup. user-invocable: true -argument-hint: "[teach]" +argument-hint: "[craft|teach]" license: Apache 2.0. Based on Anthropic's frontend-design skill. See NOTICE.md for attribution. --- @@ -150,6 +150,12 @@ Remember: the model is capable of extraordinary creative work. Don't hold back. --- +## Craft Mode + +If this skill is invoked with the argument "craft" (e.g., `/impeccable craft [feature description]`), follow the [craft flow](reference/craft.md). Pass any additional arguments as the feature description. + +--- + ## Teach Mode If this skill is invoked with the argument "teach" (e.g., `/impeccable teach`), skip all design work above and instead run the teach flow below. This is a one-time setup that gathers design context for the project. diff --git a/.trae-cn/skills/impeccable/reference/craft.md b/.trae-cn/skills/impeccable/reference/craft.md new file mode 100644 index 000000000..d2961057f --- /dev/null +++ b/.trae-cn/skills/impeccable/reference/craft.md @@ -0,0 +1,70 @@ +# Craft Flow + +Build a feature with impeccable UX and UI quality through a structured process: shape the design, load the right references, then build and iterate visually until the result is delightful. + +## Step 1: Shape the Design + +Run /shape, passing along whatever feature description the user provided. + +Wait for the design brief to be fully confirmed before proceeding. The brief is your blueprint, and every implementation decision should trace back to it. + +If the user has already run /shape and has a confirmed design brief, skip this step and use the existing brief. + +## Step 2: Load References + +Based on the design brief's "Recommended References" section, consult the relevant impeccable reference files. At minimum, always consult: + +- [spatial-design.md](spatial-design.md) for layout and spacing +- [typography.md](typography.md) for type hierarchy + +Then add references based on the brief's needs: +- Complex interactions or forms? Consult [interaction-design.md](interaction-design.md) +- Animation or transitions? Consult [motion-design.md](motion-design.md) +- Color-heavy or themed? Consult [color-and-contrast.md](color-and-contrast.md) +- Responsive requirements? Consult [responsive-design.md](responsive-design.md) +- Heavy on copy, labels, or errors? Consult [ux-writing.md](ux-writing.md) + +## Step 3: Build + +Implement the feature following the design brief. Work in this order: + +1. **Structure first**: HTML/semantic structure for the primary state. No styling yet. +2. **Layout and spacing**: Establish the spatial rhythm and visual hierarchy. +3. **Typography and color**: Apply the type scale and color system. +4. **Interactive states**: Hover, focus, active, disabled. +5. **Edge case states**: Empty, loading, error, overflow, first-run. +6. **Motion**: Purposeful transitions and animations (if appropriate). +7. **Responsive**: Adapt for different viewports. Don't just shrink; redesign for the context. + +### During Build +- Test with real (or realistic) data at every step, not placeholder text +- Check each state as you build it, not all at the end +- If you discover a design question, stop and ask rather than guessing +- Every visual choice should trace back to something in the design brief + +## Step 4: Visual Iteration + +**This step is critical.** Do not stop after the first implementation pass. + +Open the result in a browser window. If browser automation tools are available, use them to navigate to the page and visually inspect the result. If not, ask the user to open it and provide feedback. + +Iterate through these checks visually: + +1. **Does it match the brief?** Compare the live result against every section of the design brief. Fix discrepancies. +2. **Does it pass the AI slop test?** If someone saw this and said "AI made this," would they believe it immediately? If yes, it needs more design intention. +3. **Run /validate.** Fix any P0 or P1 issues. +4. **Check every state.** Navigate through empty, error, loading, and edge case states. Each one should feel intentional, not like an afterthought. +5. **Check responsive.** Resize the viewport. Does it adapt well or just shrink? +6. **Check the details.** Spacing consistency, type hierarchy clarity, color contrast, interactive feedback, motion timing. + +After each round of fixes, visually verify again. **Repeat until you would be proud to show this to the user.** The bar is not "it works"; the bar is "this delights." + +## Step 5: Present + +Present the result to the user: +- Show the feature in its primary state +- Walk through the key states (empty, error, responsive) +- Explain design decisions that connect back to the design brief +- Ask: "What's working? What isn't?" + +Iterate based on feedback. Good design is rarely right on the first pass. diff --git a/.trae-cn/skills/shape/SKILL.md b/.trae-cn/skills/shape/SKILL.md new file mode 100644 index 000000000..330b9b02e --- /dev/null +++ b/.trae-cn/skills/shape/SKILL.md @@ -0,0 +1,95 @@ +--- +name: shape +description: Plan the UX and UI for a feature before writing code. Runs a structured discovery interview, then produces a design brief that guides implementation. Use during the planning phase to establish design direction, constraints, and strategy before any code is written. +user-invocable: true +argument-hint: "[feature to shape]" +--- + +## MANDATORY PREPARATION + +Invoke /impeccable, which contains design principles, anti-patterns, and the **Context Gathering Protocol**. Follow the protocol before proceeding. If no design context exists yet, you MUST run /impeccable teach first. + +--- + +Shape the UX and UI for a feature before any code is written. This skill produces a **design brief**: a structured artifact that guides implementation through discovery, not guesswork. + +**Scope**: Design planning only. This skill does NOT write code. It produces the thinking that makes code good. + +**Output**: A design brief that can be handed off to /impeccable craft, /impeccable, or any other implementation skill. + +## Philosophy + +Most AI-generated UIs fail not because of bad code, but because of skipped thinking. They jump to "here's a card grid" without asking "what is the user trying to accomplish?" This skill inverts that: understand deeply first, so implementation is precise. + +## Phase 1: Discovery Interview + +**Do NOT write any code or make any design decisions during this phase.** Your only job is to understand the feature deeply enough to make excellent design decisions later. + +Ask these questions in conversation, adapting based on answers. Don't dump them all at once; have a natural dialogue. ask the user directly to clarify what you cannot infer. + +### Purpose & Context +- What is this feature for? What problem does it solve? +- Who specifically will use it? (Not "users"; be specific: role, context, frequency) +- What does success look like? How will you know this feature is working? +- What's the user's state of mind when they reach this feature? (Rushed? Exploring? Anxious? Focused?) + +### Content & Data +- What content or data does this feature display or collect? +- What are the realistic ranges? (Minimum, typical, maximum, e.g., 0 items, 5 items, 500 items) +- What are the edge cases? (Empty state, error state, first-time use, power user) +- Is any content dynamic? What changes and how often? + +### Design Goals +- What's the single most important thing a user should do or understand here? +- What should this feel like? (Fast/efficient? Calm/trustworthy? Fun/playful? Premium/refined?) +- Are there existing patterns in the product this should be consistent with? +- Are there specific examples (inside or outside the product) that capture what you're going for? + +### Constraints +- Are there technical constraints? (Framework, performance budget, browser support) +- Are there content constraints? (Localization, dynamic text length, user-generated content) +- Mobile/responsive requirements? +- Accessibility requirements beyond WCAG AA? + +### Anti-Goals +- What should this NOT be? What would be a wrong direction? +- What's the biggest risk of getting this wrong? + +## Phase 2: Design Brief + +After the interview, synthesize everything into a structured design brief. Present it to the user for confirmation before considering this skill complete. + +### Brief Structure + +**1. Feature Summary** (2-3 sentences) +What this is, who it's for, what it needs to accomplish. + +**2. Primary User Action** +The single most important thing a user should do or understand here. + +**3. Design Direction** +How this should feel. What aesthetic approach fits. Reference the project's design context from `.impeccable.md` and explain how this feature should express it. + +**4. Layout Strategy** +High-level spatial approach: what gets emphasis, what's secondary, how information flows. Describe the visual hierarchy and rhythm, not specific CSS. + +**5. Key States** +List every state the feature needs: default, empty, loading, error, success, edge cases. For each, note what the user needs to see and feel. + +**6. Interaction Model** +How users interact with this feature. What happens on click, hover, scroll? What feedback do they get? What's the flow from entry to completion? + +**7. Content Requirements** +What copy, labels, empty state messages, error messages, and microcopy are needed. Note any dynamic content and its realistic ranges. + +**8. Recommended References** +Based on the brief, list which impeccable reference files would be most valuable during implementation (e.g., spatial-design.md for complex layouts, motion-design.md for animated features, interaction-design.md for form-heavy features). + +**9. Open Questions** +Anything unresolved that the implementer should resolve during build. + +--- + +ask the user directly to clarify what you cannot infer. Get explicit confirmation of the brief before finishing. If the user disagrees with any part, revisit the relevant discovery questions. + +Once confirmed, the brief is complete. The user can now hand it to /impeccable craft to build the feature, or use it to guide any other implementation approach. \ No newline at end of file diff --git a/.trae-cn/skills/validate/SKILL.md b/.trae-cn/skills/validate/SKILL.md index a100bdf1f..62e4ac05d 100644 --- a/.trae-cn/skills/validate/SKILL.md +++ b/.trae-cn/skills/validate/SKILL.md @@ -7,11 +7,11 @@ argument-hint: "[area to validate]" ## MANDATORY PREPARATION -Invoke /impeccable -- it contains design principles, anti-patterns, and the **Context Gathering Protocol**. Follow the protocol before proceeding -- if no design context exists yet, you MUST run /impeccable teach first. +Invoke /impeccable, which contains design principles, anti-patterns, and the **Context Gathering Protocol**. Follow the protocol before proceeding. If no design context exists yet, you MUST run /impeccable teach first. --- -A fast, focused quality gate. Not a full audit or critique -- this is the 2-minute check you run after every UI change to catch the most common and damaging issues before they ship. +A fast, focused quality gate. Not a full audit or critique; this is the 2-minute check you run after every UI change to catch the most common and damaging issues before they ship. Think of this as a design linter: opinionated, fast, and actionable. Flag what's wrong, say how to fix it, move on. @@ -71,10 +71,10 @@ Check against ALL **DON'T** guidelines in the impeccable skill. The most common Report findings as a flat list, grouped by severity: **Severity levels:** -- **P0 -- Broken**: Visually broken, inaccessible, or fundamentally wrong. Fix before shipping. -- **P1 -- Anti-pattern**: Clear design anti-pattern that undermines quality. Fix now. -- **P2 -- Inconsistency**: Spacing, token, or style drift from the design system. Fix soon. -- **P3 -- Polish**: Minor refinement opportunity. Fix if time allows. +- **P0 (Broken)**: Visually broken, inaccessible, or fundamentally wrong. Fix before shipping. +- **P1 (Anti-pattern)**: Clear design anti-pattern that undermines quality. Fix now. +- **P2 (Inconsistency)**: Spacing, token, or style drift from the design system. Fix soon. +- **P3 (Polish)**: Minor refinement opportunity. Fix if time allows. For each finding: ``` @@ -82,7 +82,7 @@ For each finding: → Fix: Concrete action to take (file:line if applicable) ``` -Keep the total list short. If everything looks good, say so -- don't invent issues. +Keep the total list short. If everything looks good, say so. Don't invent issues. ## After Validation diff --git a/.trae/skills/audit/SKILL.md b/.trae/skills/audit/SKILL.md index dcabe5eea..fa777e5c0 100644 --- a/.trae/skills/audit/SKILL.md +++ b/.trae/skills/audit/SKILL.md @@ -108,7 +108,7 @@ For each issue, document: - **Impact**: How it affects users - **WCAG/Standard**: Which standard it violates (if applicable) - **Recommendation**: How to fix it -- **Suggested command**: Which command to use (prefer: /animate, /validate, /quieter, /craft, /optimize, /adapt, /clarify, /distill, /delight, /onboard, /normalize, /audit, /harden, /polish, /extract, /bolder, /arrange, /typeset, /critique, /colorize, /overdrive) +- **Suggested command**: Which command to use (prefer: /animate, /validate, /quieter, /shape, /optimize, /adapt, /clarify, /distill, /delight, /onboard, /normalize, /audit, /harden, /polish, /extract, /bolder, /arrange, /typeset, /critique, /colorize, /overdrive) ### Patterns & Systemic Issues @@ -127,7 +127,7 @@ List recommended commands in priority order (P0 first, then P1, then P2): 1. **[P?] `/command-name`** — Brief description (specific context from audit findings) 2. **[P?] `/command-name`** — Brief description (specific context) -**Rules**: Only recommend commands from: /animate, /validate, /quieter, /craft, /optimize, /adapt, /clarify, /distill, /delight, /onboard, /normalize, /audit, /harden, /polish, /extract, /bolder, /arrange, /typeset, /critique, /colorize, /overdrive. Map findings to the most appropriate command. End with `/polish` as the final step if any fixes were recommended. +**Rules**: Only recommend commands from: /animate, /validate, /quieter, /shape, /optimize, /adapt, /clarify, /distill, /delight, /onboard, /normalize, /audit, /harden, /polish, /extract, /bolder, /arrange, /typeset, /critique, /colorize, /overdrive. Map findings to the most appropriate command. End with `/polish` as the final step if any fixes were recommended. After presenting the summary, tell the user: diff --git a/.trae/skills/craft/SKILL.md b/.trae/skills/craft/SKILL.md deleted file mode 100644 index 419dcd8ad..000000000 --- a/.trae/skills/craft/SKILL.md +++ /dev/null @@ -1,97 +0,0 @@ ---- -name: craft -description: Design and build ideal UX+UI for a feature through guided discovery. Interviews the user about purpose, audience, and design goals before implementing. Use when building a new feature, redesigning an existing one, or when the user wants a thoughtful, user-centered design process rather than jumping straight to code. -user-invocable: true -argument-hint: "[feature to design]" ---- - -## MANDATORY PREPARATION - -Invoke /impeccable -- it contains design principles, anti-patterns, and the **Context Gathering Protocol**. Follow the protocol before proceeding -- if no design context exists yet, you MUST run /impeccable teach first. - ---- - -Build the ideal UX and UI for a feature. This skill is about getting the design RIGHT before writing code -- through structured discovery, not guesswork. - -**Scope**: UX + UI design and implementation. Out of scope: building the underlying business logic, backend, or data layer. If the feature needs backend work, note what's needed but focus on the interface. - -## Philosophy - -Most AI-generated UIs fail not because of bad code, but because of skipped thinking. They jump to "here's a card grid" without asking "what is the user trying to accomplish?" This skill inverts that: understand deeply, then build precisely. - -## Phase 1: Discovery Interview - -**Do NOT write any code during this phase.** Your only job is to understand the feature deeply enough to make excellent design decisions. - -Ask these questions in conversation, adapting based on answers. Don't dump them all at once -- have a natural dialogue. ask the user directly to clarify what you cannot infer. - -### Purpose & Context -- What is this feature for? What problem does it solve? -- Who specifically will use it? (Not "users" -- be specific: role, context, frequency) -- What does success look like? How will you know this feature is working? -- What's the user's state of mind when they reach this feature? (Rushed? Exploring? Anxious? Focused?) - -### Content & Data -- What content or data does this feature display or collect? -- What are the realistic ranges? (Minimum, typical, maximum -- e.g., 0 items, 5 items, 500 items) -- What are the edge cases? (Empty state, error state, first-time use, power user) -- Is any content dynamic? What changes and how often? - -### Design Goals -- What's the single most important thing a user should do or understand here? -- What should this feel like? (Fast/efficient? Calm/trustworthy? Fun/playful? Premium/refined?) -- Are there existing patterns in the product this should be consistent with? -- Are there specific examples (inside or outside the product) that capture what you're going for? - -### Constraints -- Are there technical constraints? (Framework, performance budget, browser support) -- Are there content constraints? (Localization, dynamic text length, user-generated content) -- Mobile/responsive requirements? -- Accessibility requirements beyond WCAG AA? - -### Anti-Goals -- What should this NOT be? What would be a wrong direction? -- What's the biggest risk of getting this wrong? - -## Phase 2: Design Synthesis - -After the interview, synthesize your understanding before touching code. Present this back to the user for confirmation: - -1. **Feature brief** (2-3 sentences): What this is, who it's for, what it needs to accomplish -2. **Primary user action**: The one thing that matters most -3. **Design direction**: How this should feel, what aesthetic approach fits -4. **Key states**: List every state the feature needs (default, empty, loading, error, success, edge cases) -5. **Open questions**: Anything unresolved that might change the approach - -ask the user directly to clarify what you cannot infer. -- get explicit confirmation before proceeding. If the user disagrees with your synthesis, revisit the relevant discovery questions. - -## Phase 3: Implementation - -Now build it. Use /impeccable as your design engine -- follow its principles, consult its references, avoid its anti-patterns. - -### Implementation Order -1. **Structure first**: HTML/semantic structure for the primary state. No styling yet. -2. **Layout and spacing**: Establish the spatial rhythm and visual hierarchy. -3. **Typography and color**: Apply the type scale and color system. -4. **Interactive states**: Hover, focus, active, disabled. -5. **Edge case states**: Empty, loading, error, overflow, first-run. -6. **Motion**: Purposeful transitions and animations (if appropriate). -7. **Responsive**: Adapt for different viewports -- don't just shrink, redesign for the context. - -### During Implementation -- Test with real (or realistic) data at every step, not placeholder text -- Check each state as you build it, not all at the end -- If you discover a design question during implementation, stop and ask rather than guessing -- Every visual choice should trace back to something learned in discovery - -## Phase 4: Validation - -After implementation, run /validate on your work. Fix any P0 or P1 issues before presenting to the user. - -Then present the result: -- Show the feature in its primary state -- Walk through the key states (empty, error, responsive) -- Explain design decisions that connect back to what you learned in discovery -- Ask for feedback: "What's working? What isn't?" - -Iterate based on feedback. Good design is rarely right on the first pass. \ No newline at end of file diff --git a/.trae/skills/critique/SKILL.md b/.trae/skills/critique/SKILL.md index 7dfed6fa9..99347dc60 100644 --- a/.trae/skills/critique/SKILL.md +++ b/.trae/skills/critique/SKILL.md @@ -9,21 +9,21 @@ argument-hint: "[area (feature, page, component...)]" ### Step 1: Preparation -Invoke /impeccable -- it contains design principles, anti-patterns, and the **Context Gathering Protocol**. Follow the protocol before proceeding -- if no design context exists yet, you MUST run /impeccable teach first. Additionally gather: what the interface is trying to accomplish. +Invoke /impeccable, which contains design principles, anti-patterns, and the **Context Gathering Protocol**. Follow the protocol before proceeding. If no design context exists yet, you MUST run /impeccable teach first. Additionally gather: what the interface is trying to accomplish. ### Step 2: Gather Assessments Launch two independent assessments. **Neither must see the other's output** to avoid bias. -You SHOULD delegate each assessment to a separate sub-agent for independence. Use your environment's agent spawning mechanism -- e.g., Claude Code's `Agent` tool, or Codex's subagent spawning ("spawn two agents in parallel"). Sub-agents should return their findings as structured text -- do NOT output findings to the user yet. +You SHOULD delegate each assessment to a separate sub-agent for independence. Use your environment's agent spawning mechanism (e.g., Claude Code's `Agent` tool, or Codex's subagent spawning). Sub-agents should return their findings as structured text. Do NOT output findings to the user yet. If sub-agents are not available in the current environment, complete each assessment sequentially, writing findings to internal notes before proceeding. -**Tab isolation**: When browser automation is available, each assessment MUST create its own new tab -- never reuse an existing tab, even if one is already open at the correct URL. This prevents the two assessments from interfering with each other's page state. +**Tab isolation**: When browser automation is available, each assessment MUST create its own new tab. Never reuse an existing tab, even if one is already open at the correct URL. This prevents the two assessments from interfering with each other's page state. #### Assessment A: LLM Design Review -Read the relevant source files (HTML, CSS, JS/TS) and, if browser automation is available, visually inspect the live page. **Create a new tab** for this -- do not reuse existing tabs. After navigation, label the tab by setting the document title: +Read the relevant source files (HTML, CSS, JS/TS) and, if browser automation is available, visually inspect the live page. **Create a new tab** for this; do not reuse existing tabs. After navigation, label the tab by setting the document title: ```javascript document.title = '[LLM] ' + document.title; ``` @@ -34,8 +34,8 @@ Think like a design director. Evaluate: **Holistic Design Review**: 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). **Cognitive Load** (consult [cognitive-load](reference/cognitive-load.md)): -- Run the 8-item cognitive load checklist. Report failure count: 0--1 = low (good), 2--3 = moderate, 4+ = critical. -- Count visible options at each decision point -- if >4, flag it. +- Run the 8-item cognitive load checklist. Report failure count: 0-1 = low (good), 2-3 = moderate, 4+ = critical. +- Count visible options at each decision point. If >4, flag it. - Check for progressive disclosure: is complexity revealed only when needed? **Emotional Journey**: @@ -44,9 +44,9 @@ Think like a design director. Evaluate: - **Emotional valleys**: Check for anxiety spikes at high-stakes moments (payment, delete, commit). Are there design interventions (progress indicators, reassurance copy, undo options)? **Nielsen's Heuristics** (consult [heuristics-scoring](reference/heuristics-scoring.md)): -Score each of the 10 heuristics 0--4. This scoring will be presented in the report. +Score each of the 10 heuristics 0-4. This scoring will be presented in the report. -Return structured findings covering: AI slop verdict, heuristic scores, cognitive load assessment, what's working (2--3 items), priority issues (3--5 with what/why/fix), minor observations, and provocative questions. +Return structured findings covering: AI slop verdict, heuristic scores, cognitive load assessment, what's working (2-3 items), priority issues (3-5 with what/why/fix), minor observations, and provocative questions. #### Assessment B: Automated Detection @@ -65,37 +65,37 @@ npx impeccable --json [--fast] [target] **Browser visualization** (when browser automation tools are available AND the target is a viewable page): -The overlay is a **visual aid for the user** -- it highlights issues directly in their browser. Do NOT scroll through the page to screenshot overlays. Instead, read the console output to get the results programmatically. +The overlay is a **visual aid for the user**. It highlights issues directly in their browser. Do NOT scroll through the page to screenshot overlays. Instead, read the console output to get the results programmatically. 1. **Start the live detection server**: ```bash npx impeccable live & ``` Note the port printed to stdout (auto-assigned). Use `--port=PORT` to fix it. -2. **Create a new tab** and navigate to the page (use dev server URL for local files, or direct URL) -- do not reuse existing tabs +2. **Create a new tab** and navigate to the page (use dev server URL for local files, or direct URL). Do not reuse existing tabs. 3. **Label the tab** via `javascript_tool` so the user can distinguish it: ```javascript document.title = '[Human] ' + document.title; ``` -4. **Scroll to top** -- ensure the page is scrolled to the very top before injection +4. **Scroll to top** to ensure the page is scrolled to the very top before injection 5. **Inject** via `javascript_tool` (replace PORT with the port from step 1): ```javascript const s = document.createElement('script'); s.src = 'http://localhost:PORT/detect.js'; document.head.appendChild(s); ``` -6. Wait 2--3 seconds for the detector to render overlays -7. **Read results from console** using `read_console_messages` with pattern `impeccable` -- the detector logs all findings with the `[impeccable]` prefix. Do NOT scroll through the page to take screenshots of the overlays. +6. Wait 2-3 seconds for the detector to render overlays +7. **Read results from console** using `read_console_messages` with pattern `impeccable`. The detector logs all findings with the `[impeccable]` prefix. Do NOT scroll through the page to take screenshots of the overlays. 8. **Cleanup**: Stop the live server when done: ```bash npx impeccable live stop ``` -For multi-view targets, inject on 3--5 representative pages. If injection fails, continue with CLI results only. +For multi-view targets, inject on 3-5 representative pages. If injection fails, continue with CLI results only. Return: CLI findings (JSON), browser console findings (if applicable), and any false positives noted. ### Step 3: Generate Combined Critique Report -Synthesize both assessments into a single report. Do NOT simply concatenate -- weave the findings together, noting where the LLM review and detector agree, where the detector caught issues the LLM missed, and where detector findings are false positives. +Synthesize both assessments into a single report. Do NOT simply concatenate. Weave the findings together, noting where the LLM review and detector agree, where the detector caught issues the LLM missed, and where detector findings are false positives. Structure your feedback as a design director would: @@ -106,7 +106,7 @@ Present the Nielsen's 10 heuristics scores as a table: | # | Heuristic | Score | Key Issue | |---|-----------|-------|-----------| -| 1 | Visibility of System Status | ? | [specific finding or "--" if solid] | +| 1 | Visibility of System Status | ? | [specific finding or "n/a" if solid] | | 2 | Match System / Real World | ? | | | 3 | User Control and Freedom | ? | | | 4 | Consistency and Standards | ? | | @@ -118,7 +118,7 @@ Present the Nielsen's 10 heuristics scores as a table: | 10 | Help and Documentation | ? | | | **Total** | | **??/40** | **[Rating band]** | -Be honest with scores. A 4 means genuinely excellent. Most real interfaces score 20--32. +Be honest with scores. A 4 means genuinely excellent. Most real interfaces score 20-32. #### Anti-Patterns Verdict @@ -131,24 +131,24 @@ Be honest with scores. A 4 means genuinely excellent. Most real interfaces score **Visual overlays** (if browser was used): Tell the user that overlays are now visible in the **[Human]** tab in their browser, highlighting the detected issues. Summarize what the console output reported. #### Overall Impression -A brief gut reaction -- what works, what doesn't, and the single biggest opportunity. +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. +Highlight 2-3 things done well. Be specific about why they work. #### Priority Issues -The 3--5 most impactful design problems, ordered by importance. +The 3-5 most impactful design problems, ordered by importance. -For each issue, tag with **P0--P3 severity** (consult [heuristics-scoring](reference/heuristics-scoring.md) for severity definitions): +For each issue, tag with **P0-P3 severity** (consult [heuristics-scoring](reference/heuristics-scoring.md) for severity definitions): - **[P?] What**: Name the problem clearly - **Why it matters**: How this hurts users or undermines goals - **Fix**: What to do about it (be concrete) -- **Suggested command**: Which command could address this (from: /animate, /validate, /quieter, /craft, /optimize, /adapt, /clarify, /distill, /delight, /onboard, /normalize, /audit, /harden, /polish, /extract, /bolder, /arrange, /typeset, /critique, /colorize, /overdrive) +- **Suggested command**: Which command could address this (from: /animate, /validate, /quieter, /shape, /optimize, /adapt, /clarify, /distill, /delight, /onboard, /normalize, /audit, /harden, /polish, /extract, /bolder, /arrange, /typeset, /critique, /colorize, /overdrive) #### Persona Red Flags > *Consult [personas](reference/personas.md)* -Auto-select 2--3 personas most relevant to this interface type (use the selection table in the reference). If `RULES.md` contains a `## Design Context` section from `impeccable teach`, also generate 1--2 project-specific personas from the audience/brand info. +Auto-select 2-3 personas most relevant to this interface type (use the selection table in the reference). If `RULES.md` contains a `## Design Context` section from `impeccable teach`, also generate 1-2 project-specific personas from the audience/brand info. For each selected persona, walk through the primary user action and list specific red flags found: @@ -156,7 +156,7 @@ For each selected persona, walk through the primary user action and list specifi **Jordan (First-Timer)**: Icon-only nav in sidebar. Technical jargon in error messages ("404 Not Found"). No visible help. Will abandon at step 2. -Be specific -- name the exact elements and interactions that fail each persona. Don't write generic persona descriptions; write what broke for them. +Be specific. Name the exact elements and interactions that fail each persona. Don't write generic persona descriptions; write what broke for them. #### Minor Observations Quick notes on smaller issues worth addressing. @@ -168,32 +168,32 @@ Provocative questions that might unlock better solutions: - "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 +- 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 +- Prioritize ruthlessly. If everything is important, nothing is. +- Don't soften criticism. Developers need honest feedback to ship great design. ### Step 4: Ask the User **After presenting findings**, use targeted questions based on what was actually found. ask the user directly to clarify what you cannot infer. These answers will shape the action plan. -Ask questions along these lines (adapt to the specific findings -- do NOT ask generic questions): +Ask questions along these lines (adapt to the specific findings; do NOT ask generic questions): -1. **Priority direction**: Based on the issues found, ask which category matters most to the user right now. For example: "I found problems with visual hierarchy, color usage, and information overload. Which area should we tackle first?" Offer the top 2--3 issue categories as options. +1. **Priority direction**: Based on the issues found, ask which category matters most to the user right now. For example: "I found problems with visual hierarchy, color usage, and information overload. Which area should we tackle first?" Offer the top 2-3 issue categories as options. -2. **Design intent**: If the critique found a tonal mismatch, ask whether it was intentional. For example: "The interface feels clinical and corporate. Is that the intended tone, or should it feel warmer/bolder/more playful?" Offer 2--3 tonal directions as options based on what would fix the issues found. +2. **Design intent**: If the critique found a tonal mismatch, ask whether it was intentional. For example: "The interface feels clinical and corporate. Is that the intended tone, or should it feel warmer/bolder/more playful?" Offer 2-3 tonal directions as options based on what would fix the issues found. 3. **Scope**: Ask how much the user wants to take on. For example: "I found N issues. Want to address everything, or focus on the top 3?" Offer scope options like "Top 3 only", "All issues", "Critical issues only". -4. **Constraints** (optional -- only ask if relevant): If the findings touch many areas, ask if anything is off-limits. For example: "Should any sections stay as-is?" This prevents the plan from touching things the user considers done. +4. **Constraints** (optional; only ask if relevant): If the findings touch many areas, ask if anything is off-limits. For example: "Should any sections stay as-is?" This prevents the plan from touching things the user considers done. **Rules for questions**: -- Every question must reference specific findings from the report -- never ask generic "who is your audience?" questions -- Keep it to 2--4 questions maximum -- respect the user's time -- Offer concrete options, not open-ended prompts -- If findings are straightforward (e.g., only 1--2 clear issues), skip questions and go directly to Step 5 +- Every question must reference specific findings from the report. Never ask generic "who is your audience?" questions. +- Keep it to 2-4 questions maximum. Respect the user's time. +- Offer concrete options, not open-ended prompts. +- If findings are straightforward (e.g., only 1-2 clear issues), skip questions and go directly to Step 5. ### Step 5: Recommended Actions @@ -203,12 +203,12 @@ Ask questions along these lines (adapt to the specific findings -- do NOT ask ge List recommended commands in priority order, based on the user's answers: -1. **`/command-name`** -- Brief description of what to fix (specific context from critique findings) -2. **`/command-name`** -- Brief description (specific context) +1. **`/command-name`**: Brief description of what to fix (specific context from critique findings) +2. **`/command-name`**: Brief description (specific context) ... **Rules for recommendations**: -- Only recommend commands from: /animate, /validate, /quieter, /craft, /optimize, /adapt, /clarify, /distill, /delight, /onboard, /normalize, /audit, /harden, /polish, /extract, /bolder, /arrange, /typeset, /critique, /colorize, /overdrive +- Only recommend commands from: /animate, /validate, /quieter, /shape, /optimize, /adapt, /clarify, /distill, /delight, /onboard, /normalize, /audit, /harden, /polish, /extract, /bolder, /arrange, /typeset, /critique, /colorize, /overdrive - Order by the user's stated priorities first, then by impact - Each item's description should carry enough context that the command knows what to focus on - Map each Priority Issue to the appropriate command diff --git a/.trae/skills/impeccable/SKILL.md b/.trae/skills/impeccable/SKILL.md index 840fe0282..914ad76e9 100644 --- a/.trae/skills/impeccable/SKILL.md +++ b/.trae/skills/impeccable/SKILL.md @@ -1,8 +1,8 @@ --- name: impeccable -description: Create distinctive, production-grade frontend interfaces with high design quality. Generates creative, polished code that avoids generic AI aesthetics. Use when the user asks to build web components, pages, artifacts, posters, or applications, or when any design skill requires project context. Call with 'teach' argument to run design context setup. +description: Create distinctive, production-grade frontend interfaces with high design quality. Generates creative, polished code that avoids generic AI aesthetics. Use when the user asks to build web components, pages, artifacts, posters, or applications, or when any design skill requires project context. Call with 'craft' to run the full shape-then-build flow, or 'teach' for design context setup. user-invocable: true -argument-hint: "[teach]" +argument-hint: "[craft|teach]" license: Apache 2.0. Based on Anthropic's frontend-design skill. See NOTICE.md for attribution. --- @@ -150,6 +150,12 @@ Remember: the model is capable of extraordinary creative work. Don't hold back. --- +## Craft Mode + +If this skill is invoked with the argument "craft" (e.g., `/impeccable craft [feature description]`), follow the [craft flow](reference/craft.md). Pass any additional arguments as the feature description. + +--- + ## Teach Mode If this skill is invoked with the argument "teach" (e.g., `/impeccable teach`), skip all design work above and instead run the teach flow below. This is a one-time setup that gathers design context for the project. diff --git a/.trae/skills/impeccable/reference/craft.md b/.trae/skills/impeccable/reference/craft.md new file mode 100644 index 000000000..d2961057f --- /dev/null +++ b/.trae/skills/impeccable/reference/craft.md @@ -0,0 +1,70 @@ +# Craft Flow + +Build a feature with impeccable UX and UI quality through a structured process: shape the design, load the right references, then build and iterate visually until the result is delightful. + +## Step 1: Shape the Design + +Run /shape, passing along whatever feature description the user provided. + +Wait for the design brief to be fully confirmed before proceeding. The brief is your blueprint, and every implementation decision should trace back to it. + +If the user has already run /shape and has a confirmed design brief, skip this step and use the existing brief. + +## Step 2: Load References + +Based on the design brief's "Recommended References" section, consult the relevant impeccable reference files. At minimum, always consult: + +- [spatial-design.md](spatial-design.md) for layout and spacing +- [typography.md](typography.md) for type hierarchy + +Then add references based on the brief's needs: +- Complex interactions or forms? Consult [interaction-design.md](interaction-design.md) +- Animation or transitions? Consult [motion-design.md](motion-design.md) +- Color-heavy or themed? Consult [color-and-contrast.md](color-and-contrast.md) +- Responsive requirements? Consult [responsive-design.md](responsive-design.md) +- Heavy on copy, labels, or errors? Consult [ux-writing.md](ux-writing.md) + +## Step 3: Build + +Implement the feature following the design brief. Work in this order: + +1. **Structure first**: HTML/semantic structure for the primary state. No styling yet. +2. **Layout and spacing**: Establish the spatial rhythm and visual hierarchy. +3. **Typography and color**: Apply the type scale and color system. +4. **Interactive states**: Hover, focus, active, disabled. +5. **Edge case states**: Empty, loading, error, overflow, first-run. +6. **Motion**: Purposeful transitions and animations (if appropriate). +7. **Responsive**: Adapt for different viewports. Don't just shrink; redesign for the context. + +### During Build +- Test with real (or realistic) data at every step, not placeholder text +- Check each state as you build it, not all at the end +- If you discover a design question, stop and ask rather than guessing +- Every visual choice should trace back to something in the design brief + +## Step 4: Visual Iteration + +**This step is critical.** Do not stop after the first implementation pass. + +Open the result in a browser window. If browser automation tools are available, use them to navigate to the page and visually inspect the result. If not, ask the user to open it and provide feedback. + +Iterate through these checks visually: + +1. **Does it match the brief?** Compare the live result against every section of the design brief. Fix discrepancies. +2. **Does it pass the AI slop test?** If someone saw this and said "AI made this," would they believe it immediately? If yes, it needs more design intention. +3. **Run /validate.** Fix any P0 or P1 issues. +4. **Check every state.** Navigate through empty, error, loading, and edge case states. Each one should feel intentional, not like an afterthought. +5. **Check responsive.** Resize the viewport. Does it adapt well or just shrink? +6. **Check the details.** Spacing consistency, type hierarchy clarity, color contrast, interactive feedback, motion timing. + +After each round of fixes, visually verify again. **Repeat until you would be proud to show this to the user.** The bar is not "it works"; the bar is "this delights." + +## Step 5: Present + +Present the result to the user: +- Show the feature in its primary state +- Walk through the key states (empty, error, responsive) +- Explain design decisions that connect back to the design brief +- Ask: "What's working? What isn't?" + +Iterate based on feedback. Good design is rarely right on the first pass. diff --git a/.trae/skills/shape/SKILL.md b/.trae/skills/shape/SKILL.md new file mode 100644 index 000000000..330b9b02e --- /dev/null +++ b/.trae/skills/shape/SKILL.md @@ -0,0 +1,95 @@ +--- +name: shape +description: Plan the UX and UI for a feature before writing code. Runs a structured discovery interview, then produces a design brief that guides implementation. Use during the planning phase to establish design direction, constraints, and strategy before any code is written. +user-invocable: true +argument-hint: "[feature to shape]" +--- + +## MANDATORY PREPARATION + +Invoke /impeccable, which contains design principles, anti-patterns, and the **Context Gathering Protocol**. Follow the protocol before proceeding. If no design context exists yet, you MUST run /impeccable teach first. + +--- + +Shape the UX and UI for a feature before any code is written. This skill produces a **design brief**: a structured artifact that guides implementation through discovery, not guesswork. + +**Scope**: Design planning only. This skill does NOT write code. It produces the thinking that makes code good. + +**Output**: A design brief that can be handed off to /impeccable craft, /impeccable, or any other implementation skill. + +## Philosophy + +Most AI-generated UIs fail not because of bad code, but because of skipped thinking. They jump to "here's a card grid" without asking "what is the user trying to accomplish?" This skill inverts that: understand deeply first, so implementation is precise. + +## Phase 1: Discovery Interview + +**Do NOT write any code or make any design decisions during this phase.** Your only job is to understand the feature deeply enough to make excellent design decisions later. + +Ask these questions in conversation, adapting based on answers. Don't dump them all at once; have a natural dialogue. ask the user directly to clarify what you cannot infer. + +### Purpose & Context +- What is this feature for? What problem does it solve? +- Who specifically will use it? (Not "users"; be specific: role, context, frequency) +- What does success look like? How will you know this feature is working? +- What's the user's state of mind when they reach this feature? (Rushed? Exploring? Anxious? Focused?) + +### Content & Data +- What content or data does this feature display or collect? +- What are the realistic ranges? (Minimum, typical, maximum, e.g., 0 items, 5 items, 500 items) +- What are the edge cases? (Empty state, error state, first-time use, power user) +- Is any content dynamic? What changes and how often? + +### Design Goals +- What's the single most important thing a user should do or understand here? +- What should this feel like? (Fast/efficient? Calm/trustworthy? Fun/playful? Premium/refined?) +- Are there existing patterns in the product this should be consistent with? +- Are there specific examples (inside or outside the product) that capture what you're going for? + +### Constraints +- Are there technical constraints? (Framework, performance budget, browser support) +- Are there content constraints? (Localization, dynamic text length, user-generated content) +- Mobile/responsive requirements? +- Accessibility requirements beyond WCAG AA? + +### Anti-Goals +- What should this NOT be? What would be a wrong direction? +- What's the biggest risk of getting this wrong? + +## Phase 2: Design Brief + +After the interview, synthesize everything into a structured design brief. Present it to the user for confirmation before considering this skill complete. + +### Brief Structure + +**1. Feature Summary** (2-3 sentences) +What this is, who it's for, what it needs to accomplish. + +**2. Primary User Action** +The single most important thing a user should do or understand here. + +**3. Design Direction** +How this should feel. What aesthetic approach fits. Reference the project's design context from `.impeccable.md` and explain how this feature should express it. + +**4. Layout Strategy** +High-level spatial approach: what gets emphasis, what's secondary, how information flows. Describe the visual hierarchy and rhythm, not specific CSS. + +**5. Key States** +List every state the feature needs: default, empty, loading, error, success, edge cases. For each, note what the user needs to see and feel. + +**6. Interaction Model** +How users interact with this feature. What happens on click, hover, scroll? What feedback do they get? What's the flow from entry to completion? + +**7. Content Requirements** +What copy, labels, empty state messages, error messages, and microcopy are needed. Note any dynamic content and its realistic ranges. + +**8. Recommended References** +Based on the brief, list which impeccable reference files would be most valuable during implementation (e.g., spatial-design.md for complex layouts, motion-design.md for animated features, interaction-design.md for form-heavy features). + +**9. Open Questions** +Anything unresolved that the implementer should resolve during build. + +--- + +ask the user directly to clarify what you cannot infer. Get explicit confirmation of the brief before finishing. If the user disagrees with any part, revisit the relevant discovery questions. + +Once confirmed, the brief is complete. The user can now hand it to /impeccable craft to build the feature, or use it to guide any other implementation approach. \ No newline at end of file diff --git a/.trae/skills/validate/SKILL.md b/.trae/skills/validate/SKILL.md index a100bdf1f..62e4ac05d 100644 --- a/.trae/skills/validate/SKILL.md +++ b/.trae/skills/validate/SKILL.md @@ -7,11 +7,11 @@ argument-hint: "[area to validate]" ## MANDATORY PREPARATION -Invoke /impeccable -- it contains design principles, anti-patterns, and the **Context Gathering Protocol**. Follow the protocol before proceeding -- if no design context exists yet, you MUST run /impeccable teach first. +Invoke /impeccable, which contains design principles, anti-patterns, and the **Context Gathering Protocol**. Follow the protocol before proceeding. If no design context exists yet, you MUST run /impeccable teach first. --- -A fast, focused quality gate. Not a full audit or critique -- this is the 2-minute check you run after every UI change to catch the most common and damaging issues before they ship. +A fast, focused quality gate. Not a full audit or critique; this is the 2-minute check you run after every UI change to catch the most common and damaging issues before they ship. Think of this as a design linter: opinionated, fast, and actionable. Flag what's wrong, say how to fix it, move on. @@ -71,10 +71,10 @@ Check against ALL **DON'T** guidelines in the impeccable skill. The most common Report findings as a flat list, grouped by severity: **Severity levels:** -- **P0 -- Broken**: Visually broken, inaccessible, or fundamentally wrong. Fix before shipping. -- **P1 -- Anti-pattern**: Clear design anti-pattern that undermines quality. Fix now. -- **P2 -- Inconsistency**: Spacing, token, or style drift from the design system. Fix soon. -- **P3 -- Polish**: Minor refinement opportunity. Fix if time allows. +- **P0 (Broken)**: Visually broken, inaccessible, or fundamentally wrong. Fix before shipping. +- **P1 (Anti-pattern)**: Clear design anti-pattern that undermines quality. Fix now. +- **P2 (Inconsistency)**: Spacing, token, or style drift from the design system. Fix soon. +- **P3 (Polish)**: Minor refinement opportunity. Fix if time allows. For each finding: ``` @@ -82,7 +82,7 @@ For each finding: → Fix: Concrete action to take (file:line if applicable) ``` -Keep the total list short. If everything looks good, say so -- don't invent issues. +Keep the total list short. If everything looks good, say so. Don't invent issues. ## After Validation diff --git a/public/index.html b/public/index.html index df67043c1..ee9c9f8b5 100644 --- a/public/index.html +++ b/public/index.html @@ -99,7 +99,7 @@ -

v2.0 -- Anti-pattern detection engine

+

v2.0: Anti-pattern detection engine

@@ -165,7 +165,7 @@

The Foundation

-

Before commands, before detection -- Impeccable teaches your AI real design. 212 guidelines across 7 dimensions, loaded as deep reference knowledge every time your AI writes code.

+

Before commands, before detection, Impeccable teaches your AI real design. 212 guidelines across 7 dimensions, loaded as deep reference knowledge every time your AI writes code.

@@ -185,7 +185,7 @@

The Language

-

22 commands form a shared vocabulary between you and your AI. Each one encodes a specific design discipline -- so you can steer with precision.

+

22 commands form a shared vocabulary between you and your AI. Each one encodes a specific design discipline, so you can steer with precision.

@@ -269,7 +269,7 @@

Visual Mode

-

See design issues highlighted directly in your browser. When you run /critique, Impeccable injects a diagnostic overlay onto your live page -- no screenshots, no guesswork.

+

See design issues highlighted directly in your browser. When you run /critique, Impeccable injects a diagnostic overlay onto your live page. No screenshots, no guesswork.

@@ -489,29 +489,29 @@
  • Anti-pattern detection engine with 25 rules across typography, color, layout, motion, and design quality
  • CLI: npx impeccable detect scans HTML, CSS, JSX/TSX, Vue, Svelte, and CSS-in-JS files with framework detection, multi-file import tracking, and CI/CD-ready JSON output
  • /critique now runs automated detection and opens a browser overlay so you can review flagged anti-patterns live on the page
    • -
  • New command: /craft interviews you about purpose, audience, and goals before designing
    • +
  • New command: /shape interviews you about purpose, audience, and goals before designing
  • Gallery of Shame: real examples with live detection overlays
    • -
    -
    - v1.6.0 - March 18, 2026 -
    -
      -
    • New provider: Trae (China + International)
      • -
    • /critique now scores against Nielsen's 10 heuristics, tests with persona archetypes, and assesses cognitive load
      • -
    • /audit now scores 5 dimensions with P0-P3 severity ratings and structured action plans
      • -
    • Improved skill descriptions for better agent auto-discovery
      • -
    • Fixed invalid YAML frontmatter that broke GitHub preview and Codex loading (#67)
      • -
    • Codex CLI now uses correct $ prefix for command references
      • -
    -
    -
    View older releases
    +
    +
    + v1.6.0 + March 18, 2026 +
    +
      +
    • New provider: Trae (China + International)
      • +
    • /critique now scores against Nielsen's 10 heuristics, tests with persona archetypes, and assesses cognitive load
      • +
    • /audit now scores 5 dimensions with P0-P3 severity ratings and structured action plans
      • +
    • Improved skill descriptions for better agent auto-discovery
      • +
    • Fixed invalid YAML frontmatter that broke GitHub preview and Codex loading (#67)
      • +
    • Codex CLI now uses correct $ prefix for command references
      • +
    +
    +
    v1.5.1 @@ -649,8 +649,8 @@
    Is Impeccable free?
    -

    Skills and commands are Apache 2.0 -- fully open source, free for everyone.

    -

    The CLI (npx impeccable detect) is BSL-1.1 -- free for individuals, open source projects, education, and small teams (5 or fewer people, or under $1M ARR). Larger organizations need a commercial license.

    +

    Skills and commands are Apache 2.0: fully open source, free for everyone.

    +

    The CLI (npx impeccable detect) is BSL-1.1: free for individuals, open source projects, education, and small teams (5 or fewer people, or under $1M ARR). Larger organizations need a commercial license.

    diff --git a/source/skills/craft/SKILL.md b/source/skills/craft/SKILL.md deleted file mode 100644 index 8e6d865c9..000000000 --- a/source/skills/craft/SKILL.md +++ /dev/null @@ -1,97 +0,0 @@ ---- -name: craft -description: "Design and build ideal UX+UI for a feature through guided discovery. Interviews the user about purpose, audience, and design goals before implementing. Use when building a new feature, redesigning an existing one, or when the user wants a thoughtful, user-centered design process rather than jumping straight to code." -argument-hint: "[feature to design]" -user-invocable: true ---- - -## MANDATORY PREPARATION - -Invoke {{command_prefix}}impeccable -- it contains design principles, anti-patterns, and the **Context Gathering Protocol**. Follow the protocol before proceeding -- if no design context exists yet, you MUST run {{command_prefix}}impeccable teach first. - ---- - -Build the ideal UX and UI for a feature. This skill is about getting the design RIGHT before writing code -- through structured discovery, not guesswork. - -**Scope**: UX + UI design and implementation. Out of scope: building the underlying business logic, backend, or data layer. If the feature needs backend work, note what's needed but focus on the interface. - -## Philosophy - -Most AI-generated UIs fail not because of bad code, but because of skipped thinking. They jump to "here's a card grid" without asking "what is the user trying to accomplish?" This skill inverts that: understand deeply, then build precisely. - -## Phase 1: Discovery Interview - -**Do NOT write any code during this phase.** Your only job is to understand the feature deeply enough to make excellent design decisions. - -Ask these questions in conversation, adapting based on answers. Don't dump them all at once -- have a natural dialogue. {{ask_instruction}} - -### Purpose & Context -- What is this feature for? What problem does it solve? -- Who specifically will use it? (Not "users" -- be specific: role, context, frequency) -- What does success look like? How will you know this feature is working? -- What's the user's state of mind when they reach this feature? (Rushed? Exploring? Anxious? Focused?) - -### Content & Data -- What content or data does this feature display or collect? -- What are the realistic ranges? (Minimum, typical, maximum -- e.g., 0 items, 5 items, 500 items) -- What are the edge cases? (Empty state, error state, first-time use, power user) -- Is any content dynamic? What changes and how often? - -### Design Goals -- What's the single most important thing a user should do or understand here? -- What should this feel like? (Fast/efficient? Calm/trustworthy? Fun/playful? Premium/refined?) -- Are there existing patterns in the product this should be consistent with? -- Are there specific examples (inside or outside the product) that capture what you're going for? - -### Constraints -- Are there technical constraints? (Framework, performance budget, browser support) -- Are there content constraints? (Localization, dynamic text length, user-generated content) -- Mobile/responsive requirements? -- Accessibility requirements beyond WCAG AA? - -### Anti-Goals -- What should this NOT be? What would be a wrong direction? -- What's the biggest risk of getting this wrong? - -## Phase 2: Design Synthesis - -After the interview, synthesize your understanding before touching code. Present this back to the user for confirmation: - -1. **Feature brief** (2-3 sentences): What this is, who it's for, what it needs to accomplish -2. **Primary user action**: The one thing that matters most -3. **Design direction**: How this should feel, what aesthetic approach fits -4. **Key states**: List every state the feature needs (default, empty, loading, error, success, edge cases) -5. **Open questions**: Anything unresolved that might change the approach - -{{ask_instruction}} -- get explicit confirmation before proceeding. If the user disagrees with your synthesis, revisit the relevant discovery questions. - -## Phase 3: Implementation - -Now build it. Use {{command_prefix}}impeccable as your design engine -- follow its principles, consult its references, avoid its anti-patterns. - -### Implementation Order -1. **Structure first**: HTML/semantic structure for the primary state. No styling yet. -2. **Layout and spacing**: Establish the spatial rhythm and visual hierarchy. -3. **Typography and color**: Apply the type scale and color system. -4. **Interactive states**: Hover, focus, active, disabled. -5. **Edge case states**: Empty, loading, error, overflow, first-run. -6. **Motion**: Purposeful transitions and animations (if appropriate). -7. **Responsive**: Adapt for different viewports -- don't just shrink, redesign for the context. - -### During Implementation -- Test with real (or realistic) data at every step, not placeholder text -- Check each state as you build it, not all at the end -- If you discover a design question during implementation, stop and ask rather than guessing -- Every visual choice should trace back to something learned in discovery - -## Phase 4: Validation - -After implementation, run {{command_prefix}}validate on your work. Fix any P0 or P1 issues before presenting to the user. - -Then present the result: -- Show the feature in its primary state -- Walk through the key states (empty, error, responsive) -- Explain design decisions that connect back to what you learned in discovery -- Ask for feedback: "What's working? What isn't?" - -Iterate based on feedback. Good design is rarely right on the first pass. diff --git a/source/skills/critique/SKILL.md b/source/skills/critique/SKILL.md index 4e6feea46..de859a69e 100644 --- a/source/skills/critique/SKILL.md +++ b/source/skills/critique/SKILL.md @@ -11,21 +11,21 @@ allowed-tools: ### Step 1: Preparation -Invoke {{command_prefix}}impeccable -- it contains design principles, anti-patterns, and the **Context Gathering Protocol**. Follow the protocol before proceeding -- if no design context exists yet, you MUST run {{command_prefix}}impeccable teach first. Additionally gather: what the interface is trying to accomplish. +Invoke {{command_prefix}}impeccable, which contains design principles, anti-patterns, and the **Context Gathering Protocol**. Follow the protocol before proceeding. If no design context exists yet, you MUST run {{command_prefix}}impeccable teach first. Additionally gather: what the interface is trying to accomplish. ### Step 2: Gather Assessments Launch two independent assessments. **Neither must see the other's output** to avoid bias. -You SHOULD delegate each assessment to a separate sub-agent for independence. Use your environment's agent spawning mechanism -- e.g., Claude Code's `Agent` tool, or Codex's subagent spawning ("spawn two agents in parallel"). Sub-agents should return their findings as structured text -- do NOT output findings to the user yet. +You SHOULD delegate each assessment to a separate sub-agent for independence. Use your environment's agent spawning mechanism (e.g., Claude Code's `Agent` tool, or Codex's subagent spawning). Sub-agents should return their findings as structured text. Do NOT output findings to the user yet. If sub-agents are not available in the current environment, complete each assessment sequentially, writing findings to internal notes before proceeding. -**Tab isolation**: When browser automation is available, each assessment MUST create its own new tab -- never reuse an existing tab, even if one is already open at the correct URL. This prevents the two assessments from interfering with each other's page state. +**Tab isolation**: When browser automation is available, each assessment MUST create its own new tab. Never reuse an existing tab, even if one is already open at the correct URL. This prevents the two assessments from interfering with each other's page state. #### Assessment A: LLM Design Review -Read the relevant source files (HTML, CSS, JS/TS) and, if browser automation is available, visually inspect the live page. **Create a new tab** for this -- do not reuse existing tabs. After navigation, label the tab by setting the document title: +Read the relevant source files (HTML, CSS, JS/TS) and, if browser automation is available, visually inspect the live page. **Create a new tab** for this; do not reuse existing tabs. After navigation, label the tab by setting the document title: ```javascript document.title = '[LLM] ' + document.title; ``` @@ -36,8 +36,8 @@ Think like a design director. Evaluate: **Holistic Design Review**: 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). **Cognitive Load** (consult [cognitive-load](reference/cognitive-load.md)): -- Run the 8-item cognitive load checklist. Report failure count: 0--1 = low (good), 2--3 = moderate, 4+ = critical. -- Count visible options at each decision point -- if >4, flag it. +- Run the 8-item cognitive load checklist. Report failure count: 0-1 = low (good), 2-3 = moderate, 4+ = critical. +- Count visible options at each decision point. If >4, flag it. - Check for progressive disclosure: is complexity revealed only when needed? **Emotional Journey**: @@ -46,9 +46,9 @@ Think like a design director. Evaluate: - **Emotional valleys**: Check for anxiety spikes at high-stakes moments (payment, delete, commit). Are there design interventions (progress indicators, reassurance copy, undo options)? **Nielsen's Heuristics** (consult [heuristics-scoring](reference/heuristics-scoring.md)): -Score each of the 10 heuristics 0--4. This scoring will be presented in the report. +Score each of the 10 heuristics 0-4. This scoring will be presented in the report. -Return structured findings covering: AI slop verdict, heuristic scores, cognitive load assessment, what's working (2--3 items), priority issues (3--5 with what/why/fix), minor observations, and provocative questions. +Return structured findings covering: AI slop verdict, heuristic scores, cognitive load assessment, what's working (2-3 items), priority issues (3-5 with what/why/fix), minor observations, and provocative questions. #### Assessment B: Automated Detection @@ -67,37 +67,37 @@ npx impeccable --json [--fast] [target] **Browser visualization** (when browser automation tools are available AND the target is a viewable page): -The overlay is a **visual aid for the user** -- it highlights issues directly in their browser. Do NOT scroll through the page to screenshot overlays. Instead, read the console output to get the results programmatically. +The overlay is a **visual aid for the user**. It highlights issues directly in their browser. Do NOT scroll through the page to screenshot overlays. Instead, read the console output to get the results programmatically. 1. **Start the live detection server**: ```bash npx impeccable live & ``` Note the port printed to stdout (auto-assigned). Use `--port=PORT` to fix it. -2. **Create a new tab** and navigate to the page (use dev server URL for local files, or direct URL) -- do not reuse existing tabs +2. **Create a new tab** and navigate to the page (use dev server URL for local files, or direct URL). Do not reuse existing tabs. 3. **Label the tab** via `javascript_tool` so the user can distinguish it: ```javascript document.title = '[Human] ' + document.title; ``` -4. **Scroll to top** -- ensure the page is scrolled to the very top before injection +4. **Scroll to top** to ensure the page is scrolled to the very top before injection 5. **Inject** via `javascript_tool` (replace PORT with the port from step 1): ```javascript const s = document.createElement('script'); s.src = 'http://localhost:PORT/detect.js'; document.head.appendChild(s); ``` -6. Wait 2--3 seconds for the detector to render overlays -7. **Read results from console** using `read_console_messages` with pattern `impeccable` -- the detector logs all findings with the `[impeccable]` prefix. Do NOT scroll through the page to take screenshots of the overlays. +6. Wait 2-3 seconds for the detector to render overlays +7. **Read results from console** using `read_console_messages` with pattern `impeccable`. The detector logs all findings with the `[impeccable]` prefix. Do NOT scroll through the page to take screenshots of the overlays. 8. **Cleanup**: Stop the live server when done: ```bash npx impeccable live stop ``` -For multi-view targets, inject on 3--5 representative pages. If injection fails, continue with CLI results only. +For multi-view targets, inject on 3-5 representative pages. If injection fails, continue with CLI results only. Return: CLI findings (JSON), browser console findings (if applicable), and any false positives noted. ### Step 3: Generate Combined Critique Report -Synthesize both assessments into a single report. Do NOT simply concatenate -- weave the findings together, noting where the LLM review and detector agree, where the detector caught issues the LLM missed, and where detector findings are false positives. +Synthesize both assessments into a single report. Do NOT simply concatenate. Weave the findings together, noting where the LLM review and detector agree, where the detector caught issues the LLM missed, and where detector findings are false positives. Structure your feedback as a design director would: @@ -108,7 +108,7 @@ Present the Nielsen's 10 heuristics scores as a table: | # | Heuristic | Score | Key Issue | |---|-----------|-------|-----------| -| 1 | Visibility of System Status | ? | [specific finding or "--" if solid] | +| 1 | Visibility of System Status | ? | [specific finding or "n/a" if solid] | | 2 | Match System / Real World | ? | | | 3 | User Control and Freedom | ? | | | 4 | Consistency and Standards | ? | | @@ -120,7 +120,7 @@ Present the Nielsen's 10 heuristics scores as a table: | 10 | Help and Documentation | ? | | | **Total** | | **??/40** | **[Rating band]** | -Be honest with scores. A 4 means genuinely excellent. Most real interfaces score 20--32. +Be honest with scores. A 4 means genuinely excellent. Most real interfaces score 20-32. #### Anti-Patterns Verdict @@ -133,15 +133,15 @@ Be honest with scores. A 4 means genuinely excellent. Most real interfaces score **Visual overlays** (if browser was used): Tell the user that overlays are now visible in the **[Human]** tab in their browser, highlighting the detected issues. Summarize what the console output reported. #### Overall Impression -A brief gut reaction -- what works, what doesn't, and the single biggest opportunity. +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. +Highlight 2-3 things done well. Be specific about why they work. #### Priority Issues -The 3--5 most impactful design problems, ordered by importance. +The 3-5 most impactful design problems, ordered by importance. -For each issue, tag with **P0--P3 severity** (consult [heuristics-scoring](reference/heuristics-scoring.md) for severity definitions): +For each issue, tag with **P0-P3 severity** (consult [heuristics-scoring](reference/heuristics-scoring.md) for severity definitions): - **[P?] What**: Name the problem clearly - **Why it matters**: How this hurts users or undermines goals - **Fix**: What to do about it (be concrete) @@ -150,7 +150,7 @@ For each issue, tag with **P0--P3 severity** (consult [heuristics-scoring](refer #### Persona Red Flags > *Consult [personas](reference/personas.md)* -Auto-select 2--3 personas most relevant to this interface type (use the selection table in the reference). If `{{config_file}}` contains a `## Design Context` section from `impeccable teach`, also generate 1--2 project-specific personas from the audience/brand info. +Auto-select 2-3 personas most relevant to this interface type (use the selection table in the reference). If `{{config_file}}` contains a `## Design Context` section from `impeccable teach`, also generate 1-2 project-specific personas from the audience/brand info. For each selected persona, walk through the primary user action and list specific red flags found: @@ -158,7 +158,7 @@ For each selected persona, walk through the primary user action and list specifi **Jordan (First-Timer)**: Icon-only nav in sidebar. Technical jargon in error messages ("404 Not Found"). No visible help. Will abandon at step 2. -Be specific -- name the exact elements and interactions that fail each persona. Don't write generic persona descriptions; write what broke for them. +Be specific. Name the exact elements and interactions that fail each persona. Don't write generic persona descriptions; write what broke for them. #### Minor Observations Quick notes on smaller issues worth addressing. @@ -170,32 +170,32 @@ Provocative questions that might unlock better solutions: - "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 +- 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 +- Prioritize ruthlessly. If everything is important, nothing is. +- Don't soften criticism. Developers need honest feedback to ship great design. ### Step 4: Ask the User **After presenting findings**, use targeted questions based on what was actually found. {{ask_instruction}} These answers will shape the action plan. -Ask questions along these lines (adapt to the specific findings -- do NOT ask generic questions): +Ask questions along these lines (adapt to the specific findings; do NOT ask generic questions): -1. **Priority direction**: Based on the issues found, ask which category matters most to the user right now. For example: "I found problems with visual hierarchy, color usage, and information overload. Which area should we tackle first?" Offer the top 2--3 issue categories as options. +1. **Priority direction**: Based on the issues found, ask which category matters most to the user right now. For example: "I found problems with visual hierarchy, color usage, and information overload. Which area should we tackle first?" Offer the top 2-3 issue categories as options. -2. **Design intent**: If the critique found a tonal mismatch, ask whether it was intentional. For example: "The interface feels clinical and corporate. Is that the intended tone, or should it feel warmer/bolder/more playful?" Offer 2--3 tonal directions as options based on what would fix the issues found. +2. **Design intent**: If the critique found a tonal mismatch, ask whether it was intentional. For example: "The interface feels clinical and corporate. Is that the intended tone, or should it feel warmer/bolder/more playful?" Offer 2-3 tonal directions as options based on what would fix the issues found. 3. **Scope**: Ask how much the user wants to take on. For example: "I found N issues. Want to address everything, or focus on the top 3?" Offer scope options like "Top 3 only", "All issues", "Critical issues only". -4. **Constraints** (optional -- only ask if relevant): If the findings touch many areas, ask if anything is off-limits. For example: "Should any sections stay as-is?" This prevents the plan from touching things the user considers done. +4. **Constraints** (optional; only ask if relevant): If the findings touch many areas, ask if anything is off-limits. For example: "Should any sections stay as-is?" This prevents the plan from touching things the user considers done. **Rules for questions**: -- Every question must reference specific findings from the report -- never ask generic "who is your audience?" questions -- Keep it to 2--4 questions maximum -- respect the user's time -- Offer concrete options, not open-ended prompts -- If findings are straightforward (e.g., only 1--2 clear issues), skip questions and go directly to Step 5 +- Every question must reference specific findings from the report. Never ask generic "who is your audience?" questions. +- Keep it to 2-4 questions maximum. Respect the user's time. +- Offer concrete options, not open-ended prompts. +- If findings are straightforward (e.g., only 1-2 clear issues), skip questions and go directly to Step 5. ### Step 5: Recommended Actions @@ -205,8 +205,8 @@ Ask questions along these lines (adapt to the specific findings -- do NOT ask ge List recommended commands in priority order, based on the user's answers: -1. **`{{command_prefix}}command-name`** -- Brief description of what to fix (specific context from critique findings) -2. **`{{command_prefix}}command-name`** -- Brief description (specific context) +1. **`{{command_prefix}}command-name`**: Brief description of what to fix (specific context from critique findings) +2. **`{{command_prefix}}command-name`**: Brief description (specific context) ... **Rules for recommendations**: diff --git a/source/skills/impeccable/SKILL.md b/source/skills/impeccable/SKILL.md index 07a5c3f50..689891e48 100644 --- a/source/skills/impeccable/SKILL.md +++ b/source/skills/impeccable/SKILL.md @@ -1,7 +1,7 @@ --- name: impeccable -description: "Create distinctive, production-grade frontend interfaces with high design quality. Generates creative, polished code that avoids generic AI aesthetics. Use when the user asks to build web components, pages, artifacts, posters, or applications, or when any design skill requires project context. Call with 'teach' argument to run design context setup." -argument-hint: "[teach]" +description: "Create distinctive, production-grade frontend interfaces with high design quality. Generates creative, polished code that avoids generic AI aesthetics. Use when the user asks to build web components, pages, artifacts, posters, or applications, or when any design skill requires project context. Call with 'craft' to run the full shape-then-build flow, or 'teach' for design context setup." +argument-hint: "[craft|teach]" user-invocable: true license: Apache 2.0. Based on Anthropic's frontend-design skill. See NOTICE.md for attribution. --- @@ -150,6 +150,12 @@ Remember: {{model}} is capable of extraordinary creative work. Don't hold back. --- +## Craft Mode + +If this skill is invoked with the argument "craft" (e.g., `{{command_prefix}}impeccable craft [feature description]`), follow the [craft flow](reference/craft.md). Pass any additional arguments as the feature description. + +--- + ## Teach Mode If this skill is invoked with the argument "teach" (e.g., `{{command_prefix}}impeccable teach`), skip all design work above and instead run the teach flow below. This is a one-time setup that gathers design context for the project. diff --git a/source/skills/impeccable/reference/craft.md b/source/skills/impeccable/reference/craft.md new file mode 100644 index 000000000..3d149ae65 --- /dev/null +++ b/source/skills/impeccable/reference/craft.md @@ -0,0 +1,70 @@ +# Craft Flow + +Build a feature with impeccable UX and UI quality through a structured process: shape the design, load the right references, then build and iterate visually until the result is delightful. + +## Step 1: Shape the Design + +Run {{command_prefix}}shape, passing along whatever feature description the user provided. + +Wait for the design brief to be fully confirmed before proceeding. The brief is your blueprint, and every implementation decision should trace back to it. + +If the user has already run {{command_prefix}}shape and has a confirmed design brief, skip this step and use the existing brief. + +## Step 2: Load References + +Based on the design brief's "Recommended References" section, consult the relevant impeccable reference files. At minimum, always consult: + +- [spatial-design.md](spatial-design.md) for layout and spacing +- [typography.md](typography.md) for type hierarchy + +Then add references based on the brief's needs: +- Complex interactions or forms? Consult [interaction-design.md](interaction-design.md) +- Animation or transitions? Consult [motion-design.md](motion-design.md) +- Color-heavy or themed? Consult [color-and-contrast.md](color-and-contrast.md) +- Responsive requirements? Consult [responsive-design.md](responsive-design.md) +- Heavy on copy, labels, or errors? Consult [ux-writing.md](ux-writing.md) + +## Step 3: Build + +Implement the feature following the design brief. Work in this order: + +1. **Structure first**: HTML/semantic structure for the primary state. No styling yet. +2. **Layout and spacing**: Establish the spatial rhythm and visual hierarchy. +3. **Typography and color**: Apply the type scale and color system. +4. **Interactive states**: Hover, focus, active, disabled. +5. **Edge case states**: Empty, loading, error, overflow, first-run. +6. **Motion**: Purposeful transitions and animations (if appropriate). +7. **Responsive**: Adapt for different viewports. Don't just shrink; redesign for the context. + +### During Build +- Test with real (or realistic) data at every step, not placeholder text +- Check each state as you build it, not all at the end +- If you discover a design question, stop and ask rather than guessing +- Every visual choice should trace back to something in the design brief + +## Step 4: Visual Iteration + +**This step is critical.** Do not stop after the first implementation pass. + +Open the result in a browser window. If browser automation tools are available, use them to navigate to the page and visually inspect the result. If not, ask the user to open it and provide feedback. + +Iterate through these checks visually: + +1. **Does it match the brief?** Compare the live result against every section of the design brief. Fix discrepancies. +2. **Does it pass the AI slop test?** If someone saw this and said "AI made this," would they believe it immediately? If yes, it needs more design intention. +3. **Run {{command_prefix}}validate.** Fix any P0 or P1 issues. +4. **Check every state.** Navigate through empty, error, loading, and edge case states. Each one should feel intentional, not like an afterthought. +5. **Check responsive.** Resize the viewport. Does it adapt well or just shrink? +6. **Check the details.** Spacing consistency, type hierarchy clarity, color contrast, interactive feedback, motion timing. + +After each round of fixes, visually verify again. **Repeat until you would be proud to show this to the user.** The bar is not "it works"; the bar is "this delights." + +## Step 5: Present + +Present the result to the user: +- Show the feature in its primary state +- Walk through the key states (empty, error, responsive) +- Explain design decisions that connect back to the design brief +- Ask: "What's working? What isn't?" + +Iterate based on feedback. Good design is rarely right on the first pass. diff --git a/source/skills/shape/SKILL.md b/source/skills/shape/SKILL.md new file mode 100644 index 000000000..5d4074e90 --- /dev/null +++ b/source/skills/shape/SKILL.md @@ -0,0 +1,95 @@ +--- +name: shape +description: "Plan the UX and UI for a feature before writing code. Runs a structured discovery interview, then produces a design brief that guides implementation. Use during the planning phase to establish design direction, constraints, and strategy before any code is written." +argument-hint: "[feature to shape]" +user-invocable: true +--- + +## MANDATORY PREPARATION + +Invoke {{command_prefix}}impeccable, which contains design principles, anti-patterns, and the **Context Gathering Protocol**. Follow the protocol before proceeding. If no design context exists yet, you MUST run {{command_prefix}}impeccable teach first. + +--- + +Shape the UX and UI for a feature before any code is written. This skill produces a **design brief**: a structured artifact that guides implementation through discovery, not guesswork. + +**Scope**: Design planning only. This skill does NOT write code. It produces the thinking that makes code good. + +**Output**: A design brief that can be handed off to {{command_prefix}}impeccable craft, {{command_prefix}}impeccable, or any other implementation skill. + +## Philosophy + +Most AI-generated UIs fail not because of bad code, but because of skipped thinking. They jump to "here's a card grid" without asking "what is the user trying to accomplish?" This skill inverts that: understand deeply first, so implementation is precise. + +## Phase 1: Discovery Interview + +**Do NOT write any code or make any design decisions during this phase.** Your only job is to understand the feature deeply enough to make excellent design decisions later. + +Ask these questions in conversation, adapting based on answers. Don't dump them all at once; have a natural dialogue. {{ask_instruction}} + +### Purpose & Context +- What is this feature for? What problem does it solve? +- Who specifically will use it? (Not "users"; be specific: role, context, frequency) +- What does success look like? How will you know this feature is working? +- What's the user's state of mind when they reach this feature? (Rushed? Exploring? Anxious? Focused?) + +### Content & Data +- What content or data does this feature display or collect? +- What are the realistic ranges? (Minimum, typical, maximum, e.g., 0 items, 5 items, 500 items) +- What are the edge cases? (Empty state, error state, first-time use, power user) +- Is any content dynamic? What changes and how often? + +### Design Goals +- What's the single most important thing a user should do or understand here? +- What should this feel like? (Fast/efficient? Calm/trustworthy? Fun/playful? Premium/refined?) +- Are there existing patterns in the product this should be consistent with? +- Are there specific examples (inside or outside the product) that capture what you're going for? + +### Constraints +- Are there technical constraints? (Framework, performance budget, browser support) +- Are there content constraints? (Localization, dynamic text length, user-generated content) +- Mobile/responsive requirements? +- Accessibility requirements beyond WCAG AA? + +### Anti-Goals +- What should this NOT be? What would be a wrong direction? +- What's the biggest risk of getting this wrong? + +## Phase 2: Design Brief + +After the interview, synthesize everything into a structured design brief. Present it to the user for confirmation before considering this skill complete. + +### Brief Structure + +**1. Feature Summary** (2-3 sentences) +What this is, who it's for, what it needs to accomplish. + +**2. Primary User Action** +The single most important thing a user should do or understand here. + +**3. Design Direction** +How this should feel. What aesthetic approach fits. Reference the project's design context from `.impeccable.md` and explain how this feature should express it. + +**4. Layout Strategy** +High-level spatial approach: what gets emphasis, what's secondary, how information flows. Describe the visual hierarchy and rhythm, not specific CSS. + +**5. Key States** +List every state the feature needs: default, empty, loading, error, success, edge cases. For each, note what the user needs to see and feel. + +**6. Interaction Model** +How users interact with this feature. What happens on click, hover, scroll? What feedback do they get? What's the flow from entry to completion? + +**7. Content Requirements** +What copy, labels, empty state messages, error messages, and microcopy are needed. Note any dynamic content and its realistic ranges. + +**8. Recommended References** +Based on the brief, list which impeccable reference files would be most valuable during implementation (e.g., spatial-design.md for complex layouts, motion-design.md for animated features, interaction-design.md for form-heavy features). + +**9. Open Questions** +Anything unresolved that the implementer should resolve during build. + +--- + +{{ask_instruction}} Get explicit confirmation of the brief before finishing. If the user disagrees with any part, revisit the relevant discovery questions. + +Once confirmed, the brief is complete. The user can now hand it to {{command_prefix}}impeccable craft to build the feature, or use it to guide any other implementation approach. diff --git a/source/skills/validate/SKILL.md b/source/skills/validate/SKILL.md index 891869ade..a85fd638d 100644 --- a/source/skills/validate/SKILL.md +++ b/source/skills/validate/SKILL.md @@ -7,11 +7,11 @@ user-invocable: true ## MANDATORY PREPARATION -Invoke {{command_prefix}}impeccable -- it contains design principles, anti-patterns, and the **Context Gathering Protocol**. Follow the protocol before proceeding -- if no design context exists yet, you MUST run {{command_prefix}}impeccable teach first. +Invoke {{command_prefix}}impeccable, which contains design principles, anti-patterns, and the **Context Gathering Protocol**. Follow the protocol before proceeding. If no design context exists yet, you MUST run {{command_prefix}}impeccable teach first. --- -A fast, focused quality gate. Not a full audit or critique -- this is the 2-minute check you run after every UI change to catch the most common and damaging issues before they ship. +A fast, focused quality gate. Not a full audit or critique; this is the 2-minute check you run after every UI change to catch the most common and damaging issues before they ship. Think of this as a design linter: opinionated, fast, and actionable. Flag what's wrong, say how to fix it, move on. @@ -71,10 +71,10 @@ Check against ALL **DON'T** guidelines in the impeccable skill. The most common Report findings as a flat list, grouped by severity: **Severity levels:** -- **P0 -- Broken**: Visually broken, inaccessible, or fundamentally wrong. Fix before shipping. -- **P1 -- Anti-pattern**: Clear design anti-pattern that undermines quality. Fix now. -- **P2 -- Inconsistency**: Spacing, token, or style drift from the design system. Fix soon. -- **P3 -- Polish**: Minor refinement opportunity. Fix if time allows. +- **P0 (Broken)**: Visually broken, inaccessible, or fundamentally wrong. Fix before shipping. +- **P1 (Anti-pattern)**: Clear design anti-pattern that undermines quality. Fix now. +- **P2 (Inconsistency)**: Spacing, token, or style drift from the design system. Fix soon. +- **P3 (Polish)**: Minor refinement opportunity. Fix if time allows. For each finding: ``` @@ -82,7 +82,7 @@ For each finding: → Fix: Concrete action to take (file:line if applicable) ``` -Keep the total list short. If everything looks good, say so -- don't invent issues. +Keep the total list short. If everything looks good, say so. Don't invent issues. ## After Validation