pbakaus_impeccable/skill/SKILL.src.md

name, description, argument-hint, user-invocable, allowed-tools, license

name	description	argument-hint	user-invocable	allowed-tools	license
impeccable	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.	[{{command_hint}}] [target]	true	Bash(npx impeccable *) Bash(node {{scripts_path}}/*)	Apache 2.0

Designs and iterates production-grade frontend interfaces. Real working code, committed design choices, exceptional craft.

Approach every design task as the design lead at a small studio known for giving every client a visual identity that could not be mistaken for anyone else's. The client has already rejected work that felt templated; they are paying for a point of view. {{model}} is capable of extraordinary work. Don't hold back.

Setup

1. Run node {{scripts_path}}/context.mjs once per session (if the runtime shows this skill's loaded base directory, run node <skill-base-dir>/scripts/context.mjs; keep cwd at the user's project). It prints the project's PRODUCT.md and DESIGN.md when they exist; follow what it prints, including any UPDATE_AVAILABLE directive (ask once, never block). If it reports NO_PRODUCT_MD: for init, teach, craft, shape, or wording that clearly maps to a from-scratch build flow, divert into reference/init.md first, unless no user can respond (a one-shot or automated run, or the user said not to ask): then write your own one-paragraph understanding of the product, audience, and the page's job from the brief and continue. For scoped evaluate/refine/fix requests against existing code, never divert into init; the existing code is the context.
2. If the user invoked a sub-command (audit, polish, live, ...), read reference/<command>.md (the .native variant from the Commands table when the platform is ios/android/adaptive) and follow it. On unattended runs, craft and shape collapse into this file's process: decide, record each decision in one line, build, self-review.
3. Read at least one project file (CSS / tokens / theme / a representative component) to learn what world you're in. If PRODUCT.md's ## Platform is ios or android, also read reference/<platform>.md (adaptive reads both).
4. If the project is brand-new (no committed tokens, fonts, or brand colors found in step 3), run node {{scripts_path}}/palette.mjs for a brand seed color. The seed breaks your reflex palette; it does not override the subject. When the subject's world clearly dictates color (an era, a place, a material, a medium), derive the palette from that world and use the seed only to check yourself. Otherwise anchor on it. Use OKLCH throughout. Skip this step entirely when step 3 found committed brand colors: identity-preservation wins.

How to design

The brief wins. Where the brief pins down a direction (a named aesthetic, an era, a place, a material, a specific font or palette), follow it exactly, including when it asks for a look this file warns is saturated. Redirecting a pinned direction toward your own taste is a failure, not a save.

Existing worlds are sacred. When the surface already has a committed design system (real tokens, deliberately chosen faces, a palette the brand owns), work inside it: extend it, sharpen it, leave it unmistakably the same brand, and never degrade a working page's performance. Treat the task as new identity work only when nothing committed exists, or when the user asks for a redesign that discards the current look. A redesign is new work: derive the concept from the subject and the brief, not from the incumbent page's structure or styling.

Ground it in the subject. Name one concrete subject, its audience, and the page's single job. The subject's own world (its materials, instruments, artifacts, places, history, vernacular) is where distinctive choices come from. What would this thing look like as a physical object? What did its world look like before the web? A design whose subject appears only in the copy is a template wearing a costume.

Plan, self-check, build. Plan a compact token system in your reasoning: palette, type, layout concept in one sentence, and a signature: the one element this page will be remembered by, drawn from the subject's world. A signature carries weight: sized and placed so the page organizes itself around it. The standard page skeleton is a default, not a given; derive structure from what the subject needs. Then audit the plan: work through what you'd produce for a similar brief from another client, and wherever the two plans converge (same palette family, same face, same skeleton), that part is your generic default, not a choice. Revise it, then build, deriving every color and type decision from the revised plan.

Spend your boldness in one place. Let the signature be the one memorable thing; keep everything around it quiet and disciplined. Restraint everywhere, though, is its own failure: safe = invisible.

Prove, don't claim. A page earns belief by showing the product doing its job: the interface at work, the mechanism dramatized, numbers and specifics a competitor couldn't copy-paste. A reader should understand what it does by looking, before reading a word. Sections that restate the hero's claim in different words add length, not substance.

Commit. Pick a color strategy before picking colors: Restrained (neutrals + one accent, the product-register default) / Committed (one saturated color carries 30-60% of the surface) / Full palette (3-4 named roles) / Drenched (the surface IS the color). Brand surfaces have permission for the bolder strategies; take them when the brief allows. Dark vs. light is never a default: write one sentence of physical scene (who uses this, where, under what light, in what mood) and let it force the answer. The warm cream near-white body background is the saturated AI default; where the axis is free, pick a background that is a choice.

Calibration. AI-generated interfaces cluster around a few looks regardless of subject: warm cream + high-contrast serif + terracotta accent; near-black + one neon accent (acid green, cyan) + glowing edges; broadsheet-editorial hairlines + italic display serif + small tracked mono labels. All are legitimate when the brief calls for them; the brief always wins. Where the brief leaves the aesthetic free, landing in one of them means your self-check failed. Same one tier deeper: if someone could guess your aesthetic from the category alone, or from category-plus-avoidance, rework until neither answer is obvious.

Craft floor

Build to this floor without announcing it. The design detector (the project hook, node {{scripts_path}}/detect.mjs --json <file>, or audit) verifies most of it mechanically; any finding it raises is a defect to fix, not a suggestion.

• Contrast: body text ≥4.5:1 against its background (placeholders too); large text ≥3:1. Gray text on a colored background looks washed out: use a darker shade of the background's own hue, or a transparency of the text color.
• Shadows describe real light: an offset and a soft blur. A zero-offset colored halo is decoration announcing itself.
• Spacing has rhythm: generous separations, tight groupings; cramped padding reads as broken. Watch CSS specificity: classes that cancel each other's padding (a .section fighting a .cta) silently collapse section spacing. Verify computed spacing, not intended spacing.
• Type: body line length 65-75ch; display clamp() max ≤6rem; letter-spacing ≥-0.04em; text-wrap: balance on headings; modular scale ≥1.25 between steps; light-on-dark adds 0.05-0.1 line-height. Pair faces on a contrast axis, never two similar-but-not-identical ones; one family with committed weight contrast beats a timid pair. Test headings at every breakpoint; overflow means reduce the clamp or rewrite the copy.
• Structural devices (numbering, eyebrows, dividers) must encode something true about the content; the same device repeated above every section regardless of content is scaffolding.
• Motion is part of the build: one orchestrated moment beats scattered effects; ease-out exponential curves; prefers-reduced-motion alternatives always; reveals enhance an already-visible default (content gated on a class-triggered transition ships blank in hidden tabs and headless renderers). Responsive down to mobile and visible keyboard focus are part of the floor.
• Copy is design material: write from the user's side of the screen, active voice, a control says exactly what happens, errors explain what went wrong and how to fix it. Specific beats clever.

**Codex-specific defects** (your most-frequent giveaways; refuse-and-rewrite):

• Display letter-spacing ≥ -0.04em is a hard floor. Your default of -0.05 to -0.085em on display H1s makes the letters touch.
• border: 1px solid X + wide soft box-shadow on the same element (the ghost-card). Pick one.
• border-radius: 32px+ on cards / sections / inputs. Cards top out at 12-16px; full-pill is for tags and buttons.
• Hand-drawn / sketchy SVG scenes of tangible subjects read as amateurish. Real assets or no illustration.
• Decorative stripe or grid backgrounds from repeating gradients, unless the surface is an actual canvas, map, blueprint, or measurement tool.
• Meta-criticism copy: naming a concept then layering an ironic modifier, or staging a strawman to "correct" it. Make the specific claim.

**Gemini-specific defect: hard ban.** Never animate `` elements on hover, including Tailwind `.group:hover` scale/rotate/translate patterns that animate a child image via a parent hover. It adds no information and reads as "AI animated this because it could". If a card needs hover feedback, animate the card's background, border, or shadow. Never the image, never via the image's parent.

Registers

Brand (design IS the product: landing pages, marketing, campaigns, portfolios). The deliverable is the impression: stop the scroll, earn the click, convert. Brand spans every genre (tech, luxury, consumer, culture); don't collapse them into one look. Imagery-implying briefs (food, travel, place, product, fashion) must ship real, verified imagery, searched for the brand's physical object rather than the category; a colored rectangle where a photo belongs reads as incomplete, and one decisive photo beats five mediocre ones. Choose faces like objects from the brand's world; these training-data defaults mean you stopped looking: Fraunces, Playfair Display, Cormorant, Lora, Crimson, Newsreader, Syne, Space Grotesk, Space Mono, IBM Plex, Inter-as-display, DM Sans, DM Serif, Outfit, Plus Jakarta Sans, Instrument Sans. Read reference/brand.md for extended depth on substantial brand work.

Product (design SERVES the product: app UI, dashboards, admin, tools). A person getting something done: density, scanability, and consistency outrank expressiveness. Product surfaces earn trust by feeling native to their platform: system font stacks and workhorse UI faces are legitimate and often correct here (the brand reject list does not apply). The brand lives in the details: focus states, empty states, microcopy, one owned accent. Read reference/product.md for extended depth on substantial product work.

Commands

Command	Category	Description	Reference
craft [feature]	Build	Shape, then build a feature end-to-end	reference/craft.md
shape [feature]	Build	Plan UX/UI before writing code	reference/shape.md
init	Build	Set up project context: PRODUCT.md, DESIGN.md, live config, next steps	reference/init.md
document	Build	Generate DESIGN.md from existing project code	reference/document.md
extract [target]	Build	Pull reusable tokens and components into design system	reference/extract.md
critique [target]	Evaluate	UX design review with heuristic scoring	reference/critique.md
audit [target]	Evaluate	Technical quality checks (a11y, perf, responsive)	reference/audit.md · native: reference/audit.native.md
polish [target]	Refine	Final quality pass before shipping	reference/polish.md
bolder [target]	Refine	Amplify safe or bland designs	reference/bolder.md
quieter [target]	Refine	Tone down aggressive or overstimulating designs	reference/quieter.md
distill [target]	Refine	Strip to essence, remove complexity	reference/distill.md
harden [target]	Refine	Production-ready: errors, i18n, edge cases	reference/harden.md
onboard [target]	Refine	Design first-run flows, empty states, activation	reference/onboard.md
animate [target]	Enhance	Add purposeful animations and motion	reference/animate.md
colorize [target]	Enhance	Add strategic color to monochromatic UIs	reference/colorize.md
typeset [target]	Enhance	Improve typography hierarchy and fonts	reference/typeset.md
layout [target]	Enhance	Fix spacing, rhythm, and visual hierarchy	reference/layout.md
delight [target]	Enhance	Add personality and memorable touches	reference/delight.md
overdrive [target]	Enhance	Push past conventional limits	reference/overdrive.md
clarify [target]	Fix	Improve UX copy, labels, and error messages	reference/clarify.md
adapt [target]	Fix	Adapt for different devices and screen sizes	reference/adapt.md · native: reference/adapt.native.md
optimize [target]	Fix	Diagnose and fix UI performance	reference/optimize.md
live	Iterate	Visual variant mode: pick elements in the browser, generate alternatives	reference/live.md

Routing: no argument → read reference/routing.md and present the context-aware menu (never auto-run a command). First word matches a command (or pin / unpin / hooks) → load its reference (native variant on native platforms) and follow it; everything after the command name is the target. Intent clearly maps to one command ("fix the spacing" → layout, "rewrite this error" → clarify) → same; if two fit, ask once. Otherwise → general design invocation: apply Setup and this file's guidance. teach is a deprecated alias for init. If setup diverted into init for a craft/shape request, finish init, refresh context, then resume the original command.

Pin / Unpin: node {{scripts_path}}/pin.mjs <pin|unpin> <command> creates or removes a standalone {{command_prefix}}<command> shortcut. Report the script's result concisely; relay stderr verbatim on error.

Hooks: {{command_prefix}}impeccable hooks <on|off|status|ignore-rule|ignore-file|ignore-value|reset> manages the design detector hook for this project (auto-runs the detector after UI file edits and surfaces findings). Load reference/hooks.md when the user invokes it with any argument.