diff --git a/.claude/skills/adapt/SKILL.md b/.claude/skills/adapt/SKILL.md index 7e11509f7..b0c508b1c 100644 --- a/.claude/skills/adapt/SKILL.md +++ b/.claude/skills/adapt/SKILL.md @@ -13,6 +13,12 @@ args: Adapt existing designs to work effectively across different contexts - different screen sizes, devices, platforms, or use cases. +## MANDATORY PREPARATION + +Use the frontend-design skill — 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 teach-impeccable first. Additionally gather: target platforms/devices and usage contexts. + +--- + ## Assess Adaptation Challenge Understand what needs adaptation and why: diff --git a/.claude/skills/animate/SKILL.md b/.claude/skills/animate/SKILL.md index 5abd7435f..d12d88b01 100644 --- a/.claude/skills/animate/SKILL.md +++ b/.claude/skills/animate/SKILL.md @@ -12,20 +12,7 @@ Analyze a feature and strategically add animations and micro-interactions that e ## MANDATORY PREPARATION -### Context Gathering (Do This First) - -You cannot do a great job without having necessary context, such as target audience (critical), desired use-cases (critical), brand personality/tone (playful vs serious, energetic vs calm), and performance constraints. - -Attempt to gather these from the current thread or codebase. - -1. If you don't find *exact* information and have to infer from existing design and functionality, you MUST STOP and STOP and call the AskUserQuestionTool to clarify. whether you got it right. -2. Otherwise, if you can't fully infer or your level of confidence is medium or lower, you MUST STOP and call the AskUserQuestionTool to clarify. clarifying questions first to complete your context. - -Do NOT proceed until you have answers. Guessing leads to inappropriate or excessive animation. - -### Use frontend-design skill - -Use the frontend-design skill for design principles and anti-patterns. Do NOT proceed until it has executed and you know all DO's and DON'Ts. +Use the frontend-design skill — 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 teach-impeccable first. Additionally gather: performance constraints. --- @@ -46,7 +33,7 @@ Analyze where motion would improve the experience: - Who's the audience? (Motion-sensitive users? Power users who want speed?) - What matters most? (One hero animation vs many micro-interactions?) -If any of these are unclear from the codebase, STOP and call the AskUserQuestionTool to clarify. +If any of these are unclear from the codebase, STOP and call the AskUserQuestion tool to clarify. **CRITICAL**: Respect `prefers-reduced-motion`. Always provide non-animated alternatives for users who need them. diff --git a/.claude/skills/bolder/SKILL.md b/.claude/skills/bolder/SKILL.md index a13aa1bc6..088f30c44 100644 --- a/.claude/skills/bolder/SKILL.md +++ b/.claude/skills/bolder/SKILL.md @@ -12,20 +12,7 @@ Increase visual impact and personality in designs that are too safe, generic, or ## MANDATORY PREPARATION -### Context Gathering (Do This First) - -You cannot do a great job without having necessary context, such as target audience (critical), desired use-cases (critical), brand personality/tone, and everything else that a great human designer would need as well. - -Attempt to gather these from the current thread or codebase. - -1. If you don't find *exact* information and have to infer from existing design and functionality, you MUST STOP and STOP and call the AskUserQuestionTool to clarify. whether you got it right. -2. Otherwise, if you can't fully infer or your level of confidence is medium or lower, you MUST STOP and call the AskUserQuestionTool to clarify. clarifying questions first to complete your context. - -Do NOT proceed until you have answers. Guessing leads to generic AI slop. - -### Use frontend-design skill - -Use the frontend-design skill for design principles and anti-patterns. Do NOT proceed until it has executed and you know all DO's and DON'Ts. +Use the frontend-design skill — 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 teach-impeccable first. --- @@ -47,7 +34,7 @@ Analyze what makes the design feel too safe or boring: - Who's the audience? (What will resonate?) - What are the constraints? (Brand guidelines, accessibility, performance) -If any of these are unclear from the codebase, STOP and call the AskUserQuestionTool to clarify. +If any of these are unclear from the codebase, STOP and call the AskUserQuestion tool to clarify. **CRITICAL**: "Bolder" doesn't mean chaotic or garish. It means distinctive, memorable, and confident. Think intentional drama, not random chaos. diff --git a/.claude/skills/clarify/SKILL.md b/.claude/skills/clarify/SKILL.md index 4592a08de..bc10a30d3 100644 --- a/.claude/skills/clarify/SKILL.md +++ b/.claude/skills/clarify/SKILL.md @@ -10,6 +10,12 @@ args: Identify and improve unclear, confusing, or poorly written interface text to make the product easier to understand and use. +## MANDATORY PREPARATION + +Use the frontend-design skill — 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 teach-impeccable first. Additionally gather: audience technical level and users' mental state in context. + +--- + ## Assess Current Copy Identify what makes the text unclear or ineffective: diff --git a/.claude/skills/colorize/SKILL.md b/.claude/skills/colorize/SKILL.md index 05b15813a..b45d52a2e 100644 --- a/.claude/skills/colorize/SKILL.md +++ b/.claude/skills/colorize/SKILL.md @@ -12,20 +12,7 @@ Strategically introduce color to designs that are too monochromatic, gray, or la ## MANDATORY PREPARATION -### Context Gathering (Do This First) - -You cannot do a great job without having necessary context, such as target audience (critical), desired use-cases (critical), brand personality/tone, and especially existing brand colors. - -Attempt to gather these from the current thread or codebase. - -1. If you don't find *exact* information and have to infer from existing design and functionality, you MUST STOP and STOP and call the AskUserQuestionTool to clarify. whether you got it right. -2. Otherwise, if you can't fully infer or your level of confidence is medium or lower, you MUST STOP and call the AskUserQuestionTool to clarify. clarifying questions first to complete your context. - -Do NOT proceed until you have answers. Guessing leads to generic AI slop colors. - -### Use frontend-design skill - -Use the frontend-design skill for design principles and anti-patterns. Do NOT proceed until it has executed and you know all DO's and DON'Ts. +Use the frontend-design skill — 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 teach-impeccable first. Additionally gather: existing brand colors. --- @@ -47,7 +34,7 @@ Analyze the current state and identify opportunities: - **Wayfinding**: Helping users navigate and understand structure - **Delight**: Moments of visual interest and personality -If any of these are unclear from the codebase, STOP and call the AskUserQuestionTool to clarify. +If any of these are unclear from the codebase, STOP and call the AskUserQuestion tool to clarify. **CRITICAL**: More color ≠ better. Strategic color beats rainbow vomit every time. Every color should have a purpose. diff --git a/.claude/skills/critique/SKILL.md b/.claude/skills/critique/SKILL.md index 7d3aefad4..eb0d663b9 100644 --- a/.claude/skills/critique/SKILL.md +++ b/.claude/skills/critique/SKILL.md @@ -8,9 +8,13 @@ args: required: false --- -Conduct a holistic design critique, evaluating whether the interface actually works—not just technically, but as a designed experience. Think like a design director giving feedback. +## MANDATORY PREPARATION -**First**: Use the frontend-design skill for design principles and anti-patterns. +Use the frontend-design skill — 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 teach-impeccable first. Additionally gather: what the interface is trying to accomplish. + +--- + +Conduct a holistic design critique, evaluating whether the interface actually works—not just technically, but as a designed experience. Think like a design director giving feedback. ## Design Critique diff --git a/.claude/skills/delight/SKILL.md b/.claude/skills/delight/SKILL.md index 6106d4d71..a215ac30d 100644 --- a/.claude/skills/delight/SKILL.md +++ b/.claude/skills/delight/SKILL.md @@ -12,20 +12,7 @@ Identify opportunities to add moments of joy, personality, and unexpected polish ## MANDATORY PREPARATION -### Context Gathering (Do This First) - -You cannot do a great job without having necessary context, such as target audience (critical), desired use-cases (critical), brand personality (playful vs professional vs quirky vs elegant), and what's appropriate for the domain. - -Attempt to gather these from the current thread or codebase. - -1. If you don't find *exact* information and have to infer from existing design and functionality, you MUST STOP and STOP and call the AskUserQuestionTool to clarify. whether you got it right. -2. Otherwise, if you can't fully infer or your level of confidence is medium or lower, you MUST STOP and call the AskUserQuestionTool to clarify. clarifying questions first to complete your context. - -Do NOT proceed until you have answers. Delight that's wrong for the context is worse than no delight at all. - -### Use frontend-design skill - -Use the frontend-design skill for design principles and anti-patterns. Do NOT proceed until it has executed and you know all DO's and DON'Ts. +Use the frontend-design skill — 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 teach-impeccable first. Additionally gather: what's appropriate for the domain (playful vs professional vs quirky vs elegant). --- @@ -54,7 +41,7 @@ Identify where delight would enhance (not distract from) the experience: - **Helpful surprises**: Anticipating needs before users ask (productivity tools) - **Sensory richness**: Satisfying sounds, smooth animations (creative tools) -If any of these are unclear from the codebase, STOP and call the AskUserQuestionTool to clarify. +If any of these are unclear from the codebase, STOP and call the AskUserQuestion tool to clarify. **CRITICAL**: Delight should enhance usability, never obscure it. If users notice the delight more than accomplishing their goal, you've gone too far. @@ -113,7 +100,7 @@ Add personality and joy through these methods: **Loading delight**: - Playful loading animations (not just spinners) -- Personality in loading messages ("Herding pixels..." "Teaching robots to dance...") +- Personality in loading messages (write product-specific ones, not generic AI filler) - Progress indication with encouraging messages - Skeleton screens with subtle animations @@ -203,7 +190,7 @@ Add personality and joy through these methods: **Form interactions**: - Input fields that animate on focus -- Checkboxes that bounce when checked +- Checkboxes with a satisfying scale pulse when checked - Success state that celebrates valid input - Auto-grow textareas @@ -253,13 +240,15 @@ Add personality and joy through these methods: - Countdown with encouraging messages ``` -Loading messages rotation: -- "Waking up the servers..." -- "Teaching robots to dance..." -- "Consulting the magic 8-ball..." -- "Counting backwards from infinity..." +Loading messages — write ones specific to your product, not generic AI filler: +- "Crunching your latest numbers..." +- "Syncing with your team's changes..." +- "Preparing your dashboard..." +- "Checking for updates since yesterday..." ``` +**WARNING**: Avoid cliched loading messages like "Herding pixels", "Teaching robots to dance", "Consulting the magic 8-ball", "Counting backwards from infinity". These are AI-slop copy — instantly recognizable as machine-generated. Write messages that are specific to what your product actually does. + ### Celebration Moments **Success celebrations**: diff --git a/.claude/skills/distill/SKILL.md b/.claude/skills/distill/SKILL.md index b9f0ddf28..1fd5c4887 100644 --- a/.claude/skills/distill/SKILL.md +++ b/.claude/skills/distill/SKILL.md @@ -12,20 +12,7 @@ Remove unnecessary complexity from designs, revealing the essential elements and ## MANDATORY PREPARATION -### Context Gathering (Do This First) - -You cannot do a great job without having necessary context, such as target audience (critical), desired use-cases (critical), and understanding what's truly essential vs nice-to-have for this product. - -Attempt to gather these from the current thread or codebase. - -1. If you don't find *exact* information and have to infer from existing design and functionality, you MUST STOP and STOP and call the AskUserQuestionTool to clarify. whether you got it right. -2. Otherwise, if you can't fully infer or your level of confidence is medium or lower, you MUST STOP and call the AskUserQuestionTool to clarify. clarifying questions first to complete your context. - -Do NOT proceed until you have answers. Simplifying the wrong things destroys usability. - -### Use frontend-design skill - -Use the frontend-design skill for design principles and anti-patterns. Do NOT proceed until it has executed and you know all DO's and DON'Ts. +Use the frontend-design skill — 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 teach-impeccable first. --- @@ -47,7 +34,7 @@ Analyze what makes the design feel complex or cluttered: - What can be removed, hidden, or combined? - What's the 20% that delivers 80% of value? -If any of these are unclear from the codebase, STOP and call the AskUserQuestionTool to clarify. +If any of these are unclear from the codebase, STOP and call the AskUserQuestion tool to clarify. **CRITICAL**: Simplicity is not about removing features - it's about removing obstacles between users and their goals. Every element should justify its existence. diff --git a/.claude/skills/frontend-design/SKILL.md b/.claude/skills/frontend-design/SKILL.md index c78cca7e0..df336117b 100644 --- a/.claude/skills/frontend-design/SKILL.md +++ b/.claude/skills/frontend-design/SKILL.md @@ -6,6 +6,26 @@ license: Apache 2.0. Based on Anthropic's frontend-design skill. See NOTICE.md f 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. +## Context Gathering Protocol + +Design skills produce generic output without project context. You MUST have confirmed design context before doing any design work. + +**Required context** — every design skill needs at minimum: +- **Target audience**: Who uses this product and in what context? +- **Use cases**: What jobs are they trying to get done? +- **Brand personality/tone**: How should the interface feel? + +Individual skills may require additional context — check the skill's preparation section for specifics. + +**CRITICAL**: You cannot infer this context by reading the codebase. Code tells you what was built, not who it's for or what it should feel like. Only the creator can provide this context. + +**Gathering order:** +1. **Check current instructions (instant)**: If your loaded instructions already contain a **Design Context** section, proceed immediately. +2. **Check .impeccable.md (fast)**: If not in instructions, read `.impeccable.md` from the project root. If it exists and contains the required context, proceed. +3. **Run teach-impeccable (REQUIRED)**: If neither source has context, you MUST run the teach-impeccable skill NOW before doing anything else. Do NOT skip this step. Do NOT attempt to infer context from the codebase instead. + +--- + ## Design Direction Commit to a BOLD aesthetic direction: diff --git a/.claude/skills/normalize/SKILL.md b/.claude/skills/normalize/SKILL.md index e1a986b6e..ea91d5c58 100644 --- a/.claude/skills/normalize/SKILL.md +++ b/.claude/skills/normalize/SKILL.md @@ -10,6 +10,12 @@ args: Analyze and redesign the feature to perfectly match our design system standards, aesthetics, and established patterns. +## MANDATORY PREPARATION + +Use the frontend-design skill — 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 teach-impeccable first. + +--- + ## Plan Before making changes, deeply understand the context: diff --git a/.claude/skills/onboard/SKILL.md b/.claude/skills/onboard/SKILL.md index 120f74357..4ec0049dd 100644 --- a/.claude/skills/onboard/SKILL.md +++ b/.claude/skills/onboard/SKILL.md @@ -8,6 +8,12 @@ args: required: false --- +## MANDATORY PREPARATION + +Use the frontend-design skill — 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 teach-impeccable first. Additionally gather: the "aha moment" you want users to reach, and users' experience level. + +--- + Create or improve onboarding experiences that help users understand, adopt, and succeed with the product quickly. ## Assess Onboarding Needs diff --git a/.claude/skills/polish/SKILL.md b/.claude/skills/polish/SKILL.md index 50c8fb499..3e95d12f4 100644 --- a/.claude/skills/polish/SKILL.md +++ b/.claude/skills/polish/SKILL.md @@ -8,7 +8,11 @@ args: required: false --- -**First**: Use the frontend-design skill for design principles and anti-patterns. +## MANDATORY PREPARATION + +Use the frontend-design skill — 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 teach-impeccable first. Additionally gather: quality bar (MVP vs flagship). + +--- Perform a meticulous final pass to catch all the small details that separate good work from great work. The difference between shipped and polished. diff --git a/.claude/skills/quieter/SKILL.md b/.claude/skills/quieter/SKILL.md index def796a4f..3e63a54c6 100644 --- a/.claude/skills/quieter/SKILL.md +++ b/.claude/skills/quieter/SKILL.md @@ -12,20 +12,7 @@ Reduce visual intensity in designs that are too bold, aggressive, or overstimula ## MANDATORY PREPARATION -### Context Gathering (Do This First) - -You cannot do a great job without having necessary context, such as target audience (critical), desired use-cases (critical), brand personality/tone, and everything else that a great human designer would need as well. - -Attempt to gather these from the current thread or codebase. - -1. If you don't find *exact* information and have to infer from existing design and functionality, you MUST STOP and STOP and call the AskUserQuestionTool to clarify. whether you got it right. -2. Otherwise, if you can't fully infer or your level of confidence is medium or lower, you MUST STOP and call the AskUserQuestionTool to clarify. clarifying questions first to complete your context. - -Do NOT proceed until you have answers. Guessing leads to generic design. - -### Use frontend-design skill - -Use the frontend-design skill for design principles and anti-patterns. Do NOT proceed until it has executed and you know all DO's and DON'Ts. +Use the frontend-design skill — 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 teach-impeccable first. --- @@ -47,7 +34,7 @@ Analyze what makes the design feel too intense: - What's working? (Don't throw away good ideas) - What's the core message? (Preserve what matters) -If any of these are unclear from the codebase, STOP and call the AskUserQuestionTool to clarify. +If any of these are unclear from the codebase, STOP and call the AskUserQuestion tool to clarify. **CRITICAL**: "Quieter" doesn't mean boring or generic. It means refined, sophisticated, and easier on the eyes. Think luxury, not laziness. diff --git a/.claude/skills/teach-impeccable/SKILL.md b/.claude/skills/teach-impeccable/SKILL.md index 2ac070a53..450f69675 100644 --- a/.claude/skills/teach-impeccable/SKILL.md +++ b/.claude/skills/teach-impeccable/SKILL.md @@ -21,7 +21,7 @@ Note what you've learned and what remains unclear. ## Step 2: Ask UX-Focused Questions -STOP and call the AskUserQuestionTool to clarify. Focus only on what you couldn't infer from the codebase: +STOP and call the AskUserQuestion tool to clarify. Focus only on what you couldn't infer from the codebase: ### Users & Purpose - Who uses this? What's their context when using it? @@ -64,6 +64,8 @@ Synthesize your findings and the user's answers into a `## Design Context` secti [3-5 principles derived from the conversation that should guide all design decisions] ``` -Write this section to CLAUDE.md in the project root. If the file exists, append or update the Design Context section. +Write this section to `.impeccable.md` in the project root. If the file already exists, update the Design Context section in place. + +Then STOP and call the AskUserQuestion tool to clarify. whether they'd also like the Design Context appended to CLAUDE.md. If yes, append or update the section there as well. Confirm completion and summarize the key design principles that will now guide all future work. \ No newline at end of file diff --git a/scripts/lib/utils.js b/scripts/lib/utils.js index 5838ecf27..ba741dd7d 100644 --- a/scripts/lib/utils.js +++ b/scripts/lib/utils.js @@ -267,7 +267,7 @@ export const PROVIDER_PLACEHOLDERS = { 'claude-code': { model: 'Claude', config_file: 'CLAUDE.md', - ask_instruction: 'STOP and call the AskUserQuestionTool to clarify.' + ask_instruction: 'STOP and call the AskUserQuestion tool to clarify.' }, 'cursor': { model: 'the model', diff --git a/source/skills/adapt/SKILL.md b/source/skills/adapt/SKILL.md index 9bbea89d0..1a3773596 100644 --- a/source/skills/adapt/SKILL.md +++ b/source/skills/adapt/SKILL.md @@ -13,6 +13,12 @@ user-invokable: true Adapt existing designs to work effectively across different contexts - different screen sizes, devices, platforms, or use cases. +## MANDATORY PREPARATION + +Use the frontend-design skill — 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 teach-impeccable first. Additionally gather: target platforms/devices and usage contexts. + +--- + ## Assess Adaptation Challenge Understand what needs adaptation and why: diff --git a/source/skills/animate/SKILL.md b/source/skills/animate/SKILL.md index c6563c15e..fc6aeba83 100644 --- a/source/skills/animate/SKILL.md +++ b/source/skills/animate/SKILL.md @@ -12,20 +12,7 @@ Analyze a feature and strategically add animations and micro-interactions that e ## MANDATORY PREPARATION -### Context Gathering (Do This First) - -You cannot do a great job without having necessary context, such as target audience (critical), desired use-cases (critical), brand personality/tone (playful vs serious, energetic vs calm), and performance constraints. - -Attempt to gather these from the current thread or codebase. - -1. If you don't find *exact* information and have to infer from existing design and functionality, you MUST STOP and {{ask_instruction}} whether you got it right. -2. Otherwise, if you can't fully infer or your level of confidence is medium or lower, you MUST {{ask_instruction}} clarifying questions first to complete your context. - -Do NOT proceed until you have answers. Guessing leads to inappropriate or excessive animation. - -### Use frontend-design skill - -Use the frontend-design skill for design principles and anti-patterns. Do NOT proceed until it has executed and you know all DO's and DON'Ts. +Use the frontend-design skill — 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 teach-impeccable first. Additionally gather: performance constraints. --- diff --git a/source/skills/bolder/SKILL.md b/source/skills/bolder/SKILL.md index 4ae1d73c3..38cffc374 100644 --- a/source/skills/bolder/SKILL.md +++ b/source/skills/bolder/SKILL.md @@ -12,20 +12,7 @@ Increase visual impact and personality in designs that are too safe, generic, or ## MANDATORY PREPARATION -### Context Gathering (Do This First) - -You cannot do a great job without having necessary context, such as target audience (critical), desired use-cases (critical), brand personality/tone, and everything else that a great human designer would need as well. - -Attempt to gather these from the current thread or codebase. - -1. If you don't find *exact* information and have to infer from existing design and functionality, you MUST STOP and {{ask_instruction}} whether you got it right. -2. Otherwise, if you can't fully infer or your level of confidence is medium or lower, you MUST {{ask_instruction}} clarifying questions first to complete your context. - -Do NOT proceed until you have answers. Guessing leads to generic AI slop. - -### Use frontend-design skill - -Use the frontend-design skill for design principles and anti-patterns. Do NOT proceed until it has executed and you know all DO's and DON'Ts. +Use the frontend-design skill — 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 teach-impeccable first. --- diff --git a/source/skills/clarify/SKILL.md b/source/skills/clarify/SKILL.md index c39e4f73f..9bf07bd98 100644 --- a/source/skills/clarify/SKILL.md +++ b/source/skills/clarify/SKILL.md @@ -10,6 +10,12 @@ user-invokable: true Identify and improve unclear, confusing, or poorly written interface text to make the product easier to understand and use. +## MANDATORY PREPARATION + +Use the frontend-design skill — 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 teach-impeccable first. Additionally gather: audience technical level and users' mental state in context. + +--- + ## Assess Current Copy Identify what makes the text unclear or ineffective: diff --git a/source/skills/colorize/SKILL.md b/source/skills/colorize/SKILL.md index 905782fb5..004b36eb9 100644 --- a/source/skills/colorize/SKILL.md +++ b/source/skills/colorize/SKILL.md @@ -12,20 +12,7 @@ Strategically introduce color to designs that are too monochromatic, gray, or la ## MANDATORY PREPARATION -### Context Gathering (Do This First) - -You cannot do a great job without having necessary context, such as target audience (critical), desired use-cases (critical), brand personality/tone, and especially existing brand colors. - -Attempt to gather these from the current thread or codebase. - -1. If you don't find *exact* information and have to infer from existing design and functionality, you MUST STOP and {{ask_instruction}} whether you got it right. -2. Otherwise, if you can't fully infer or your level of confidence is medium or lower, you MUST {{ask_instruction}} clarifying questions first to complete your context. - -Do NOT proceed until you have answers. Guessing leads to generic AI slop colors. - -### Use frontend-design skill - -Use the frontend-design skill for design principles and anti-patterns. Do NOT proceed until it has executed and you know all DO's and DON'Ts. +Use the frontend-design skill — 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 teach-impeccable first. Additionally gather: existing brand colors. --- diff --git a/source/skills/critique/SKILL.md b/source/skills/critique/SKILL.md index 26c07f591..5b5f4978e 100644 --- a/source/skills/critique/SKILL.md +++ b/source/skills/critique/SKILL.md @@ -10,20 +10,7 @@ user-invokable: true ## MANDATORY PREPARATION -### Context Gathering (Do This First) - -You cannot do a great job without having necessary context, such as target audience (critical), desired use-cases (critical), brand personality/tone, and what the interface is trying to accomplish. - -Attempt to gather these from the current thread or codebase. - -1. If you don't find *exact* information and have to infer from existing design and functionality, you MUST STOP and {{ask_instruction}} whether you got it right. -2. Otherwise, if you can't fully infer or your level of confidence is medium or lower, you MUST {{ask_instruction}} clarifying questions first to complete your context. - -Do NOT proceed until you have answers. Critique without context produces generic feedback. - -### Use frontend-design skill - -Use the frontend-design skill for design principles and anti-patterns. Do NOT proceed until it has executed and you know all DO's and DON'Ts. +Use the frontend-design skill — 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 teach-impeccable first. Additionally gather: what the interface is trying to accomplish. --- diff --git a/source/skills/delight/SKILL.md b/source/skills/delight/SKILL.md index efc2d87ec..e3e0de820 100644 --- a/source/skills/delight/SKILL.md +++ b/source/skills/delight/SKILL.md @@ -12,20 +12,7 @@ Identify opportunities to add moments of joy, personality, and unexpected polish ## MANDATORY PREPARATION -### Context Gathering (Do This First) - -You cannot do a great job without having necessary context, such as target audience (critical), desired use-cases (critical), brand personality (playful vs professional vs quirky vs elegant), and what's appropriate for the domain. - -Attempt to gather these from the current thread or codebase. - -1. If you don't find *exact* information and have to infer from existing design and functionality, you MUST STOP and {{ask_instruction}} whether you got it right. -2. Otherwise, if you can't fully infer or your level of confidence is medium or lower, you MUST {{ask_instruction}} clarifying questions first to complete your context. - -Do NOT proceed until you have answers. Delight that's wrong for the context is worse than no delight at all. - -### Use frontend-design skill - -Use the frontend-design skill for design principles and anti-patterns. Do NOT proceed until it has executed and you know all DO's and DON'Ts. +Use the frontend-design skill — 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 teach-impeccable first. Additionally gather: what's appropriate for the domain (playful vs professional vs quirky vs elegant). --- diff --git a/source/skills/distill/SKILL.md b/source/skills/distill/SKILL.md index 6ff81ad0e..62d318a2a 100644 --- a/source/skills/distill/SKILL.md +++ b/source/skills/distill/SKILL.md @@ -12,20 +12,7 @@ Remove unnecessary complexity from designs, revealing the essential elements and ## MANDATORY PREPARATION -### Context Gathering (Do This First) - -You cannot do a great job without having necessary context, such as target audience (critical), desired use-cases (critical), and understanding what's truly essential vs nice-to-have for this product. - -Attempt to gather these from the current thread or codebase. - -1. If you don't find *exact* information and have to infer from existing design and functionality, you MUST STOP and {{ask_instruction}} whether you got it right. -2. Otherwise, if you can't fully infer or your level of confidence is medium or lower, you MUST {{ask_instruction}} clarifying questions first to complete your context. - -Do NOT proceed until you have answers. Simplifying the wrong things destroys usability. - -### Use frontend-design skill - -Use the frontend-design skill for design principles and anti-patterns. Do NOT proceed until it has executed and you know all DO's and DON'Ts. +Use the frontend-design skill — 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 teach-impeccable first. --- diff --git a/source/skills/frontend-design/SKILL.md b/source/skills/frontend-design/SKILL.md index d0c1173ca..c0486f7d2 100644 --- a/source/skills/frontend-design/SKILL.md +++ b/source/skills/frontend-design/SKILL.md @@ -6,6 +6,26 @@ license: Apache 2.0. Based on Anthropic's frontend-design skill. See NOTICE.md f 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. +## Context Gathering Protocol + +Design skills produce generic output without project context. You MUST have confirmed design context before doing any design work. + +**Required context** — every design skill needs at minimum: +- **Target audience**: Who uses this product and in what context? +- **Use cases**: What jobs are they trying to get done? +- **Brand personality/tone**: How should the interface feel? + +Individual skills may require additional context — check the skill's preparation section for specifics. + +**CRITICAL**: You cannot infer this context by reading the codebase. Code tells you what was built, not who it's for or what it should feel like. Only the creator can provide this context. + +**Gathering order:** +1. **Check current instructions (instant)**: If your loaded instructions already contain a **Design Context** section, proceed immediately. +2. **Check .impeccable.md (fast)**: If not in instructions, read `.impeccable.md` from the project root. If it exists and contains the required context, proceed. +3. **Run teach-impeccable (REQUIRED)**: If neither source has context, you MUST run the teach-impeccable skill NOW before doing anything else. Do NOT skip this step. Do NOT attempt to infer context from the codebase instead. + +--- + ## Design Direction Commit to a BOLD aesthetic direction: diff --git a/source/skills/normalize/SKILL.md b/source/skills/normalize/SKILL.md index b818d8603..5a8fc542e 100644 --- a/source/skills/normalize/SKILL.md +++ b/source/skills/normalize/SKILL.md @@ -10,6 +10,12 @@ user-invokable: true Analyze and redesign the feature to perfectly match our design system standards, aesthetics, and established patterns. +## MANDATORY PREPARATION + +Use the frontend-design skill — 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 teach-impeccable first. + +--- + ## Plan Before making changes, deeply understand the context: diff --git a/source/skills/onboard/SKILL.md b/source/skills/onboard/SKILL.md index f11e88d4f..46bf34d96 100644 --- a/source/skills/onboard/SKILL.md +++ b/source/skills/onboard/SKILL.md @@ -10,20 +10,7 @@ user-invokable: true ## MANDATORY PREPARATION -### Context Gathering (Do This First) - -You cannot do a great job without having necessary context, such as target audience (critical), desired use-cases (critical), the "aha moment" you want users to reach, and what users' experience level and motivation looks like. - -Attempt to gather these from the current thread or codebase. - -1. If you don't find *exact* information and have to infer from existing design and functionality, you MUST STOP and {{ask_instruction}} whether you got it right. -2. Otherwise, if you can't fully infer or your level of confidence is medium or lower, you MUST {{ask_instruction}} clarifying questions first to complete your context. - -Do NOT proceed until you have answers. Onboarding designed for the wrong audience wastes everyone's time. - -### Use frontend-design skill - -Use the frontend-design skill for design principles and anti-patterns. Do NOT proceed until it has executed and you know all DO's and DON'Ts. +Use the frontend-design skill — 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 teach-impeccable first. Additionally gather: the "aha moment" you want users to reach, and users' experience level. --- diff --git a/source/skills/polish/SKILL.md b/source/skills/polish/SKILL.md index ff4aa5312..cfdeda837 100644 --- a/source/skills/polish/SKILL.md +++ b/source/skills/polish/SKILL.md @@ -8,7 +8,11 @@ args: user-invokable: true --- -**First**: Use the frontend-design skill for design principles and anti-patterns. +## MANDATORY PREPARATION + +Use the frontend-design skill — 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 teach-impeccable first. Additionally gather: quality bar (MVP vs flagship). + +--- Perform a meticulous final pass to catch all the small details that separate good work from great work. The difference between shipped and polished. diff --git a/source/skills/quieter/SKILL.md b/source/skills/quieter/SKILL.md index aa59a9671..503a522c7 100644 --- a/source/skills/quieter/SKILL.md +++ b/source/skills/quieter/SKILL.md @@ -12,20 +12,7 @@ Reduce visual intensity in designs that are too bold, aggressive, or overstimula ## MANDATORY PREPARATION -### Context Gathering (Do This First) - -You cannot do a great job without having necessary context, such as target audience (critical), desired use-cases (critical), brand personality/tone, and everything else that a great human designer would need as well. - -Attempt to gather these from the current thread or codebase. - -1. If you don't find *exact* information and have to infer from existing design and functionality, you MUST STOP and {{ask_instruction}} whether you got it right. -2. Otherwise, if you can't fully infer or your level of confidence is medium or lower, you MUST {{ask_instruction}} clarifying questions first to complete your context. - -Do NOT proceed until you have answers. Guessing leads to generic design. - -### Use frontend-design skill - -Use the frontend-design skill for design principles and anti-patterns. Do NOT proceed until it has executed and you know all DO's and DON'Ts. +Use the frontend-design skill — 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 teach-impeccable first. --- diff --git a/source/skills/teach-impeccable/SKILL.md b/source/skills/teach-impeccable/SKILL.md index 18f5479f5..64a7a1b73 100644 --- a/source/skills/teach-impeccable/SKILL.md +++ b/source/skills/teach-impeccable/SKILL.md @@ -64,6 +64,8 @@ Synthesize your findings and the user's answers into a `## Design Context` secti [3-5 principles derived from the conversation that should guide all design decisions] ``` -Write this section to {{config_file}} in the project root. If the file exists, append or update the Design Context section. +Write this section to `.impeccable.md` in the project root. If the file already exists, update the Design Context section in place. + +Then {{ask_instruction}} whether they'd also like the Design Context appended to {{config_file}}. If yes, append or update the section there as well. Confirm completion and summarize the key design principles that will now guide all future work. diff --git a/tests/lib/utils.test.js b/tests/lib/utils.test.js index ba8739d3e..5af8cbe99 100644 --- a/tests/lib/utils.test.js +++ b/tests/lib/utils.test.js @@ -620,7 +620,7 @@ describe('replacePlaceholders', () => { test('should replace {{ask_instruction}} with provider-specific value', () => { const result = replacePlaceholders('{{ask_instruction}}', 'claude-code'); - expect(result).toBe('STOP and call the AskUserQuestionTool to clarify.'); + expect(result).toBe('STOP and call the AskUserQuestion tool to clarify.'); const cursorResult = replacePlaceholders('{{ask_instruction}}', 'cursor'); expect(cursorResult).toBe('ask the user directly to clarify what you cannot infer.'); @@ -648,7 +648,7 @@ describe('replacePlaceholders', () => { test('should replace multiple placeholders in the same string', () => { const result = replacePlaceholders('{{model}} uses {{config_file}} and {{ask_instruction}}', 'claude-code'); - expect(result).toBe('Claude uses CLAUDE.md and STOP and call the AskUserQuestionTool to clarify.'); + expect(result).toBe('Claude uses CLAUDE.md and STOP and call the AskUserQuestion tool to clarify.'); }); test('should replace multiple occurrences of the same placeholder', () => {