USP
Unlike generic AI design tools, Impeccable uses 7 domain-specific reference files and 27 deterministic anti-pattern rules to guide AI, ensuring designs are unique, refined, and avoid common pitfalls, offering a shared, precise design vocab…
Use cases
- 01Auditing frontend designs for accessibility and performance
- 02Critiquing UX design for hierarchy and clarity
- 03Polishing UI for design system alignment
- 04Adding purposeful motion and strategic color
- 05Adapting designs for different devices
Detected files (8)
.opencode/skills/impeccable/SKILL.mdskillShow content (14127 bytes)
--- name: impeccable description: Use when the user wants to design, redesign, shape, critique, audit, polish, clarify, distill, harden, optimize, adapt, animate, colorize, extract, or otherwise improve a frontend interface. Covers websites, landing pages, dashboards, product UI, app shells, components, forms, settings, onboarding, and empty states. Handles UX review, visual hierarchy, information architecture, cognitive load, accessibility, performance, responsive behavior, theming, anti-patterns, typography, fonts, spacing, layout, alignment, color, motion, micro-interactions, UX copy, error states, edge cases, i18n, and reusable design systems or tokens. Also use for bland designs that need to become bolder or more delightful, loud designs that should become quieter, live browser iteration on UI elements, or ambitious visual effects that should feel technically extraordinary. Not for backend-only or non-UI tasks. version: 3.0.7 user-invocable: true argument-hint: "[craft|shape · audit|critique · animate|bolder|colorize|delight|layout|overdrive|quieter|typeset · adapt|clarify|distill · harden|onboard|optimize|polish · teach|document|extract|live] [target]" license: Apache 2.0. Based on Anthropic's frontend-design skill. See NOTICE.md for attribution. allowed-tools: - Bash(npx impeccable *) --- Designs and iterates production-grade frontend interfaces. Real working code, committed design choices, exceptional craft. ## Setup (non-optional) Before any design work or file edits, pass these gates. Skipping them produces generic output that ignores the project. | Gate | Required check | If fail | |---|---|---| | Context | The PRODUCT.md / DESIGN.md loader result is known from `node .opencode/skills/impeccable/scripts/load-context.mjs`. | Run the loader before continuing. | | Product | PRODUCT.md exists and is not empty or placeholder (`[TODO]` markers, <200 chars). | Run `/impeccable teach`, refresh context, then resume. Never synthesize PRODUCT.md from the user's original prompt alone. | | Command | The matching command reference is loaded when a sub-command is used. | Load the reference before continuing. | | Craft | `/impeccable craft` has a user-confirmed shape brief for this task. `teach` / PRODUCT.md never counts as shape. | Run `/impeccable shape` and wait for explicit brief confirmation. | | Image | Required visual probes / mocks are generated or skipped with a reason. | Resolve the image-generation gate in `shape.md` or `craft.md` before code. | | Mutation | All active gates above pass. | Do not edit project files yet. | Codex-style agents must state this before editing files: ```text IMPECCABLE_PREFLIGHT: context=pass product=pass command_reference=pass shape=pass|not_required image_gate=pass|skipped:<reason> mutation=open ``` For `/impeccable craft`, `shape=pass` is only valid after a separate user response approving the shape design brief, or when the user provided an already-confirmed brief in the request. Do not mark `shape=pass` after writing PRODUCT.md, summarizing assumptions, or drafting an unconfirmed brief yourself. Other harnesses should follow the same checklist when they can expose this state. ### 1. Context gathering Two files, case-insensitive. The loader looks at the project root by default and falls back to `.agents/context/` and `docs/` if the root is clean. Override with `IMPECCABLE_CONTEXT_DIR=path/to/dir` (absolute or relative to cwd). - **PRODUCT.md**: required. Users, brand, tone, anti-references, strategic principles. - **DESIGN.md**: optional, strongly recommended. Colors, typography, elevation, components. Load both in one call: ```bash node .opencode/skills/impeccable/scripts/load-context.mjs ``` Consume the full JSON output. Never pipe through `head`, `tail`, `grep`, or `jq`. The output's `contextDir` field tells you where the files were resolved from. If the output is already in this session's conversation history, don't re-run. Exceptions requiring a fresh load: you just ran `/impeccable teach` or `/impeccable document` (they rewrite the files), or the user manually edited one. `/impeccable live` already warms context via `live.mjs`. If you've run `live.mjs`, don't also run `load-context.mjs` this session. If PRODUCT.md is missing, empty, or placeholder (`[TODO]` markers, <200 chars): run `/impeccable teach`, then resume the user's original task with the fresh context. If the original task was `/impeccable craft`, resume into `/impeccable shape` before any implementation work. If DESIGN.md is missing: nudge once per session (*"Run `/impeccable document` for more on-brand output"*), then proceed. ### 2. Register Every design task is **brand** (marketing, landing, campaign, long-form content, portfolio: design IS the product) or **product** (app UI, admin, dashboard, tool: design SERVES the product). Identify before designing. Priority: (1) cue in the task itself ("landing page" vs "dashboard"); (2) the surface in focus (the page, file, or route being worked on); (3) `register` field in PRODUCT.md. First match wins. If PRODUCT.md lacks the `register` field (legacy), infer it once from its "Users" and "Product Purpose" sections, then cache the inferred value for the session. Suggest the user run `/impeccable teach` to add the field explicitly. Load the matching reference: [reference/brand.md](reference/brand.md) or [reference/product.md](reference/product.md). The shared design laws below apply to both. ## Shared design laws Apply to every design, both registers. Match implementation complexity to the aesthetic vision: maximalism needs elaborate code, minimalism needs precision. Interpret creatively. Vary across projects; never converge on the same choices. Claude is capable of extraordinary work. Don't hold back. ### Color - Use OKLCH. Reduce chroma as lightness approaches 0 or 100; high chroma at extremes looks garish. - Never use `#000` or `#fff`. Tint every neutral toward the brand hue (chroma 0.005–0.01 is enough). - Pick a **color strategy** before picking colors. Four steps on the commitment axis: - **Restrained**: tinted neutrals + one accent ≤10%. Product default; brand minimalism. - **Committed**: one saturated color carries 30–60% of the surface. Brand default for identity-driven pages. - **Full palette**: 3–4 named roles, each used deliberately. Brand campaigns; product data viz. - **Drenched**: the surface IS the color. Brand heroes, campaign pages. - The "one accent ≤10%" rule is Restrained only. Committed / Full palette / Drenched exceed it on purpose. Don't collapse every design to Restrained by reflex. ### Theme Dark vs. light is never a default. Not dark "because tools look cool dark." Not light "to be safe." Before choosing, write one sentence of physical scene: who uses this, where, under what ambient light, in what mood. If the sentence doesn't force the answer, it's not concrete enough. Add detail until it does. "Observability dashboard" does not force an answer. "SRE glancing at incident severity on a 27-inch monitor at 2am in a dim room" does. Run the sentence, not the category. ### Typography - Cap body line length at 65–75ch. - Hierarchy through scale + weight contrast (≥1.25 ratio between steps). Avoid flat scales. ### Layout - Vary spacing for rhythm. Same padding everywhere is monotony. - Cards are the lazy answer. Use them only when they're truly the best affordance. Nested cards are always wrong. - Don't wrap everything in a container. Most things don't need one. ### Motion - Don't animate CSS layout properties. - Ease out with exponential curves (ease-out-quart / quint / expo). No bounce, no elastic. ### Absolute bans Match-and-refuse. If you're about to write any of these, rewrite the element with different structure. - **Side-stripe borders.** `border-left` or `border-right` greater than 1px as a colored accent on cards, list items, callouts, or alerts. Never intentional. Rewrite with full borders, background tints, leading numbers/icons, or nothing. - **Gradient text.** `background-clip: text` combined with a gradient background. Decorative, never meaningful. Use a single solid color. Emphasis via weight or size. - **Glassmorphism as default.** Blurs and glass cards used decoratively. Rare and purposeful, or nothing. - **The hero-metric template.** Big number, small label, supporting stats, gradient accent. SaaS cliché. - **Identical card grids.** Same-sized cards with icon + heading + text, repeated endlessly. - **Modal as first thought.** Modals are usually laziness. Exhaust inline / progressive alternatives first. ### Copy - Every word earns its place. No restated headings, no intros that repeat the title. - **No em dashes.** Use commas, colons, semicolons, periods, or parentheses. Also not `--`. ### The AI slop test If someone could look at this interface and say "AI made that" without doubt, it's failed. Cross-register failures are the absolute bans above. Register-specific failures live in each reference. **Category-reflex check.** Run at two altitudes; the second one catches what the first one misses. - **First-order:** if someone could guess the theme + palette from the category alone ("observability → dark blue", "healthcare → white + teal", "finance → navy + gold", "crypto → neon on black"), it's the first training-data reflex. Rework the scene sentence and color strategy until the answer isn't obvious from the domain. - **Second-order:** if someone could guess the aesthetic family from category-plus-anti-references ("AI workflow tool that's not SaaS-cream → editorial-typographic", "fintech that's not navy-and-gold → terminal-native dark mode"), it's the trap one tier deeper. The first reflex was avoided; the second wasn't. Rework until both answers are not obvious. The brand register's [reflex-reject aesthetic lanes](reference/brand.md) list catches the currently-saturated families. ## Commands | Command | Category | Description | Reference | |---|---|---|---| | `craft [feature]` | Build | Shape, then build a feature end-to-end | [reference/craft.md](reference/craft.md) | | `shape [feature]` | Build | Plan UX/UI before writing code | [reference/shape.md](reference/shape.md) | | `teach` | Build | Set up PRODUCT.md and DESIGN.md context | [reference/teach.md](reference/teach.md) | | `document` | Build | Generate DESIGN.md from existing project code | [reference/document.md](reference/document.md) | | `extract [target]` | Build | Pull reusable tokens and components into design system | [reference/extract.md](reference/extract.md) | | `critique [target]` | Evaluate | UX design review with heuristic scoring | [reference/critique.md](reference/critique.md) | | `audit [target]` | Evaluate | Technical quality checks (a11y, perf, responsive) | [reference/audit.md](reference/audit.md) | | `polish [target]` | Refine | Final quality pass before shipping | [reference/polish.md](reference/polish.md) | | `bolder [target]` | Refine | Amplify safe or bland designs | [reference/bolder.md](reference/bolder.md) | | `quieter [target]` | Refine | Tone down aggressive or overstimulating designs | [reference/quieter.md](reference/quieter.md) | | `distill [target]` | Refine | Strip to essence, remove complexity | [reference/distill.md](reference/distill.md) | | `harden [target]` | Refine | Production-ready: errors, i18n, edge cases | [reference/harden.md](reference/harden.md) | | `onboard [target]` | Refine | Design first-run flows, empty states, activation | [reference/onboard.md](reference/onboard.md) | | `animate [target]` | Enhance | Add purposeful animations and motion | [reference/animate.md](reference/animate.md) | | `colorize [target]` | Enhance | Add strategic color to monochromatic UIs | [reference/colorize.md](reference/colorize.md) | | `typeset [target]` | Enhance | Improve typography hierarchy and fonts | [reference/typeset.md](reference/typeset.md) | | `layout [target]` | Enhance | Fix spacing, rhythm, and visual hierarchy | [reference/layout.md](reference/layout.md) | | `delight [target]` | Enhance | Add personality and memorable touches | [reference/delight.md](reference/delight.md) | | `overdrive [target]` | Enhance | Push past conventional limits | [reference/overdrive.md](reference/overdrive.md) | | `clarify [target]` | Fix | Improve UX copy, labels, and error messages | [reference/clarify.md](reference/clarify.md) | | `adapt [target]` | Fix | Adapt for different devices and screen sizes | [reference/adapt.md](reference/adapt.md) | | `optimize [target]` | Fix | Diagnose and fix UI performance | [reference/optimize.md](reference/optimize.md) | | `live` | Iterate | Visual variant mode: pick elements in the browser, generate alternatives | [reference/live.md](reference/live.md) | Plus two management commands: `pin <command>` and `unpin <command>`, detailed below. ### Routing rules 1. **No argument**: render the table above as the user-facing command menu, grouped by category. Ask what they'd like to do. 2. **First word matches a command**: load its reference file and follow its instructions. Everything after the command name is the target. 3. **First word doesn't match**: general design invocation. Apply the setup steps, shared design laws, and the loaded register reference, using the full argument as context. Setup (context gathering, register) is already loaded by then; sub-commands don't re-invoke `/impeccable`. If the first word is `craft`, setup still runs first, but [reference/craft.md](reference/craft.md) owns the rest of the flow. If setup invokes `teach` as a blocker, finish teach, refresh context, then resume the original command and target. ## Pin / Unpin **Pin** creates a standalone shortcut so `/<command>` invokes `/impeccable <command>` directly. **Unpin** removes it. The script writes to every harness directory present in the project. ```bash node .opencode/skills/impeccable/scripts/pin.mjs <pin|unpin> <command> ``` Valid `<command>` is any command from the table above. Report the script's result concisely. Confirm the new shortcut on success, relay stderr verbatim on error..agents/skills/impeccable/SKILL.mdskillShow content (13728 bytes)
--- name: impeccable description: Use when the user wants to design, redesign, shape, critique, audit, polish, clarify, distill, harden, optimize, adapt, animate, colorize, extract, or otherwise improve a frontend interface. Covers websites, landing pages, dashboards, product UI, app shells, components, forms, settings, onboarding, and empty states. Handles UX review, visual hierarchy, information architecture, cognitive load, accessibility, performance, responsive behavior, theming, anti-patterns, typography, fonts, spacing, layout, alignment, color, motion, micro-interactions, UX copy, error states, edge cases, i18n, and reusable design systems or tokens. Also use for bland designs that need to become bolder or more delightful, loud designs that should become quieter, live browser iteration on UI elements, or ambitious visual effects that should feel technically extraordinary. Not for backend-only or non-UI tasks. --- Designs and iterates production-grade frontend interfaces. Real working code, committed design choices, exceptional craft. ## Setup (non-optional) Before any design work or file edits, pass these gates. Skipping them produces generic output that ignores the project. | Gate | Required check | If fail | |---|---|---| | Context | The PRODUCT.md / DESIGN.md loader result is known from `node .agents/skills/impeccable/scripts/load-context.mjs`. | Run the loader before continuing. | | Product | PRODUCT.md exists and is not empty or placeholder (`[TODO]` markers, <200 chars). | Run `$impeccable teach`, refresh context, then resume. Never synthesize PRODUCT.md from the user's original prompt alone. | | Command | The matching command reference is loaded when a sub-command is used. | Load the reference before continuing. | | Craft | `$impeccable craft` has a user-confirmed shape brief for this task. `teach` / PRODUCT.md never counts as shape. | Run `$impeccable shape` and wait for explicit brief confirmation. | | Image | Required visual probes / mocks are generated or skipped with a reason. | Resolve the image-generation gate in `shape.md` or `craft.md` before code. | | Mutation | All active gates above pass. | Do not edit project files yet. | Codex-style agents must state this before editing files: ```text IMPECCABLE_PREFLIGHT: context=pass product=pass command_reference=pass shape=pass|not_required image_gate=pass|skipped:<reason> mutation=open ``` For `$impeccable craft`, `shape=pass` is only valid after a separate user response approving the shape design brief, or when the user provided an already-confirmed brief in the request. Do not mark `shape=pass` after writing PRODUCT.md, summarizing assumptions, or drafting an unconfirmed brief yourself. Other harnesses should follow the same checklist when they can expose this state. ### 1. Context gathering Two files, case-insensitive. The loader looks at the project root by default and falls back to `.agents/context/` and `docs/` if the root is clean. Override with `IMPECCABLE_CONTEXT_DIR=path/to/dir` (absolute or relative to cwd). - **PRODUCT.md**: required. Users, brand, tone, anti-references, strategic principles. - **DESIGN.md**: optional, strongly recommended. Colors, typography, elevation, components. Load both in one call: ```bash node .agents/skills/impeccable/scripts/load-context.mjs ``` Consume the full JSON output. Never pipe through `head`, `tail`, `grep`, or `jq`. The output's `contextDir` field tells you where the files were resolved from. If the output is already in this session's conversation history, don't re-run. Exceptions requiring a fresh load: you just ran `$impeccable teach` or `$impeccable document` (they rewrite the files), or the user manually edited one. `$impeccable live` already warms context via `live.mjs`. If you've run `live.mjs`, don't also run `load-context.mjs` this session. If PRODUCT.md is missing, empty, or placeholder (`[TODO]` markers, <200 chars): run `$impeccable teach`, then resume the user's original task with the fresh context. If the original task was `$impeccable craft`, resume into `$impeccable shape` before any implementation work. If DESIGN.md is missing: nudge once per session (*"Run `$impeccable document` for more on-brand output"*), then proceed. ### 2. Register Every design task is **brand** (marketing, landing, campaign, long-form content, portfolio: design IS the product) or **product** (app UI, admin, dashboard, tool: design SERVES the product). Identify before designing. Priority: (1) cue in the task itself ("landing page" vs "dashboard"); (2) the surface in focus (the page, file, or route being worked on); (3) `register` field in PRODUCT.md. First match wins. If PRODUCT.md lacks the `register` field (legacy), infer it once from its "Users" and "Product Purpose" sections, then cache the inferred value for the session. Suggest the user run `$impeccable teach` to add the field explicitly. Load the matching reference: [reference/brand.md](reference/brand.md) or [reference/product.md](reference/product.md). The shared design laws below apply to both. ## Shared design laws Apply to every design, both registers. Match implementation complexity to the aesthetic vision: maximalism needs elaborate code, minimalism needs precision. Interpret creatively. Vary across projects; never converge on the same choices. GPT is capable of extraordinary work. Don't hold back. ### Color - Use OKLCH. Reduce chroma as lightness approaches 0 or 100; high chroma at extremes looks garish. - Never use `#000` or `#fff`. Tint every neutral toward the brand hue (chroma 0.005–0.01 is enough). - Pick a **color strategy** before picking colors. Four steps on the commitment axis: - **Restrained**: tinted neutrals + one accent ≤10%. Product default; brand minimalism. - **Committed**: one saturated color carries 30–60% of the surface. Brand default for identity-driven pages. - **Full palette**: 3–4 named roles, each used deliberately. Brand campaigns; product data viz. - **Drenched**: the surface IS the color. Brand heroes, campaign pages. - The "one accent ≤10%" rule is Restrained only. Committed / Full palette / Drenched exceed it on purpose. Don't collapse every design to Restrained by reflex. ### Theme Dark vs. light is never a default. Not dark "because tools look cool dark." Not light "to be safe." Before choosing, write one sentence of physical scene: who uses this, where, under what ambient light, in what mood. If the sentence doesn't force the answer, it's not concrete enough. Add detail until it does. "Observability dashboard" does not force an answer. "SRE glancing at incident severity on a 27-inch monitor at 2am in a dim room" does. Run the sentence, not the category. ### Typography - Cap body line length at 65–75ch. - Hierarchy through scale + weight contrast (≥1.25 ratio between steps). Avoid flat scales. ### Layout - Vary spacing for rhythm. Same padding everywhere is monotony. - Cards are the lazy answer. Use them only when they're truly the best affordance. Nested cards are always wrong. - Don't wrap everything in a container. Most things don't need one. ### Motion - Don't animate CSS layout properties. - Ease out with exponential curves (ease-out-quart / quint / expo). No bounce, no elastic. ### Absolute bans Match-and-refuse. If you're about to write any of these, rewrite the element with different structure. - **Side-stripe borders.** `border-left` or `border-right` greater than 1px as a colored accent on cards, list items, callouts, or alerts. Never intentional. Rewrite with full borders, background tints, leading numbers/icons, or nothing. - **Gradient text.** `background-clip: text` combined with a gradient background. Decorative, never meaningful. Use a single solid color. Emphasis via weight or size. - **Glassmorphism as default.** Blurs and glass cards used decoratively. Rare and purposeful, or nothing. - **The hero-metric template.** Big number, small label, supporting stats, gradient accent. SaaS cliché. - **Identical card grids.** Same-sized cards with icon + heading + text, repeated endlessly. - **Modal as first thought.** Modals are usually laziness. Exhaust inline / progressive alternatives first. ### Copy - Every word earns its place. No restated headings, no intros that repeat the title. - **No em dashes.** Use commas, colons, semicolons, periods, or parentheses. Also not `--`. ### The AI slop test If someone could look at this interface and say "AI made that" without doubt, it's failed. Cross-register failures are the absolute bans above. Register-specific failures live in each reference. **Category-reflex check.** Run at two altitudes; the second one catches what the first one misses. - **First-order:** if someone could guess the theme + palette from the category alone ("observability → dark blue", "healthcare → white + teal", "finance → navy + gold", "crypto → neon on black"), it's the first training-data reflex. Rework the scene sentence and color strategy until the answer isn't obvious from the domain. - **Second-order:** if someone could guess the aesthetic family from category-plus-anti-references ("AI workflow tool that's not SaaS-cream → editorial-typographic", "fintech that's not navy-and-gold → terminal-native dark mode"), it's the trap one tier deeper. The first reflex was avoided; the second wasn't. Rework until both answers are not obvious. The brand register's [reflex-reject aesthetic lanes](reference/brand.md) list catches the currently-saturated families. ## Commands | Command | Category | Description | Reference | |---|---|---|---| | `craft [feature]` | Build | Shape, then build a feature end-to-end | [reference/craft.md](reference/craft.md) | | `shape [feature]` | Build | Plan UX/UI before writing code | [reference/shape.md](reference/shape.md) | | `teach` | Build | Set up PRODUCT.md and DESIGN.md context | [reference/teach.md](reference/teach.md) | | `document` | Build | Generate DESIGN.md from existing project code | [reference/document.md](reference/document.md) | | `extract [target]` | Build | Pull reusable tokens and components into design system | [reference/extract.md](reference/extract.md) | | `critique [target]` | Evaluate | UX design review with heuristic scoring | [reference/critique.md](reference/critique.md) | | `audit [target]` | Evaluate | Technical quality checks (a11y, perf, responsive) | [reference/audit.md](reference/audit.md) | | `polish [target]` | Refine | Final quality pass before shipping | [reference/polish.md](reference/polish.md) | | `bolder [target]` | Refine | Amplify safe or bland designs | [reference/bolder.md](reference/bolder.md) | | `quieter [target]` | Refine | Tone down aggressive or overstimulating designs | [reference/quieter.md](reference/quieter.md) | | `distill [target]` | Refine | Strip to essence, remove complexity | [reference/distill.md](reference/distill.md) | | `harden [target]` | Refine | Production-ready: errors, i18n, edge cases | [reference/harden.md](reference/harden.md) | | `onboard [target]` | Refine | Design first-run flows, empty states, activation | [reference/onboard.md](reference/onboard.md) | | `animate [target]` | Enhance | Add purposeful animations and motion | [reference/animate.md](reference/animate.md) | | `colorize [target]` | Enhance | Add strategic color to monochromatic UIs | [reference/colorize.md](reference/colorize.md) | | `typeset [target]` | Enhance | Improve typography hierarchy and fonts | [reference/typeset.md](reference/typeset.md) | | `layout [target]` | Enhance | Fix spacing, rhythm, and visual hierarchy | [reference/layout.md](reference/layout.md) | | `delight [target]` | Enhance | Add personality and memorable touches | [reference/delight.md](reference/delight.md) | | `overdrive [target]` | Enhance | Push past conventional limits | [reference/overdrive.md](reference/overdrive.md) | | `clarify [target]` | Fix | Improve UX copy, labels, and error messages | [reference/clarify.md](reference/clarify.md) | | `adapt [target]` | Fix | Adapt for different devices and screen sizes | [reference/adapt.md](reference/adapt.md) | | `optimize [target]` | Fix | Diagnose and fix UI performance | [reference/optimize.md](reference/optimize.md) | | `live` | Iterate | Visual variant mode: pick elements in the browser, generate alternatives | [reference/live.md](reference/live.md) | Plus two management commands: `pin <command>` and `unpin <command>`, detailed below. ### Routing rules 1. **No argument**: render the table above as the user-facing command menu, grouped by category. Ask what they'd like to do. 2. **First word matches a command**: load its reference file and follow its instructions. Everything after the command name is the target. 3. **First word doesn't match**: general design invocation. Apply the setup steps, shared design laws, and the loaded register reference, using the full argument as context. Setup (context gathering, register) is already loaded by then; sub-commands don't re-invoke `$impeccable`. If the first word is `craft`, setup still runs first, but [reference/craft.md](reference/craft.md) owns the rest of the flow. If setup invokes `teach` as a blocker, finish teach, refresh context, then resume the original command and target. ## Pin / Unpin **Pin** creates a standalone shortcut so `$<command>` invokes `$impeccable <command>` directly. **Unpin** removes it. The script writes to every harness directory present in the project. ```bash node .agents/skills/impeccable/scripts/pin.mjs <pin|unpin> <command> ``` Valid `<command>` is any command from the table above. Report the script's result concisely. Confirm the new shortcut on success, relay stderr verbatim on error..claude/skills/impeccable/SKILL.mdskillShow content (14121 bytes)
--- name: impeccable description: Use when the user wants to design, redesign, shape, critique, audit, polish, clarify, distill, harden, optimize, adapt, animate, colorize, extract, or otherwise improve a frontend interface. Covers websites, landing pages, dashboards, product UI, app shells, components, forms, settings, onboarding, and empty states. Handles UX review, visual hierarchy, information architecture, cognitive load, accessibility, performance, responsive behavior, theming, anti-patterns, typography, fonts, spacing, layout, alignment, color, motion, micro-interactions, UX copy, error states, edge cases, i18n, and reusable design systems or tokens. Also use for bland designs that need to become bolder or more delightful, loud designs that should become quieter, live browser iteration on UI elements, or ambitious visual effects that should feel technically extraordinary. Not for backend-only or non-UI tasks. version: 3.0.7 user-invocable: true argument-hint: "[craft|shape · audit|critique · animate|bolder|colorize|delight|layout|overdrive|quieter|typeset · adapt|clarify|distill · harden|onboard|optimize|polish · teach|document|extract|live] [target]" license: Apache 2.0. Based on Anthropic's frontend-design skill. See NOTICE.md for attribution. allowed-tools: - Bash(npx impeccable *) --- Designs and iterates production-grade frontend interfaces. Real working code, committed design choices, exceptional craft. ## Setup (non-optional) Before any design work or file edits, pass these gates. Skipping them produces generic output that ignores the project. | Gate | Required check | If fail | |---|---|---| | Context | The PRODUCT.md / DESIGN.md loader result is known from `node .claude/skills/impeccable/scripts/load-context.mjs`. | Run the loader before continuing. | | Product | PRODUCT.md exists and is not empty or placeholder (`[TODO]` markers, <200 chars). | Run `/impeccable teach`, refresh context, then resume. Never synthesize PRODUCT.md from the user's original prompt alone. | | Command | The matching command reference is loaded when a sub-command is used. | Load the reference before continuing. | | Craft | `/impeccable craft` has a user-confirmed shape brief for this task. `teach` / PRODUCT.md never counts as shape. | Run `/impeccable shape` and wait for explicit brief confirmation. | | Image | Required visual probes / mocks are generated or skipped with a reason. | Resolve the image-generation gate in `shape.md` or `craft.md` before code. | | Mutation | All active gates above pass. | Do not edit project files yet. | Codex-style agents must state this before editing files: ```text IMPECCABLE_PREFLIGHT: context=pass product=pass command_reference=pass shape=pass|not_required image_gate=pass|skipped:<reason> mutation=open ``` For `/impeccable craft`, `shape=pass` is only valid after a separate user response approving the shape design brief, or when the user provided an already-confirmed brief in the request. Do not mark `shape=pass` after writing PRODUCT.md, summarizing assumptions, or drafting an unconfirmed brief yourself. Other harnesses should follow the same checklist when they can expose this state. ### 1. Context gathering Two files, case-insensitive. The loader looks at the project root by default and falls back to `.agents/context/` and `docs/` if the root is clean. Override with `IMPECCABLE_CONTEXT_DIR=path/to/dir` (absolute or relative to cwd). - **PRODUCT.md**: required. Users, brand, tone, anti-references, strategic principles. - **DESIGN.md**: optional, strongly recommended. Colors, typography, elevation, components. Load both in one call: ```bash node .claude/skills/impeccable/scripts/load-context.mjs ``` Consume the full JSON output. Never pipe through `head`, `tail`, `grep`, or `jq`. The output's `contextDir` field tells you where the files were resolved from. If the output is already in this session's conversation history, don't re-run. Exceptions requiring a fresh load: you just ran `/impeccable teach` or `/impeccable document` (they rewrite the files), or the user manually edited one. `/impeccable live` already warms context via `live.mjs`. If you've run `live.mjs`, don't also run `load-context.mjs` this session. If PRODUCT.md is missing, empty, or placeholder (`[TODO]` markers, <200 chars): run `/impeccable teach`, then resume the user's original task with the fresh context. If the original task was `/impeccable craft`, resume into `/impeccable shape` before any implementation work. If DESIGN.md is missing: nudge once per session (*"Run `/impeccable document` for more on-brand output"*), then proceed. ### 2. Register Every design task is **brand** (marketing, landing, campaign, long-form content, portfolio: design IS the product) or **product** (app UI, admin, dashboard, tool: design SERVES the product). Identify before designing. Priority: (1) cue in the task itself ("landing page" vs "dashboard"); (2) the surface in focus (the page, file, or route being worked on); (3) `register` field in PRODUCT.md. First match wins. If PRODUCT.md lacks the `register` field (legacy), infer it once from its "Users" and "Product Purpose" sections, then cache the inferred value for the session. Suggest the user run `/impeccable teach` to add the field explicitly. Load the matching reference: [reference/brand.md](reference/brand.md) or [reference/product.md](reference/product.md). The shared design laws below apply to both. ## Shared design laws Apply to every design, both registers. Match implementation complexity to the aesthetic vision: maximalism needs elaborate code, minimalism needs precision. Interpret creatively. Vary across projects; never converge on the same choices. Claude is capable of extraordinary work. Don't hold back. ### Color - Use OKLCH. Reduce chroma as lightness approaches 0 or 100; high chroma at extremes looks garish. - Never use `#000` or `#fff`. Tint every neutral toward the brand hue (chroma 0.005–0.01 is enough). - Pick a **color strategy** before picking colors. Four steps on the commitment axis: - **Restrained**: tinted neutrals + one accent ≤10%. Product default; brand minimalism. - **Committed**: one saturated color carries 30–60% of the surface. Brand default for identity-driven pages. - **Full palette**: 3–4 named roles, each used deliberately. Brand campaigns; product data viz. - **Drenched**: the surface IS the color. Brand heroes, campaign pages. - The "one accent ≤10%" rule is Restrained only. Committed / Full palette / Drenched exceed it on purpose. Don't collapse every design to Restrained by reflex. ### Theme Dark vs. light is never a default. Not dark "because tools look cool dark." Not light "to be safe." Before choosing, write one sentence of physical scene: who uses this, where, under what ambient light, in what mood. If the sentence doesn't force the answer, it's not concrete enough. Add detail until it does. "Observability dashboard" does not force an answer. "SRE glancing at incident severity on a 27-inch monitor at 2am in a dim room" does. Run the sentence, not the category. ### Typography - Cap body line length at 65–75ch. - Hierarchy through scale + weight contrast (≥1.25 ratio between steps). Avoid flat scales. ### Layout - Vary spacing for rhythm. Same padding everywhere is monotony. - Cards are the lazy answer. Use them only when they're truly the best affordance. Nested cards are always wrong. - Don't wrap everything in a container. Most things don't need one. ### Motion - Don't animate CSS layout properties. - Ease out with exponential curves (ease-out-quart / quint / expo). No bounce, no elastic. ### Absolute bans Match-and-refuse. If you're about to write any of these, rewrite the element with different structure. - **Side-stripe borders.** `border-left` or `border-right` greater than 1px as a colored accent on cards, list items, callouts, or alerts. Never intentional. Rewrite with full borders, background tints, leading numbers/icons, or nothing. - **Gradient text.** `background-clip: text` combined with a gradient background. Decorative, never meaningful. Use a single solid color. Emphasis via weight or size. - **Glassmorphism as default.** Blurs and glass cards used decoratively. Rare and purposeful, or nothing. - **The hero-metric template.** Big number, small label, supporting stats, gradient accent. SaaS cliché. - **Identical card grids.** Same-sized cards with icon + heading + text, repeated endlessly. - **Modal as first thought.** Modals are usually laziness. Exhaust inline / progressive alternatives first. ### Copy - Every word earns its place. No restated headings, no intros that repeat the title. - **No em dashes.** Use commas, colons, semicolons, periods, or parentheses. Also not `--`. ### The AI slop test If someone could look at this interface and say "AI made that" without doubt, it's failed. Cross-register failures are the absolute bans above. Register-specific failures live in each reference. **Category-reflex check.** Run at two altitudes; the second one catches what the first one misses. - **First-order:** if someone could guess the theme + palette from the category alone ("observability → dark blue", "healthcare → white + teal", "finance → navy + gold", "crypto → neon on black"), it's the first training-data reflex. Rework the scene sentence and color strategy until the answer isn't obvious from the domain. - **Second-order:** if someone could guess the aesthetic family from category-plus-anti-references ("AI workflow tool that's not SaaS-cream → editorial-typographic", "fintech that's not navy-and-gold → terminal-native dark mode"), it's the trap one tier deeper. The first reflex was avoided; the second wasn't. Rework until both answers are not obvious. The brand register's [reflex-reject aesthetic lanes](reference/brand.md) list catches the currently-saturated families. ## Commands | Command | Category | Description | Reference | |---|---|---|---| | `craft [feature]` | Build | Shape, then build a feature end-to-end | [reference/craft.md](reference/craft.md) | | `shape [feature]` | Build | Plan UX/UI before writing code | [reference/shape.md](reference/shape.md) | | `teach` | Build | Set up PRODUCT.md and DESIGN.md context | [reference/teach.md](reference/teach.md) | | `document` | Build | Generate DESIGN.md from existing project code | [reference/document.md](reference/document.md) | | `extract [target]` | Build | Pull reusable tokens and components into design system | [reference/extract.md](reference/extract.md) | | `critique [target]` | Evaluate | UX design review with heuristic scoring | [reference/critique.md](reference/critique.md) | | `audit [target]` | Evaluate | Technical quality checks (a11y, perf, responsive) | [reference/audit.md](reference/audit.md) | | `polish [target]` | Refine | Final quality pass before shipping | [reference/polish.md](reference/polish.md) | | `bolder [target]` | Refine | Amplify safe or bland designs | [reference/bolder.md](reference/bolder.md) | | `quieter [target]` | Refine | Tone down aggressive or overstimulating designs | [reference/quieter.md](reference/quieter.md) | | `distill [target]` | Refine | Strip to essence, remove complexity | [reference/distill.md](reference/distill.md) | | `harden [target]` | Refine | Production-ready: errors, i18n, edge cases | [reference/harden.md](reference/harden.md) | | `onboard [target]` | Refine | Design first-run flows, empty states, activation | [reference/onboard.md](reference/onboard.md) | | `animate [target]` | Enhance | Add purposeful animations and motion | [reference/animate.md](reference/animate.md) | | `colorize [target]` | Enhance | Add strategic color to monochromatic UIs | [reference/colorize.md](reference/colorize.md) | | `typeset [target]` | Enhance | Improve typography hierarchy and fonts | [reference/typeset.md](reference/typeset.md) | | `layout [target]` | Enhance | Fix spacing, rhythm, and visual hierarchy | [reference/layout.md](reference/layout.md) | | `delight [target]` | Enhance | Add personality and memorable touches | [reference/delight.md](reference/delight.md) | | `overdrive [target]` | Enhance | Push past conventional limits | [reference/overdrive.md](reference/overdrive.md) | | `clarify [target]` | Fix | Improve UX copy, labels, and error messages | [reference/clarify.md](reference/clarify.md) | | `adapt [target]` | Fix | Adapt for different devices and screen sizes | [reference/adapt.md](reference/adapt.md) | | `optimize [target]` | Fix | Diagnose and fix UI performance | [reference/optimize.md](reference/optimize.md) | | `live` | Iterate | Visual variant mode: pick elements in the browser, generate alternatives | [reference/live.md](reference/live.md) | Plus two management commands: `pin <command>` and `unpin <command>`, detailed below. ### Routing rules 1. **No argument**: render the table above as the user-facing command menu, grouped by category. Ask what they'd like to do. 2. **First word matches a command**: load its reference file and follow its instructions. Everything after the command name is the target. 3. **First word doesn't match**: general design invocation. Apply the setup steps, shared design laws, and the loaded register reference, using the full argument as context. Setup (context gathering, register) is already loaded by then; sub-commands don't re-invoke `/impeccable`. If the first word is `craft`, setup still runs first, but [reference/craft.md](reference/craft.md) owns the rest of the flow. If setup invokes `teach` as a blocker, finish teach, refresh context, then resume the original command and target. ## Pin / Unpin **Pin** creates a standalone shortcut so `/<command>` invokes `/impeccable <command>` directly. **Unpin** removes it. The script writes to every harness directory present in the project. ```bash node .claude/skills/impeccable/scripts/pin.mjs <pin|unpin> <command> ``` Valid `<command>` is any command from the table above. Report the script's result concisely. Confirm the new shortcut on success, relay stderr verbatim on error..cursor/skills/impeccable/SKILL.mdskillShow content (13845 bytes)
--- name: impeccable description: Use when the user wants to design, redesign, shape, critique, audit, polish, clarify, distill, harden, optimize, adapt, animate, colorize, extract, or otherwise improve a frontend interface. Covers websites, landing pages, dashboards, product UI, app shells, components, forms, settings, onboarding, and empty states. Handles UX review, visual hierarchy, information architecture, cognitive load, accessibility, performance, responsive behavior, theming, anti-patterns, typography, fonts, spacing, layout, alignment, color, motion, micro-interactions, UX copy, error states, edge cases, i18n, and reusable design systems or tokens. Also use for bland designs that need to become bolder or more delightful, loud designs that should become quieter, live browser iteration on UI elements, or ambitious visual effects that should feel technically extraordinary. Not for backend-only or non-UI tasks. version: 3.0.7 license: Apache 2.0. Based on Anthropic's frontend-design skill. See NOTICE.md for attribution. --- Designs and iterates production-grade frontend interfaces. Real working code, committed design choices, exceptional craft. ## Setup (non-optional) Before any design work or file edits, pass these gates. Skipping them produces generic output that ignores the project. | Gate | Required check | If fail | |---|---|---| | Context | The PRODUCT.md / DESIGN.md loader result is known from `node .cursor/skills/impeccable/scripts/load-context.mjs`. | Run the loader before continuing. | | Product | PRODUCT.md exists and is not empty or placeholder (`[TODO]` markers, <200 chars). | Run `/impeccable teach`, refresh context, then resume. Never synthesize PRODUCT.md from the user's original prompt alone. | | Command | The matching command reference is loaded when a sub-command is used. | Load the reference before continuing. | | Craft | `/impeccable craft` has a user-confirmed shape brief for this task. `teach` / PRODUCT.md never counts as shape. | Run `/impeccable shape` and wait for explicit brief confirmation. | | Image | Required visual probes / mocks are generated or skipped with a reason. | Resolve the image-generation gate in `shape.md` or `craft.md` before code. | | Mutation | All active gates above pass. | Do not edit project files yet. | Codex-style agents must state this before editing files: ```text IMPECCABLE_PREFLIGHT: context=pass product=pass command_reference=pass shape=pass|not_required image_gate=pass|skipped:<reason> mutation=open ``` For `/impeccable craft`, `shape=pass` is only valid after a separate user response approving the shape design brief, or when the user provided an already-confirmed brief in the request. Do not mark `shape=pass` after writing PRODUCT.md, summarizing assumptions, or drafting an unconfirmed brief yourself. Other harnesses should follow the same checklist when they can expose this state. ### 1. Context gathering Two files, case-insensitive. The loader looks at the project root by default and falls back to `.agents/context/` and `docs/` if the root is clean. Override with `IMPECCABLE_CONTEXT_DIR=path/to/dir` (absolute or relative to cwd). - **PRODUCT.md**: required. Users, brand, tone, anti-references, strategic principles. - **DESIGN.md**: optional, strongly recommended. Colors, typography, elevation, components. Load both in one call: ```bash node .cursor/skills/impeccable/scripts/load-context.mjs ``` Consume the full JSON output. Never pipe through `head`, `tail`, `grep`, or `jq`. The output's `contextDir` field tells you where the files were resolved from. If the output is already in this session's conversation history, don't re-run. Exceptions requiring a fresh load: you just ran `/impeccable teach` or `/impeccable document` (they rewrite the files), or the user manually edited one. `/impeccable live` already warms context via `live.mjs`. If you've run `live.mjs`, don't also run `load-context.mjs` this session. If PRODUCT.md is missing, empty, or placeholder (`[TODO]` markers, <200 chars): run `/impeccable teach`, then resume the user's original task with the fresh context. If the original task was `/impeccable craft`, resume into `/impeccable shape` before any implementation work. If DESIGN.md is missing: nudge once per session (*"Run `/impeccable document` for more on-brand output"*), then proceed. ### 2. Register Every design task is **brand** (marketing, landing, campaign, long-form content, portfolio: design IS the product) or **product** (app UI, admin, dashboard, tool: design SERVES the product). Identify before designing. Priority: (1) cue in the task itself ("landing page" vs "dashboard"); (2) the surface in focus (the page, file, or route being worked on); (3) `register` field in PRODUCT.md. First match wins. If PRODUCT.md lacks the `register` field (legacy), infer it once from its "Users" and "Product Purpose" sections, then cache the inferred value for the session. Suggest the user run `/impeccable teach` to add the field explicitly. Load the matching reference: [reference/brand.md](reference/brand.md) or [reference/product.md](reference/product.md). The shared design laws below apply to both. ## Shared design laws Apply to every design, both registers. Match implementation complexity to the aesthetic vision: maximalism needs elaborate code, minimalism needs precision. Interpret creatively. Vary across projects; never converge on the same choices. the model is capable of extraordinary work. Don't hold back. ### Color - Use OKLCH. Reduce chroma as lightness approaches 0 or 100; high chroma at extremes looks garish. - Never use `#000` or `#fff`. Tint every neutral toward the brand hue (chroma 0.005–0.01 is enough). - Pick a **color strategy** before picking colors. Four steps on the commitment axis: - **Restrained**: tinted neutrals + one accent ≤10%. Product default; brand minimalism. - **Committed**: one saturated color carries 30–60% of the surface. Brand default for identity-driven pages. - **Full palette**: 3–4 named roles, each used deliberately. Brand campaigns; product data viz. - **Drenched**: the surface IS the color. Brand heroes, campaign pages. - The "one accent ≤10%" rule is Restrained only. Committed / Full palette / Drenched exceed it on purpose. Don't collapse every design to Restrained by reflex. ### Theme Dark vs. light is never a default. Not dark "because tools look cool dark." Not light "to be safe." Before choosing, write one sentence of physical scene: who uses this, where, under what ambient light, in what mood. If the sentence doesn't force the answer, it's not concrete enough. Add detail until it does. "Observability dashboard" does not force an answer. "SRE glancing at incident severity on a 27-inch monitor at 2am in a dim room" does. Run the sentence, not the category. ### Typography - Cap body line length at 65–75ch. - Hierarchy through scale + weight contrast (≥1.25 ratio between steps). Avoid flat scales. ### Layout - Vary spacing for rhythm. Same padding everywhere is monotony. - Cards are the lazy answer. Use them only when they're truly the best affordance. Nested cards are always wrong. - Don't wrap everything in a container. Most things don't need one. ### Motion - Don't animate CSS layout properties. - Ease out with exponential curves (ease-out-quart / quint / expo). No bounce, no elastic. ### Absolute bans Match-and-refuse. If you're about to write any of these, rewrite the element with different structure. - **Side-stripe borders.** `border-left` or `border-right` greater than 1px as a colored accent on cards, list items, callouts, or alerts. Never intentional. Rewrite with full borders, background tints, leading numbers/icons, or nothing. - **Gradient text.** `background-clip: text` combined with a gradient background. Decorative, never meaningful. Use a single solid color. Emphasis via weight or size. - **Glassmorphism as default.** Blurs and glass cards used decoratively. Rare and purposeful, or nothing. - **The hero-metric template.** Big number, small label, supporting stats, gradient accent. SaaS cliché. - **Identical card grids.** Same-sized cards with icon + heading + text, repeated endlessly. - **Modal as first thought.** Modals are usually laziness. Exhaust inline / progressive alternatives first. ### Copy - Every word earns its place. No restated headings, no intros that repeat the title. - **No em dashes.** Use commas, colons, semicolons, periods, or parentheses. Also not `--`. ### The AI slop test If someone could look at this interface and say "AI made that" without doubt, it's failed. Cross-register failures are the absolute bans above. Register-specific failures live in each reference. **Category-reflex check.** Run at two altitudes; the second one catches what the first one misses. - **First-order:** if someone could guess the theme + palette from the category alone ("observability → dark blue", "healthcare → white + teal", "finance → navy + gold", "crypto → neon on black"), it's the first training-data reflex. Rework the scene sentence and color strategy until the answer isn't obvious from the domain. - **Second-order:** if someone could guess the aesthetic family from category-plus-anti-references ("AI workflow tool that's not SaaS-cream → editorial-typographic", "fintech that's not navy-and-gold → terminal-native dark mode"), it's the trap one tier deeper. The first reflex was avoided; the second wasn't. Rework until both answers are not obvious. The brand register's [reflex-reject aesthetic lanes](reference/brand.md) list catches the currently-saturated families. ## Commands | Command | Category | Description | Reference | |---|---|---|---| | `craft [feature]` | Build | Shape, then build a feature end-to-end | [reference/craft.md](reference/craft.md) | | `shape [feature]` | Build | Plan UX/UI before writing code | [reference/shape.md](reference/shape.md) | | `teach` | Build | Set up PRODUCT.md and DESIGN.md context | [reference/teach.md](reference/teach.md) | | `document` | Build | Generate DESIGN.md from existing project code | [reference/document.md](reference/document.md) | | `extract [target]` | Build | Pull reusable tokens and components into design system | [reference/extract.md](reference/extract.md) | | `critique [target]` | Evaluate | UX design review with heuristic scoring | [reference/critique.md](reference/critique.md) | | `audit [target]` | Evaluate | Technical quality checks (a11y, perf, responsive) | [reference/audit.md](reference/audit.md) | | `polish [target]` | Refine | Final quality pass before shipping | [reference/polish.md](reference/polish.md) | | `bolder [target]` | Refine | Amplify safe or bland designs | [reference/bolder.md](reference/bolder.md) | | `quieter [target]` | Refine | Tone down aggressive or overstimulating designs | [reference/quieter.md](reference/quieter.md) | | `distill [target]` | Refine | Strip to essence, remove complexity | [reference/distill.md](reference/distill.md) | | `harden [target]` | Refine | Production-ready: errors, i18n, edge cases | [reference/harden.md](reference/harden.md) | | `onboard [target]` | Refine | Design first-run flows, empty states, activation | [reference/onboard.md](reference/onboard.md) | | `animate [target]` | Enhance | Add purposeful animations and motion | [reference/animate.md](reference/animate.md) | | `colorize [target]` | Enhance | Add strategic color to monochromatic UIs | [reference/colorize.md](reference/colorize.md) | | `typeset [target]` | Enhance | Improve typography hierarchy and fonts | [reference/typeset.md](reference/typeset.md) | | `layout [target]` | Enhance | Fix spacing, rhythm, and visual hierarchy | [reference/layout.md](reference/layout.md) | | `delight [target]` | Enhance | Add personality and memorable touches | [reference/delight.md](reference/delight.md) | | `overdrive [target]` | Enhance | Push past conventional limits | [reference/overdrive.md](reference/overdrive.md) | | `clarify [target]` | Fix | Improve UX copy, labels, and error messages | [reference/clarify.md](reference/clarify.md) | | `adapt [target]` | Fix | Adapt for different devices and screen sizes | [reference/adapt.md](reference/adapt.md) | | `optimize [target]` | Fix | Diagnose and fix UI performance | [reference/optimize.md](reference/optimize.md) | | `live` | Iterate | Visual variant mode: pick elements in the browser, generate alternatives | [reference/live.md](reference/live.md) | Plus two management commands: `pin <command>` and `unpin <command>`, detailed below. ### Routing rules 1. **No argument**: render the table above as the user-facing command menu, grouped by category. Ask what they'd like to do. 2. **First word matches a command**: load its reference file and follow its instructions. Everything after the command name is the target. 3. **First word doesn't match**: general design invocation. Apply the setup steps, shared design laws, and the loaded register reference, using the full argument as context. Setup (context gathering, register) is already loaded by then; sub-commands don't re-invoke `/impeccable`. If the first word is `craft`, setup still runs first, but [reference/craft.md](reference/craft.md) owns the rest of the flow. If setup invokes `teach` as a blocker, finish teach, refresh context, then resume the original command and target. ## Pin / Unpin **Pin** creates a standalone shortcut so `/<command>` invokes `/impeccable <command>` directly. **Unpin** removes it. The script writes to every harness directory present in the project. ```bash node .cursor/skills/impeccable/scripts/pin.mjs <pin|unpin> <command> ``` Valid `<command>` is any command from the table above. Report the script's result concisely. Confirm the new shortcut on success, relay stderr verbatim on error..gemini/skills/impeccable/SKILL.mdskillShow content (13746 bytes)
--- name: impeccable description: Use when the user wants to design, redesign, shape, critique, audit, polish, clarify, distill, harden, optimize, adapt, animate, colorize, extract, or otherwise improve a frontend interface. Covers websites, landing pages, dashboards, product UI, app shells, components, forms, settings, onboarding, and empty states. Handles UX review, visual hierarchy, information architecture, cognitive load, accessibility, performance, responsive behavior, theming, anti-patterns, typography, fonts, spacing, layout, alignment, color, motion, micro-interactions, UX copy, error states, edge cases, i18n, and reusable design systems or tokens. Also use for bland designs that need to become bolder or more delightful, loud designs that should become quieter, live browser iteration on UI elements, or ambitious visual effects that should feel technically extraordinary. Not for backend-only or non-UI tasks. version: 3.0.7 --- Designs and iterates production-grade frontend interfaces. Real working code, committed design choices, exceptional craft. ## Setup (non-optional) Before any design work or file edits, pass these gates. Skipping them produces generic output that ignores the project. | Gate | Required check | If fail | |---|---|---| | Context | The PRODUCT.md / DESIGN.md loader result is known from `node .gemini/skills/impeccable/scripts/load-context.mjs`. | Run the loader before continuing. | | Product | PRODUCT.md exists and is not empty or placeholder (`[TODO]` markers, <200 chars). | Run `/impeccable teach`, refresh context, then resume. Never synthesize PRODUCT.md from the user's original prompt alone. | | Command | The matching command reference is loaded when a sub-command is used. | Load the reference before continuing. | | Craft | `/impeccable craft` has a user-confirmed shape brief for this task. `teach` / PRODUCT.md never counts as shape. | Run `/impeccable shape` and wait for explicit brief confirmation. | | Image | Required visual probes / mocks are generated or skipped with a reason. | Resolve the image-generation gate in `shape.md` or `craft.md` before code. | | Mutation | All active gates above pass. | Do not edit project files yet. | Codex-style agents must state this before editing files: ```text IMPECCABLE_PREFLIGHT: context=pass product=pass command_reference=pass shape=pass|not_required image_gate=pass|skipped:<reason> mutation=open ``` For `/impeccable craft`, `shape=pass` is only valid after a separate user response approving the shape design brief, or when the user provided an already-confirmed brief in the request. Do not mark `shape=pass` after writing PRODUCT.md, summarizing assumptions, or drafting an unconfirmed brief yourself. Other harnesses should follow the same checklist when they can expose this state. ### 1. Context gathering Two files, case-insensitive. The loader looks at the project root by default and falls back to `.agents/context/` and `docs/` if the root is clean. Override with `IMPECCABLE_CONTEXT_DIR=path/to/dir` (absolute or relative to cwd). - **PRODUCT.md**: required. Users, brand, tone, anti-references, strategic principles. - **DESIGN.md**: optional, strongly recommended. Colors, typography, elevation, components. Load both in one call: ```bash node .gemini/skills/impeccable/scripts/load-context.mjs ``` Consume the full JSON output. Never pipe through `head`, `tail`, `grep`, or `jq`. The output's `contextDir` field tells you where the files were resolved from. If the output is already in this session's conversation history, don't re-run. Exceptions requiring a fresh load: you just ran `/impeccable teach` or `/impeccable document` (they rewrite the files), or the user manually edited one. `/impeccable live` already warms context via `live.mjs`. If you've run `live.mjs`, don't also run `load-context.mjs` this session. If PRODUCT.md is missing, empty, or placeholder (`[TODO]` markers, <200 chars): run `/impeccable teach`, then resume the user's original task with the fresh context. If the original task was `/impeccable craft`, resume into `/impeccable shape` before any implementation work. If DESIGN.md is missing: nudge once per session (*"Run `/impeccable document` for more on-brand output"*), then proceed. ### 2. Register Every design task is **brand** (marketing, landing, campaign, long-form content, portfolio: design IS the product) or **product** (app UI, admin, dashboard, tool: design SERVES the product). Identify before designing. Priority: (1) cue in the task itself ("landing page" vs "dashboard"); (2) the surface in focus (the page, file, or route being worked on); (3) `register` field in PRODUCT.md. First match wins. If PRODUCT.md lacks the `register` field (legacy), infer it once from its "Users" and "Product Purpose" sections, then cache the inferred value for the session. Suggest the user run `/impeccable teach` to add the field explicitly. Load the matching reference: [reference/brand.md](reference/brand.md) or [reference/product.md](reference/product.md). The shared design laws below apply to both. ## Shared design laws Apply to every design, both registers. Match implementation complexity to the aesthetic vision: maximalism needs elaborate code, minimalism needs precision. Interpret creatively. Vary across projects; never converge on the same choices. Gemini is capable of extraordinary work. Don't hold back. ### Color - Use OKLCH. Reduce chroma as lightness approaches 0 or 100; high chroma at extremes looks garish. - Never use `#000` or `#fff`. Tint every neutral toward the brand hue (chroma 0.005–0.01 is enough). - Pick a **color strategy** before picking colors. Four steps on the commitment axis: - **Restrained**: tinted neutrals + one accent ≤10%. Product default; brand minimalism. - **Committed**: one saturated color carries 30–60% of the surface. Brand default for identity-driven pages. - **Full palette**: 3–4 named roles, each used deliberately. Brand campaigns; product data viz. - **Drenched**: the surface IS the color. Brand heroes, campaign pages. - The "one accent ≤10%" rule is Restrained only. Committed / Full palette / Drenched exceed it on purpose. Don't collapse every design to Restrained by reflex. ### Theme Dark vs. light is never a default. Not dark "because tools look cool dark." Not light "to be safe." Before choosing, write one sentence of physical scene: who uses this, where, under what ambient light, in what mood. If the sentence doesn't force the answer, it's not concrete enough. Add detail until it does. "Observability dashboard" does not force an answer. "SRE glancing at incident severity on a 27-inch monitor at 2am in a dim room" does. Run the sentence, not the category. ### Typography - Cap body line length at 65–75ch. - Hierarchy through scale + weight contrast (≥1.25 ratio between steps). Avoid flat scales. ### Layout - Vary spacing for rhythm. Same padding everywhere is monotony. - Cards are the lazy answer. Use them only when they're truly the best affordance. Nested cards are always wrong. - Don't wrap everything in a container. Most things don't need one. ### Motion - Don't animate CSS layout properties. - Ease out with exponential curves (ease-out-quart / quint / expo). No bounce, no elastic. ### Absolute bans Match-and-refuse. If you're about to write any of these, rewrite the element with different structure. - **Side-stripe borders.** `border-left` or `border-right` greater than 1px as a colored accent on cards, list items, callouts, or alerts. Never intentional. Rewrite with full borders, background tints, leading numbers/icons, or nothing. - **Gradient text.** `background-clip: text` combined with a gradient background. Decorative, never meaningful. Use a single solid color. Emphasis via weight or size. - **Glassmorphism as default.** Blurs and glass cards used decoratively. Rare and purposeful, or nothing. - **The hero-metric template.** Big number, small label, supporting stats, gradient accent. SaaS cliché. - **Identical card grids.** Same-sized cards with icon + heading + text, repeated endlessly. - **Modal as first thought.** Modals are usually laziness. Exhaust inline / progressive alternatives first. ### Copy - Every word earns its place. No restated headings, no intros that repeat the title. - **No em dashes.** Use commas, colons, semicolons, periods, or parentheses. Also not `--`. ### The AI slop test If someone could look at this interface and say "AI made that" without doubt, it's failed. Cross-register failures are the absolute bans above. Register-specific failures live in each reference. **Category-reflex check.** Run at two altitudes; the second one catches what the first one misses. - **First-order:** if someone could guess the theme + palette from the category alone ("observability → dark blue", "healthcare → white + teal", "finance → navy + gold", "crypto → neon on black"), it's the first training-data reflex. Rework the scene sentence and color strategy until the answer isn't obvious from the domain. - **Second-order:** if someone could guess the aesthetic family from category-plus-anti-references ("AI workflow tool that's not SaaS-cream → editorial-typographic", "fintech that's not navy-and-gold → terminal-native dark mode"), it's the trap one tier deeper. The first reflex was avoided; the second wasn't. Rework until both answers are not obvious. The brand register's [reflex-reject aesthetic lanes](reference/brand.md) list catches the currently-saturated families. ## Commands | Command | Category | Description | Reference | |---|---|---|---| | `craft [feature]` | Build | Shape, then build a feature end-to-end | [reference/craft.md](reference/craft.md) | | `shape [feature]` | Build | Plan UX/UI before writing code | [reference/shape.md](reference/shape.md) | | `teach` | Build | Set up PRODUCT.md and DESIGN.md context | [reference/teach.md](reference/teach.md) | | `document` | Build | Generate DESIGN.md from existing project code | [reference/document.md](reference/document.md) | | `extract [target]` | Build | Pull reusable tokens and components into design system | [reference/extract.md](reference/extract.md) | | `critique [target]` | Evaluate | UX design review with heuristic scoring | [reference/critique.md](reference/critique.md) | | `audit [target]` | Evaluate | Technical quality checks (a11y, perf, responsive) | [reference/audit.md](reference/audit.md) | | `polish [target]` | Refine | Final quality pass before shipping | [reference/polish.md](reference/polish.md) | | `bolder [target]` | Refine | Amplify safe or bland designs | [reference/bolder.md](reference/bolder.md) | | `quieter [target]` | Refine | Tone down aggressive or overstimulating designs | [reference/quieter.md](reference/quieter.md) | | `distill [target]` | Refine | Strip to essence, remove complexity | [reference/distill.md](reference/distill.md) | | `harden [target]` | Refine | Production-ready: errors, i18n, edge cases | [reference/harden.md](reference/harden.md) | | `onboard [target]` | Refine | Design first-run flows, empty states, activation | [reference/onboard.md](reference/onboard.md) | | `animate [target]` | Enhance | Add purposeful animations and motion | [reference/animate.md](reference/animate.md) | | `colorize [target]` | Enhance | Add strategic color to monochromatic UIs | [reference/colorize.md](reference/colorize.md) | | `typeset [target]` | Enhance | Improve typography hierarchy and fonts | [reference/typeset.md](reference/typeset.md) | | `layout [target]` | Enhance | Fix spacing, rhythm, and visual hierarchy | [reference/layout.md](reference/layout.md) | | `delight [target]` | Enhance | Add personality and memorable touches | [reference/delight.md](reference/delight.md) | | `overdrive [target]` | Enhance | Push past conventional limits | [reference/overdrive.md](reference/overdrive.md) | | `clarify [target]` | Fix | Improve UX copy, labels, and error messages | [reference/clarify.md](reference/clarify.md) | | `adapt [target]` | Fix | Adapt for different devices and screen sizes | [reference/adapt.md](reference/adapt.md) | | `optimize [target]` | Fix | Diagnose and fix UI performance | [reference/optimize.md](reference/optimize.md) | | `live` | Iterate | Visual variant mode: pick elements in the browser, generate alternatives | [reference/live.md](reference/live.md) | Plus two management commands: `pin <command>` and `unpin <command>`, detailed below. ### Routing rules 1. **No argument**: render the table above as the user-facing command menu, grouped by category. Ask what they'd like to do. 2. **First word matches a command**: load its reference file and follow its instructions. Everything after the command name is the target. 3. **First word doesn't match**: general design invocation. Apply the setup steps, shared design laws, and the loaded register reference, using the full argument as context. Setup (context gathering, register) is already loaded by then; sub-commands don't re-invoke `/impeccable`. If the first word is `craft`, setup still runs first, but [reference/craft.md](reference/craft.md) owns the rest of the flow. If setup invokes `teach` as a blocker, finish teach, refresh context, then resume the original command and target. ## Pin / Unpin **Pin** creates a standalone shortcut so `/<command>` invokes `/impeccable <command>` directly. **Unpin** removes it. The script writes to every harness directory present in the project. ```bash node .gemini/skills/impeccable/scripts/pin.mjs <pin|unpin> <command> ``` Valid `<command>` is any command from the table above. Report the script's result concisely. Confirm the new shortcut on success, relay stderr verbatim on error..github/skills/impeccable/SKILL.mdskillShow content (14082 bytes)
--- name: impeccable description: Use when the user wants to design, redesign, shape, critique, audit, polish, clarify, distill, harden, optimize, adapt, animate, colorize, extract, or otherwise improve a frontend interface. Covers websites, landing pages, dashboards, product UI, app shells, components, forms, settings, onboarding, and empty states. Handles UX review, visual hierarchy, information architecture, cognitive load, accessibility, performance, responsive behavior, theming, anti-patterns, typography, fonts, spacing, layout, alignment, color, motion, micro-interactions, UX copy, error states, edge cases, i18n, and reusable design systems or tokens. Also use for bland designs that need to become bolder or more delightful, loud designs that should become quieter, live browser iteration on UI elements, or ambitious visual effects that should feel technically extraordinary. Not for backend-only or non-UI tasks. version: 3.0.7 user-invocable: true argument-hint: "[craft|shape · audit|critique · animate|bolder|colorize|delight|layout|overdrive|quieter|typeset · adapt|clarify|distill · harden|onboard|optimize|polish · teach|document|extract|live] [target]" license: Apache 2.0. Based on Anthropic's frontend-design skill. See NOTICE.md for attribution. --- Designs and iterates production-grade frontend interfaces. Real working code, committed design choices, exceptional craft. ## Setup (non-optional) Before any design work or file edits, pass these gates. Skipping them produces generic output that ignores the project. | Gate | Required check | If fail | |---|---|---| | Context | The PRODUCT.md / DESIGN.md loader result is known from `node .github/skills/impeccable/scripts/load-context.mjs`. | Run the loader before continuing. | | Product | PRODUCT.md exists and is not empty or placeholder (`[TODO]` markers, <200 chars). | Run `/impeccable teach`, refresh context, then resume. Never synthesize PRODUCT.md from the user's original prompt alone. | | Command | The matching command reference is loaded when a sub-command is used. | Load the reference before continuing. | | Craft | `/impeccable craft` has a user-confirmed shape brief for this task. `teach` / PRODUCT.md never counts as shape. | Run `/impeccable shape` and wait for explicit brief confirmation. | | Image | Required visual probes / mocks are generated or skipped with a reason. | Resolve the image-generation gate in `shape.md` or `craft.md` before code. | | Mutation | All active gates above pass. | Do not edit project files yet. | Codex-style agents must state this before editing files: ```text IMPECCABLE_PREFLIGHT: context=pass product=pass command_reference=pass shape=pass|not_required image_gate=pass|skipped:<reason> mutation=open ``` For `/impeccable craft`, `shape=pass` is only valid after a separate user response approving the shape design brief, or when the user provided an already-confirmed brief in the request. Do not mark `shape=pass` after writing PRODUCT.md, summarizing assumptions, or drafting an unconfirmed brief yourself. Other harnesses should follow the same checklist when they can expose this state. ### 1. Context gathering Two files, case-insensitive. The loader looks at the project root by default and falls back to `.agents/context/` and `docs/` if the root is clean. Override with `IMPECCABLE_CONTEXT_DIR=path/to/dir` (absolute or relative to cwd). - **PRODUCT.md**: required. Users, brand, tone, anti-references, strategic principles. - **DESIGN.md**: optional, strongly recommended. Colors, typography, elevation, components. Load both in one call: ```bash node .github/skills/impeccable/scripts/load-context.mjs ``` Consume the full JSON output. Never pipe through `head`, `tail`, `grep`, or `jq`. The output's `contextDir` field tells you where the files were resolved from. If the output is already in this session's conversation history, don't re-run. Exceptions requiring a fresh load: you just ran `/impeccable teach` or `/impeccable document` (they rewrite the files), or the user manually edited one. `/impeccable live` already warms context via `live.mjs`. If you've run `live.mjs`, don't also run `load-context.mjs` this session. If PRODUCT.md is missing, empty, or placeholder (`[TODO]` markers, <200 chars): run `/impeccable teach`, then resume the user's original task with the fresh context. If the original task was `/impeccable craft`, resume into `/impeccable shape` before any implementation work. If DESIGN.md is missing: nudge once per session (*"Run `/impeccable document` for more on-brand output"*), then proceed. ### 2. Register Every design task is **brand** (marketing, landing, campaign, long-form content, portfolio: design IS the product) or **product** (app UI, admin, dashboard, tool: design SERVES the product). Identify before designing. Priority: (1) cue in the task itself ("landing page" vs "dashboard"); (2) the surface in focus (the page, file, or route being worked on); (3) `register` field in PRODUCT.md. First match wins. If PRODUCT.md lacks the `register` field (legacy), infer it once from its "Users" and "Product Purpose" sections, then cache the inferred value for the session. Suggest the user run `/impeccable teach` to add the field explicitly. Load the matching reference: [reference/brand.md](reference/brand.md) or [reference/product.md](reference/product.md). The shared design laws below apply to both. ## Shared design laws Apply to every design, both registers. Match implementation complexity to the aesthetic vision: maximalism needs elaborate code, minimalism needs precision. Interpret creatively. Vary across projects; never converge on the same choices. the model is capable of extraordinary work. Don't hold back. ### Color - Use OKLCH. Reduce chroma as lightness approaches 0 or 100; high chroma at extremes looks garish. - Never use `#000` or `#fff`. Tint every neutral toward the brand hue (chroma 0.005–0.01 is enough). - Pick a **color strategy** before picking colors. Four steps on the commitment axis: - **Restrained**: tinted neutrals + one accent ≤10%. Product default; brand minimalism. - **Committed**: one saturated color carries 30–60% of the surface. Brand default for identity-driven pages. - **Full palette**: 3–4 named roles, each used deliberately. Brand campaigns; product data viz. - **Drenched**: the surface IS the color. Brand heroes, campaign pages. - The "one accent ≤10%" rule is Restrained only. Committed / Full palette / Drenched exceed it on purpose. Don't collapse every design to Restrained by reflex. ### Theme Dark vs. light is never a default. Not dark "because tools look cool dark." Not light "to be safe." Before choosing, write one sentence of physical scene: who uses this, where, under what ambient light, in what mood. If the sentence doesn't force the answer, it's not concrete enough. Add detail until it does. "Observability dashboard" does not force an answer. "SRE glancing at incident severity on a 27-inch monitor at 2am in a dim room" does. Run the sentence, not the category. ### Typography - Cap body line length at 65–75ch. - Hierarchy through scale + weight contrast (≥1.25 ratio between steps). Avoid flat scales. ### Layout - Vary spacing for rhythm. Same padding everywhere is monotony. - Cards are the lazy answer. Use them only when they're truly the best affordance. Nested cards are always wrong. - Don't wrap everything in a container. Most things don't need one. ### Motion - Don't animate CSS layout properties. - Ease out with exponential curves (ease-out-quart / quint / expo). No bounce, no elastic. ### Absolute bans Match-and-refuse. If you're about to write any of these, rewrite the element with different structure. - **Side-stripe borders.** `border-left` or `border-right` greater than 1px as a colored accent on cards, list items, callouts, or alerts. Never intentional. Rewrite with full borders, background tints, leading numbers/icons, or nothing. - **Gradient text.** `background-clip: text` combined with a gradient background. Decorative, never meaningful. Use a single solid color. Emphasis via weight or size. - **Glassmorphism as default.** Blurs and glass cards used decoratively. Rare and purposeful, or nothing. - **The hero-metric template.** Big number, small label, supporting stats, gradient accent. SaaS cliché. - **Identical card grids.** Same-sized cards with icon + heading + text, repeated endlessly. - **Modal as first thought.** Modals are usually laziness. Exhaust inline / progressive alternatives first. ### Copy - Every word earns its place. No restated headings, no intros that repeat the title. - **No em dashes.** Use commas, colons, semicolons, periods, or parentheses. Also not `--`. ### The AI slop test If someone could look at this interface and say "AI made that" without doubt, it's failed. Cross-register failures are the absolute bans above. Register-specific failures live in each reference. **Category-reflex check.** Run at two altitudes; the second one catches what the first one misses. - **First-order:** if someone could guess the theme + palette from the category alone ("observability → dark blue", "healthcare → white + teal", "finance → navy + gold", "crypto → neon on black"), it's the first training-data reflex. Rework the scene sentence and color strategy until the answer isn't obvious from the domain. - **Second-order:** if someone could guess the aesthetic family from category-plus-anti-references ("AI workflow tool that's not SaaS-cream → editorial-typographic", "fintech that's not navy-and-gold → terminal-native dark mode"), it's the trap one tier deeper. The first reflex was avoided; the second wasn't. Rework until both answers are not obvious. The brand register's [reflex-reject aesthetic lanes](reference/brand.md) list catches the currently-saturated families. ## Commands | Command | Category | Description | Reference | |---|---|---|---| | `craft [feature]` | Build | Shape, then build a feature end-to-end | [reference/craft.md](reference/craft.md) | | `shape [feature]` | Build | Plan UX/UI before writing code | [reference/shape.md](reference/shape.md) | | `teach` | Build | Set up PRODUCT.md and DESIGN.md context | [reference/teach.md](reference/teach.md) | | `document` | Build | Generate DESIGN.md from existing project code | [reference/document.md](reference/document.md) | | `extract [target]` | Build | Pull reusable tokens and components into design system | [reference/extract.md](reference/extract.md) | | `critique [target]` | Evaluate | UX design review with heuristic scoring | [reference/critique.md](reference/critique.md) | | `audit [target]` | Evaluate | Technical quality checks (a11y, perf, responsive) | [reference/audit.md](reference/audit.md) | | `polish [target]` | Refine | Final quality pass before shipping | [reference/polish.md](reference/polish.md) | | `bolder [target]` | Refine | Amplify safe or bland designs | [reference/bolder.md](reference/bolder.md) | | `quieter [target]` | Refine | Tone down aggressive or overstimulating designs | [reference/quieter.md](reference/quieter.md) | | `distill [target]` | Refine | Strip to essence, remove complexity | [reference/distill.md](reference/distill.md) | | `harden [target]` | Refine | Production-ready: errors, i18n, edge cases | [reference/harden.md](reference/harden.md) | | `onboard [target]` | Refine | Design first-run flows, empty states, activation | [reference/onboard.md](reference/onboard.md) | | `animate [target]` | Enhance | Add purposeful animations and motion | [reference/animate.md](reference/animate.md) | | `colorize [target]` | Enhance | Add strategic color to monochromatic UIs | [reference/colorize.md](reference/colorize.md) | | `typeset [target]` | Enhance | Improve typography hierarchy and fonts | [reference/typeset.md](reference/typeset.md) | | `layout [target]` | Enhance | Fix spacing, rhythm, and visual hierarchy | [reference/layout.md](reference/layout.md) | | `delight [target]` | Enhance | Add personality and memorable touches | [reference/delight.md](reference/delight.md) | | `overdrive [target]` | Enhance | Push past conventional limits | [reference/overdrive.md](reference/overdrive.md) | | `clarify [target]` | Fix | Improve UX copy, labels, and error messages | [reference/clarify.md](reference/clarify.md) | | `adapt [target]` | Fix | Adapt for different devices and screen sizes | [reference/adapt.md](reference/adapt.md) | | `optimize [target]` | Fix | Diagnose and fix UI performance | [reference/optimize.md](reference/optimize.md) | | `live` | Iterate | Visual variant mode: pick elements in the browser, generate alternatives | [reference/live.md](reference/live.md) | Plus two management commands: `pin <command>` and `unpin <command>`, detailed below. ### Routing rules 1. **No argument**: render the table above as the user-facing command menu, grouped by category. Ask what they'd like to do. 2. **First word matches a command**: load its reference file and follow its instructions. Everything after the command name is the target. 3. **First word doesn't match**: general design invocation. Apply the setup steps, shared design laws, and the loaded register reference, using the full argument as context. Setup (context gathering, register) is already loaded by then; sub-commands don't re-invoke `/impeccable`. If the first word is `craft`, setup still runs first, but [reference/craft.md](reference/craft.md) owns the rest of the flow. If setup invokes `teach` as a blocker, finish teach, refresh context, then resume the original command and target. ## Pin / Unpin **Pin** creates a standalone shortcut so `/<command>` invokes `/impeccable <command>` directly. **Unpin** removes it. The script writes to every harness directory present in the project. ```bash node .github/skills/impeccable/scripts/pin.mjs <pin|unpin> <command> ``` Valid `<command>` is any command from the table above. Report the script's result concisely. Confirm the new shortcut on success, relay stderr verbatim on error..kiro/skills/impeccable/SKILL.mdskillShow content (13836 bytes)
--- name: impeccable description: Use when the user wants to design, redesign, shape, critique, audit, polish, clarify, distill, harden, optimize, adapt, animate, colorize, extract, or otherwise improve a frontend interface. Covers websites, landing pages, dashboards, product UI, app shells, components, forms, settings, onboarding, and empty states. Handles UX review, visual hierarchy, information architecture, cognitive load, accessibility, performance, responsive behavior, theming, anti-patterns, typography, fonts, spacing, layout, alignment, color, motion, micro-interactions, UX copy, error states, edge cases, i18n, and reusable design systems or tokens. Also use for bland designs that need to become bolder or more delightful, loud designs that should become quieter, live browser iteration on UI elements, or ambitious visual effects that should feel technically extraordinary. Not for backend-only or non-UI tasks. version: 3.0.7 license: Apache 2.0. Based on Anthropic's frontend-design skill. See NOTICE.md for attribution. --- Designs and iterates production-grade frontend interfaces. Real working code, committed design choices, exceptional craft. ## Setup (non-optional) Before any design work or file edits, pass these gates. Skipping them produces generic output that ignores the project. | Gate | Required check | If fail | |---|---|---| | Context | The PRODUCT.md / DESIGN.md loader result is known from `node .kiro/skills/impeccable/scripts/load-context.mjs`. | Run the loader before continuing. | | Product | PRODUCT.md exists and is not empty or placeholder (`[TODO]` markers, <200 chars). | Run `/impeccable teach`, refresh context, then resume. Never synthesize PRODUCT.md from the user's original prompt alone. | | Command | The matching command reference is loaded when a sub-command is used. | Load the reference before continuing. | | Craft | `/impeccable craft` has a user-confirmed shape brief for this task. `teach` / PRODUCT.md never counts as shape. | Run `/impeccable shape` and wait for explicit brief confirmation. | | Image | Required visual probes / mocks are generated or skipped with a reason. | Resolve the image-generation gate in `shape.md` or `craft.md` before code. | | Mutation | All active gates above pass. | Do not edit project files yet. | Codex-style agents must state this before editing files: ```text IMPECCABLE_PREFLIGHT: context=pass product=pass command_reference=pass shape=pass|not_required image_gate=pass|skipped:<reason> mutation=open ``` For `/impeccable craft`, `shape=pass` is only valid after a separate user response approving the shape design brief, or when the user provided an already-confirmed brief in the request. Do not mark `shape=pass` after writing PRODUCT.md, summarizing assumptions, or drafting an unconfirmed brief yourself. Other harnesses should follow the same checklist when they can expose this state. ### 1. Context gathering Two files, case-insensitive. The loader looks at the project root by default and falls back to `.agents/context/` and `docs/` if the root is clean. Override with `IMPECCABLE_CONTEXT_DIR=path/to/dir` (absolute or relative to cwd). - **PRODUCT.md**: required. Users, brand, tone, anti-references, strategic principles. - **DESIGN.md**: optional, strongly recommended. Colors, typography, elevation, components. Load both in one call: ```bash node .kiro/skills/impeccable/scripts/load-context.mjs ``` Consume the full JSON output. Never pipe through `head`, `tail`, `grep`, or `jq`. The output's `contextDir` field tells you where the files were resolved from. If the output is already in this session's conversation history, don't re-run. Exceptions requiring a fresh load: you just ran `/impeccable teach` or `/impeccable document` (they rewrite the files), or the user manually edited one. `/impeccable live` already warms context via `live.mjs`. If you've run `live.mjs`, don't also run `load-context.mjs` this session. If PRODUCT.md is missing, empty, or placeholder (`[TODO]` markers, <200 chars): run `/impeccable teach`, then resume the user's original task with the fresh context. If the original task was `/impeccable craft`, resume into `/impeccable shape` before any implementation work. If DESIGN.md is missing: nudge once per session (*"Run `/impeccable document` for more on-brand output"*), then proceed. ### 2. Register Every design task is **brand** (marketing, landing, campaign, long-form content, portfolio: design IS the product) or **product** (app UI, admin, dashboard, tool: design SERVES the product). Identify before designing. Priority: (1) cue in the task itself ("landing page" vs "dashboard"); (2) the surface in focus (the page, file, or route being worked on); (3) `register` field in PRODUCT.md. First match wins. If PRODUCT.md lacks the `register` field (legacy), infer it once from its "Users" and "Product Purpose" sections, then cache the inferred value for the session. Suggest the user run `/impeccable teach` to add the field explicitly. Load the matching reference: [reference/brand.md](reference/brand.md) or [reference/product.md](reference/product.md). The shared design laws below apply to both. ## Shared design laws Apply to every design, both registers. Match implementation complexity to the aesthetic vision: maximalism needs elaborate code, minimalism needs precision. Interpret creatively. Vary across projects; never converge on the same choices. Claude is capable of extraordinary work. Don't hold back. ### Color - Use OKLCH. Reduce chroma as lightness approaches 0 or 100; high chroma at extremes looks garish. - Never use `#000` or `#fff`. Tint every neutral toward the brand hue (chroma 0.005–0.01 is enough). - Pick a **color strategy** before picking colors. Four steps on the commitment axis: - **Restrained**: tinted neutrals + one accent ≤10%. Product default; brand minimalism. - **Committed**: one saturated color carries 30–60% of the surface. Brand default for identity-driven pages. - **Full palette**: 3–4 named roles, each used deliberately. Brand campaigns; product data viz. - **Drenched**: the surface IS the color. Brand heroes, campaign pages. - The "one accent ≤10%" rule is Restrained only. Committed / Full palette / Drenched exceed it on purpose. Don't collapse every design to Restrained by reflex. ### Theme Dark vs. light is never a default. Not dark "because tools look cool dark." Not light "to be safe." Before choosing, write one sentence of physical scene: who uses this, where, under what ambient light, in what mood. If the sentence doesn't force the answer, it's not concrete enough. Add detail until it does. "Observability dashboard" does not force an answer. "SRE glancing at incident severity on a 27-inch monitor at 2am in a dim room" does. Run the sentence, not the category. ### Typography - Cap body line length at 65–75ch. - Hierarchy through scale + weight contrast (≥1.25 ratio between steps). Avoid flat scales. ### Layout - Vary spacing for rhythm. Same padding everywhere is monotony. - Cards are the lazy answer. Use them only when they're truly the best affordance. Nested cards are always wrong. - Don't wrap everything in a container. Most things don't need one. ### Motion - Don't animate CSS layout properties. - Ease out with exponential curves (ease-out-quart / quint / expo). No bounce, no elastic. ### Absolute bans Match-and-refuse. If you're about to write any of these, rewrite the element with different structure. - **Side-stripe borders.** `border-left` or `border-right` greater than 1px as a colored accent on cards, list items, callouts, or alerts. Never intentional. Rewrite with full borders, background tints, leading numbers/icons, or nothing. - **Gradient text.** `background-clip: text` combined with a gradient background. Decorative, never meaningful. Use a single solid color. Emphasis via weight or size. - **Glassmorphism as default.** Blurs and glass cards used decoratively. Rare and purposeful, or nothing. - **The hero-metric template.** Big number, small label, supporting stats, gradient accent. SaaS cliché. - **Identical card grids.** Same-sized cards with icon + heading + text, repeated endlessly. - **Modal as first thought.** Modals are usually laziness. Exhaust inline / progressive alternatives first. ### Copy - Every word earns its place. No restated headings, no intros that repeat the title. - **No em dashes.** Use commas, colons, semicolons, periods, or parentheses. Also not `--`. ### The AI slop test If someone could look at this interface and say "AI made that" without doubt, it's failed. Cross-register failures are the absolute bans above. Register-specific failures live in each reference. **Category-reflex check.** Run at two altitudes; the second one catches what the first one misses. - **First-order:** if someone could guess the theme + palette from the category alone ("observability → dark blue", "healthcare → white + teal", "finance → navy + gold", "crypto → neon on black"), it's the first training-data reflex. Rework the scene sentence and color strategy until the answer isn't obvious from the domain. - **Second-order:** if someone could guess the aesthetic family from category-plus-anti-references ("AI workflow tool that's not SaaS-cream → editorial-typographic", "fintech that's not navy-and-gold → terminal-native dark mode"), it's the trap one tier deeper. The first reflex was avoided; the second wasn't. Rework until both answers are not obvious. The brand register's [reflex-reject aesthetic lanes](reference/brand.md) list catches the currently-saturated families. ## Commands | Command | Category | Description | Reference | |---|---|---|---| | `craft [feature]` | Build | Shape, then build a feature end-to-end | [reference/craft.md](reference/craft.md) | | `shape [feature]` | Build | Plan UX/UI before writing code | [reference/shape.md](reference/shape.md) | | `teach` | Build | Set up PRODUCT.md and DESIGN.md context | [reference/teach.md](reference/teach.md) | | `document` | Build | Generate DESIGN.md from existing project code | [reference/document.md](reference/document.md) | | `extract [target]` | Build | Pull reusable tokens and components into design system | [reference/extract.md](reference/extract.md) | | `critique [target]` | Evaluate | UX design review with heuristic scoring | [reference/critique.md](reference/critique.md) | | `audit [target]` | Evaluate | Technical quality checks (a11y, perf, responsive) | [reference/audit.md](reference/audit.md) | | `polish [target]` | Refine | Final quality pass before shipping | [reference/polish.md](reference/polish.md) | | `bolder [target]` | Refine | Amplify safe or bland designs | [reference/bolder.md](reference/bolder.md) | | `quieter [target]` | Refine | Tone down aggressive or overstimulating designs | [reference/quieter.md](reference/quieter.md) | | `distill [target]` | Refine | Strip to essence, remove complexity | [reference/distill.md](reference/distill.md) | | `harden [target]` | Refine | Production-ready: errors, i18n, edge cases | [reference/harden.md](reference/harden.md) | | `onboard [target]` | Refine | Design first-run flows, empty states, activation | [reference/onboard.md](reference/onboard.md) | | `animate [target]` | Enhance | Add purposeful animations and motion | [reference/animate.md](reference/animate.md) | | `colorize [target]` | Enhance | Add strategic color to monochromatic UIs | [reference/colorize.md](reference/colorize.md) | | `typeset [target]` | Enhance | Improve typography hierarchy and fonts | [reference/typeset.md](reference/typeset.md) | | `layout [target]` | Enhance | Fix spacing, rhythm, and visual hierarchy | [reference/layout.md](reference/layout.md) | | `delight [target]` | Enhance | Add personality and memorable touches | [reference/delight.md](reference/delight.md) | | `overdrive [target]` | Enhance | Push past conventional limits | [reference/overdrive.md](reference/overdrive.md) | | `clarify [target]` | Fix | Improve UX copy, labels, and error messages | [reference/clarify.md](reference/clarify.md) | | `adapt [target]` | Fix | Adapt for different devices and screen sizes | [reference/adapt.md](reference/adapt.md) | | `optimize [target]` | Fix | Diagnose and fix UI performance | [reference/optimize.md](reference/optimize.md) | | `live` | Iterate | Visual variant mode: pick elements in the browser, generate alternatives | [reference/live.md](reference/live.md) | Plus two management commands: `pin <command>` and `unpin <command>`, detailed below. ### Routing rules 1. **No argument**: render the table above as the user-facing command menu, grouped by category. Ask what they'd like to do. 2. **First word matches a command**: load its reference file and follow its instructions. Everything after the command name is the target. 3. **First word doesn't match**: general design invocation. Apply the setup steps, shared design laws, and the loaded register reference, using the full argument as context. Setup (context gathering, register) is already loaded by then; sub-commands don't re-invoke `/impeccable`. If the first word is `craft`, setup still runs first, but [reference/craft.md](reference/craft.md) owns the rest of the flow. If setup invokes `teach` as a blocker, finish teach, refresh context, then resume the original command and target. ## Pin / Unpin **Pin** creates a standalone shortcut so `/<command>` invokes `/impeccable <command>` directly. **Unpin** removes it. The script writes to every harness directory present in the project. ```bash node .kiro/skills/impeccable/scripts/pin.mjs <pin|unpin> <command> ``` Valid `<command>` is any command from the table above. Report the script's result concisely. Confirm the new shortcut on success, relay stderr verbatim on error..claude-plugin/marketplace.jsonmarketplaceShow content (886 bytes)
{ "$schema": "https://anthropic.com/claude-code/marketplace.schema.json", "name": "impeccable", "metadata": { "description": "Design fluency for AI harnesses. 1 skill, 23 commands, and curated anti-patterns for impeccable frontend design." }, "owner": { "name": "Paul Bakaus", "email": "paul@paulbakaus.com" }, "plugins": [ { "name": "impeccable", "description": "Design fluency for frontend development. 1 skill with 23 commands (/impeccable polish, /impeccable audit, /impeccable critique, etc.) and curated anti-pattern detection.", "version": "3.0.7", "author": { "name": "Paul Bakaus", "email": "paul@paulbakaus.com" }, "source": "./plugin", "category": "design", "homepage": "https://impeccable.style", "tags": ["design", "frontend", "ui", "ux", "skills", "commands"] } ] }
README
Impeccable
The vocabulary you didn't know you needed. 1 skill, 23 commands, and curated anti-patterns for impeccable frontend design.
Quick start: Visit impeccable.style to download ready-to-use bundles.
Why Impeccable?
Anthropic's frontend-design was the first widely-used design skill for Claude. Impeccable started from there.
Every model trained on the same SaaS templates. Skip the guidance and you get the same handful of tells on every project: Inter for everything, purple-to-blue gradients, cards nested in cards, gray text on colored backgrounds, the rounded-square icon tile above every heading.
Impeccable adds:
- 7 domain reference files (view source). Typography, color, motion, spatial, interaction, responsive, UX writing. Load on every command, alongside a brand-vs-product register that adjusts the defaults.
- 23 commands. A shared design vocabulary with your AI:
polish,audit,critique,distill,animate,bolder,quieter, and more. - 27 deterministic anti-pattern rules plus a 12-rule LLM critique pass. CLI and browser extension run the deterministic ones with no LLM and no API key. Each is tied to specific design guidance the skill teaches against.
What's Included
The Skill: impeccable
A comprehensive design skill with 7 domain-specific references (view skill):
| Reference | Covers |
|---|---|
| typography | Type systems, font pairing, modular scales, OpenType |
| color-and-contrast | OKLCH, tinted neutrals, dark mode, accessibility |
| spatial-design | Spacing systems, grids, visual hierarchy |
| motion-design | Easing curves, staggering, reduced motion |
| interaction-design | Forms, focus states, loading patterns |
| responsive-design | Mobile-first, fluid design, container queries |
| ux-writing | Button labels, error messages, empty states |
23 Commands
All commands are accessed through /impeccable:
| Command | What it does |
|---|---|
/impeccable craft | Full shape-then-build flow with visual iteration |
/impeccable teach | One-time setup: gather design context, write root PRODUCT.md and DESIGN.md |
/impeccable document | Generate root DESIGN.md from existing project code |
/impeccable extract | Pull reusable components and tokens into the design system |
/impeccable shape | Plan UX/UI before writing code |
/impeccable critique | UX design review: hierarchy, clarity, emotional resonance |
/impeccable audit | Run technical quality checks (a11y, performance, responsive) |
/impeccable polish | Final pass, design system alignment, and shipping readiness |
/impeccable bolder | Amplify boring designs |
/impeccable quieter | Tone down overly bold designs |
/impeccable distill | Strip to essence |
/impeccable harden | Error handling, i18n, text overflow, edge cases |
/impeccable onboard | First-run flows, empty states, activation paths |
/impeccable animate | Add purposeful motion |
/impeccable colorize | Introduce strategic color |
/impeccable typeset | Fix font choices, hierarchy, sizing |
/impeccable layout | Fix layout, spacing, visual rhythm |
/impeccable delight | Add moments of joy |
/impeccable overdrive | Add technically extraordinary effects |
/impeccable clarify | Improve unclear UX copy |
/impeccable adapt | Adapt for different devices |
/impeccable optimize | Performance improvements |
/impeccable live | Visual variant mode: iterate on elements in the browser |
Use /impeccable pin <command> to create standalone shortcuts (e.g., pin audit creates /audit).
Usage Examples
/impeccable audit blog # Audit blog hub + post pages
/impeccable critique landing # UX design review
/impeccable polish settings # Final pass before shipping
/impeccable harden checkout # Add error handling + edge cases
Or use /impeccable directly with a description:
/impeccable redo this hero section
Anti-Patterns
The skill includes explicit guidance on what to avoid:
- Don't use overused fonts (Arial, Inter, system defaults)
- Don't use gray text on colored backgrounds
- Don't use pure black/gray (always tint)
- Don't wrap everything in cards or nest cards inside cards
- Don't use bounce/elastic easing (feels dated)
See It In Action
Visit impeccable.style to see before/after case studies of real projects transformed with Impeccable commands.
Installation
Option 1: Download from Website (Recommended)
Visit impeccable.style, download the ZIP for your tool, and extract to your project.
Option 2: Copy from Repository
Cursor:
cp -r dist/cursor/.cursor your-project/
Note: Cursor skills require setup:
- Switch to Nightly channel in Cursor Settings → Beta
- Enable Agent Skills in Cursor Settings → Rules
Claude Code:
# Project-specific
cp -r dist/claude-code/.claude your-project/
# Or global (applies to all projects)
cp -r dist/claude-code/.claude/* ~/.claude/
OpenCode:
cp -r dist/opencode/.opencode your-project/
Pi:
cp -r dist/pi/.pi your-project/
Gemini CLI:
cp -r dist/gemini/.gemini your-project/
Note: Gemini CLI skills require setup:
- Install preview version:
npm i -g @google/gemini-cli@preview- Run
/settingsand enable "Skills"- Run
/skills listto verify installation
Codex CLI:
# Project-local
cp -r dist/agents/.agents your-project/
# Or user-wide
mkdir -p ~/.agents/skills
cp -r dist/agents/.agents/skills/* ~/.agents/skills/
GitHub Copilot:
cp -r dist/github/.github your-project/
Trae:
# Trae China (domestic version)
cp -r dist/trae/.trae-cn/skills/* ~/.trae-cn/skills/
# Trae International
cp -r dist/trae/.trae/skills/* ~/.trae/skills/
Note: Trae has two versions with different config directories:
- Trae China:
~/.trae-cn/skills/- Trae International:
~/.trae/skills/After copying, restart Trae IDE to activate the skills.
Rovo Dev:
# Project-specific
cp -r dist/rovo-dev/.rovodev your-project/
# Or global (applies to all projects)
cp -r dist/rovo-dev/.rovodev/skills/* ~/.rovodev/skills/
Qoder:
# Project-specific
cp -r dist/qoder/.qoder your-project/
# Or global (applies to all projects)
cp -r dist/qoder/.qoder/skills/* ~/.qoder/skills/
Usage
Once installed, use commands in your AI harness:
/audit # Find issues
/normalize # Fix inconsistencies
/polish # Final cleanup
/distill # Remove complexity
Most commands accept an optional argument to focus on a specific area:
/audit header
/polish checkout-form
Note: Codex uses skills here, not /prompts: commands. Open /skills or type $impeccable. Repo-local installs live in .agents/skills/; user-wide installs live in ~/.agents/skills/. GitHub Copilot uses .github/skills/. Restart the tool if a newly installed skill does not appear.
CLI
Impeccable includes a standalone CLI for detecting anti-patterns without an AI harness:
npx impeccable detect src/ # scan a directory
npx impeccable detect index.html # scan an HTML file
npx impeccable detect https://example.com # scan a URL (Puppeteer)
npx impeccable detect --fast --json . # regex-only, JSON output
The detector catches 24 issues across AI slop (side-tab borders, purple gradients, bounce easing, dark glows) and general design quality (line length, cramped padding, small touch targets, skipped headings, and more).
Supported Tools
Community & Ecosystem
Join the community and ecosystem conversations:
- GitHub Discussions: file bugs, request features, and help newcomers.
- Impeccable on npm: grab the CLI, follow releases, and star the package.
- Follow @pbakaus on Twitter for release notes, sample lint reports, and video highlights of new rules.
Contributing
See DEVELOP.md for contributor guidelines and build instructions.
License
Apache 2.0. See LICENSE.
The impeccable skill builds on Anthropic's original frontend-design skill. See NOTICE.md for attribution.
Created by Paul Bakaus