diff --git a/.agents/skills/impeccable/SKILL.md b/.agents/skills/impeccable/SKILL.md index 25044b37a..8af38df3d 100644 --- a/.agents/skills/impeccable/SKILL.md +++ b/.agents/skills/impeccable/SKILL.md @@ -5,28 +5,15 @@ description: Use when the user wants to design, redesign, shape, critique, audit Designs and iterates production-grade frontend interfaces. Real working code, committed design choices, exceptional craft. -## Setup (non-optional) +## Setup -Before any design work or file edits, pass these gates. Skipping them produces generic output that ignores the project. +Before any design work or file edits: -| 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. | +1. Load context (PRODUCT.md / DESIGN.md) via the loader script. +2. Identify the register and load the matching register reference (brand.md or product.md). +3. **If the user invoked a sub-command (e.g. `craft`, `shape`, `audit`), load its reference file too.** This is non-negotiable: `craft` without `craft.md` loaded means you'll skip the shape-and-confirm step the user expects. -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: 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. +Skipping these produces generic output that ignores the project. ### 1. Context gathering diff --git a/.agents/skills/impeccable/reference/brand.md b/.agents/skills/impeccable/reference/brand.md index b069f2553..3d83a1cdc 100644 --- a/.agents/skills/impeccable/reference/brand.md +++ b/.agents/skills/impeccable/reference/brand.md @@ -12,6 +12,8 @@ Brand isn't a neutral register. AI-generated landing pages have flooded the inte **The second slop test: aesthetic lane.** Before committing to moves, name the reference. A Klim-style specimen page is one lane; Stripe-minimal is another; Liquid-Death-acid-maximalism is another. Don't drift into editorial-magazine aesthetics on a brief that isn't editorial. A hiking brand with Cormorant italic drop caps has the wrong register within the register. +Then the inverse test: in one sentence, describe what you're about to build the way a competitor would describe theirs. If that sentence fits the modal landing page in the category, restart. + ## Typography ### Font selection procedure @@ -66,6 +68,7 @@ Brand surfaces have permission for Committed, Full palette, and Drenched strateg - Palette IS voice. A calm brand and a restless brand should not share palette mechanics. - When the strategy is Committed or Drenched, color carries the brand. Don't hedge with neutrals around the edges. Commit. - Don't converge across projects. If the last brand surface was restrained-on-cream, this one is not. +- When a cultural-symbol palette is the obvious pull, reach past it. Let the cultural reading come from typography, imagery, and copy, not the palette. ## Layout @@ -79,14 +82,14 @@ Brand surfaces have permission for Committed, Full palette, and Drenched strateg Brand surfaces lean on imagery. A restaurant, hotel, magazine, or product landing page without any imagery reads as incomplete, not as restrained. A solid-color rectangle where a hero image should go is worse than a representative stock photo. -**When the brief implies imagery (restaurants, hotels, magazines, photography, hobbyist communities, food, travel, fashion, product), you must ship imagery.** Zero images is a bug, not a design choice. "Restraint" is not an excuse. +**When the brief implies imagery (restaurants, hotels, magazines, photography, hobbyist communities, food, travel, fashion, product), you must ship imagery.** Zero images is a bug, not a design choice. "Restraint" is not an excuse. If the approved comp or brief is image-led, ship real project assets, generated raster assets, or a credible canvas/SVG/WebGL scene. Do not replace photographic, architectural, product, or place imagery with generic CSS panels, decorative diagrams, cards, bullets, or copy. -- **For greenfield work without local assets, use stock imagery.** Unsplash is the default. The URL shape is `https://images.unsplash.com/photo-{id}?auto=format&fit=crop&w=1600&q=80`. Pick real Unsplash photo IDs you're confident exist (`photo-1559339352-11d035aa65de`, `photo-1590490360182-c33d57733427`, etc.); if unsure, pick fewer photos but don't substitute colored `
` placeholders. +- **For greenfield work without local assets, use stock imagery.** Unsplash is the default. The URL shape is `https://images.unsplash.com/photo-{id}?auto=format&fit=crop&w=1600&q=80`. **Verify the URLs before referencing them.** If you have an image-search MCP, web-fetch tool, or browser access, use it to find real photo IDs and confirm they resolve. Guessed IDs (even ones that look real) often 404 and ship as broken-image placeholders. Without a verification path, pick fewer photos you're confident exist over more that you guessed; never substitute colored `
` placeholders. - **Search for the brand's physical object**, not the generic category: "handmade pasta on a scratched wooden table" beats "Italian food"; "cypress trees above a limestone hotel facade at dusk" beats "luxury hotel". - **One decisive photo beats five mediocre ones.** Hero imagery should commit to a mood; padding with more stock doesn't rescue an indecisive one. - **Alt text is part of the voice.** "Coastal fettuccine, hand-cut, served on the terrace" beats "pasta dish". -Tech / dev-tool brands are the exception where zero imagery can be correct; a developer landing page often carries its voice through typography, code samples, diagrams. Know which kind of brand you're working on. +"Imagery" here is broader than stock photography: product screenshots, custom data visualizations, generated SVG, and canvas/WebGL scenes are all imagery. Text-only pages where typography alone carries the entire visual weight are the failure mode. ## Motion @@ -102,6 +105,7 @@ Tech / dev-tool brands are the exception where zero imagery can be correct; a de - Timid palettes and average layouts. Safe = invisible. - Zero imagery on a brief that implies imagery (restaurant, hotel, food, travel, fashion, photography, hobbyist). Colored blocks where a hero photo belongs. - Defaulting to editorial-magazine aesthetics (display serif + italic + drop caps + broadsheet grid) on briefs that aren't magazine-shaped. Editorial is ONE aesthetic lane, not the default brand aesthetic. +- Repeated tiny uppercase tracked labels above every section heading. A single strong kicker can be voice; repeating it as section grammar is AI scaffolding unless it's a deliberate, named brand system. ## Brand permissions diff --git a/.agents/skills/impeccable/reference/craft.md b/.agents/skills/impeccable/reference/craft.md index 337b5c9b7..98f6ad593 100644 --- a/.agents/skills/impeccable/reference/craft.md +++ b/.agents/skills/impeccable/reference/craft.md @@ -1,43 +1,41 @@ # Craft Flow -Build a feature with impeccable UX and UI quality through a structured process: shape the design, land the visual direction, build real production code, then inspect and improve in-browser until the result meets a high-end studio bar. +Build a feature with impeccable UX and UI quality: shape the design, land the visual direction, build real production code, inspect and improve in-browser until it meets a high-end studio bar. -## Build Gate +Before writing code, you need: PRODUCT.md loaded, register identified and the matching reference loaded, and a confirmed design direction for this task (either from `shape` or supplied by the user). PRODUCT.md is project context, not a task-specific brief. -Craft cannot build until all of these are true: +Treat any approved visual direction (generated mock or stated reference) as a concrete contract for composition, hierarchy, density, atmosphere, signature motifs, and distinctive visual moves. Don't let mocks replace structure, copy, accessibility, or state design. But if the live result lacks the approved direction's major ingredients, the implementation is wrong. -1. PRODUCT context is valid and current. -2. The shape design brief is explicitly confirmed by the user for this task, unless the user already provided a confirmed brief. -3. Implementation references from the brief are loaded. -4. The shape visual probe decision is recorded: generated, skipped with reason, or already resolved. -5. The north-star mock decision is recorded: generated, skipped with reason, or not applicable. +## Step 0: Project Foundation -PRODUCT.md and `teach` answers do **not** satisfy the shape gate. They are project context only. A compact self-authored brief does not satisfy the shape gate either. `shape=pass` requires a separate user response approving the shape brief or an already-confirmed brief supplied by the user. +Before shape, before code: figure out what kind of project you're working in. -Invalid image-skip reasons include: "the final implementation will be semantic HTML/CSS/SVG", "the diagram should stay editable", "a raster mock would not be used directly", or "the product is fictional." Generated probes and mocks are direction artifacts; they are not implementation assets. +Look at the working directory. Run `ls`. Check for: -## Craft Contract +- An existing framework: `astro.config.mjs/ts`, `next.config.js/ts`, `nuxt.config.ts`, `svelte.config.js`, `vite.config.js/ts`, `package.json` with framework deps, `Cargo.toml` + Leptos/Yew, `Gemfile` + Rails. **If found, use it.** Do not start a parallel build, do not introduce a second framework, do not write to `dist/` or `build/` directly. Whatever pipeline the project has, respect it. +- An existing component library or design system: `src/components/`, `app/components/`, a `tokens.css` / `theme.ts`, an `astro.config` `integrations`. Read what's there before adding to it. +- An existing icon set: `lucide-react`, `@phosphor-icons/react`, `@iconify/*`, hand-rolled SVG sprites in `assets/icons/`. **Use what's already in the project**; don't introduce a second set. -Craft is not a first pass. It is a loop with these required artifacts: +If the directory is empty (greenfield), don't pick a framework silently. Ask the user via the AskUserQuestion tool, with sensible defaults framed by the brief: -1. Confirmed design brief from `shape`. -2. Approved visual direction, from generated probes / mocks when image generation is available. -3. Mock fidelity inventory: the visible ingredients from the approved direction that must survive into code. -4. Semantic, functional implementation using the project's real stack and conventions. -5. Browser evidence across relevant viewports. -6. At least one critique-and-fix pass after the first browser inspection, unless the first pass has no material defects. +```text +What should this be built on? + - Astro (default for content-led brand sites, landing pages, marketing surfaces) + - SvelteKit / Next.js / Nuxt (when the brief implies an app surface or significant interactivity) + - Single index.html (one-shot demo, prototype, or a deliberately framework-free experiment) +``` -Do not let generated mockups replace interface structure, copy, accessibility, responsive behavior, or state design. But do treat the approved mock as a concrete visual contract for composition, hierarchy, density, atmosphere, signature motifs, image needs, and distinctive visual moves. "North star" means "preserve the important visible ingredients in semantic code," not "use it as loose mood." +Default: Astro for brand briefs, the project's existing framework for product briefs. Ask once; don't re-ask mid-task. ## Step 1: Shape the Design -Run $impeccable shape, passing along whatever feature description the user provided. +Run $impeccable shape, passing along whatever feature description the user provided. Shape is **required** for craft; it is what produces a confirmed direction. -Wait for the design brief to be fully confirmed by the user before proceeding. The brief is your blueprint, and every implementation decision should trace back to it. +Present the shape output and stop. Wait for the user to confirm, override, or course-correct before writing code. -If this craft run resumed after `teach` created PRODUCT.md, run shape now. Do not treat the teach interview, PRODUCT.md, or a summary of project context as a substitute for shape. Shape is task-specific and must cover scope, content/states, visual direction, constraints, anti-goals, probes when applicable, and explicit brief confirmation. +If the user already supplied a confirmed brief or ran shape separately, use it and skip this step. -If the user has already run $impeccable shape and has a confirmed design brief, skip this step and use the existing brief. +When the original prompt + PRODUCT.md already answer scope, content, and visual direction with no real ambiguity, the shape output can be **compact** (3-5 bullets stating what you're building and the visual lane, ending with one or two specific questions or "confirm or override"). The full 10-section structured brief is reserved for genuinely ambiguous, multi-screen, or stakeholder-heavy tasks. Don't pad a clear brief into a long one to look thorough; equally, don't skip the pause to look efficient. ## Step 2: Load References @@ -55,79 +53,60 @@ Then add references based on the brief's needs: ## Step 3: Land the Visual Direction (Capability-Gated) -Before implementation, generate high-fidelity visual comps when all of these are true: +Generate high-fidelity visual comps before implementation when all three are true: -- The work is **net-new** or visually open-ended enough that composition exploration will improve the build. -- The brief's scope is **mid-fi, high-fi, or production-ready**. -- The current harness has **built-in image generation capability** (for example, Codex with a native image tool). Do **not** ask the user to set up external APIs, shell scripts, or one-off tooling just to do this. +- The work is net-new or visually open-ended enough that composition exploration will improve the build. +- The brief's scope is mid-fi, high-fi, or production-ready. +- The harness gives you native image generation (Codex's `image_gen`, an equivalent MCP tool). Don't ask the user to set up external APIs. -When those conditions are met, this step is mandatory for **both brand and product work** in Codex and any harness with built-in image generation. Use native image generation; in Codex, use the built-in `image_gen` tool via the imagegen skill. If image generation is unavailable, do not ask the user to install APIs or tooling. State in one line that the image step is skipped because the harness lacks native image generation, then proceed. - -Do not skip this step because the eventual UI should be semantic, editable, code-native, responsive, or accessible. Those are implementation requirements, not reasons to avoid visual exploration. - -### Purpose - -Use the mock step to find a stronger visual lane than code-first generation would reliably discover on its own. The brief remains authoritative on user, purpose, content, constraints, states, and anti-goals. The mock clarifies composition, hierarchy, density, typography, and visual tone. +When met, this step is mandatory for both brand and product work. If image generation isn't available, skip silently. "The eventual UI is semantic/code-native/accessible" is not a reason to skip; those are implementation requirements, not exploration ones. ### What to generate -Generate **1 to 3** high-fidelity north-star comps based on the confirmed brief. If shape already produced direction probes, use those results as input and generate a more resolved mock from the winning lane, not another unrelated exploration. +Generate **1 to 3** high-fidelity north-star comps from the confirmed brief. If shape already produced direction probes, resolve the winning lane further, not an unrelated exploration. Comps must differ in primary visual direction, not just color. -- For brand work, push visual identity, composition, and mood aggressively. -- For product work, still push hierarchy, topology, density, and tone, but keep the comps grounded in realistic product structure and states. -- For landing pages and long-form brand surfaces, show enough of the next section or second fold to establish the system beyond the hero. - -The comps must be genuinely different in primary visual direction, not just color variants. +- Brand work: push visual identity, composition, and mood aggressively. +- Product work: push hierarchy, topology, density, tone, grounded in realistic product structure. +- Landing pages and long-form brand surfaces: show enough of the second fold to establish the system beyond the hero. ### Approval loop -Show the comps and ask what should carry forward. If the user asks for changes or the best direction is still weak, generate a focused revision before implementation. Continue until one direction is approved, or until the user explicitly delegates the choice. +Show the comps and ask what carries forward. Iterate until one direction is approved or the user delegates. If the user delegates, pick the strongest direction and explain it from the brief, not personal taste. -If the user delegates, pick the strongest direction and explain the decision using the brief, not personal taste. - -Before moving to implementation, summarize: - -- What to carry into code -- What **not** to literalize from the mock - -This summary is required before Step 4. It is the handoff between visual exploration and semantic implementation. +Before Step 4, summarize what to carry into code and what **not** to literalize from the mock. This is the handoff between visual exploration and semantic implementation. ### Mock fidelity inventory -Before building, inventory the approved mock's major visible ingredients: +Inventory the approved mock's major visible ingredients: -- Hero silhouette and dominant composition. -- Signature motifs: planets, devices, portraits, charts, route lines, insets, badges, or other memorable objects. -- Nav and primary CTA treatment. -- Section sequence visible in the mock, especially the second fold. -- Image-native content the concept depends on. -- Typography, density, color/material treatment, and motion cues. +- Hero silhouette and dominant composition +- Signature motifs (planets, devices, portraits, charts, route lines, insets, badges, etc.) +- Nav and primary CTA treatment +- Section sequence, especially the second fold +- Image-native content the concept depends on +- Typography, density, color/material treatment, motion cues -For each ingredient, decide how it will be implemented: semantic HTML/CSS/SVG, generated asset, sourced project asset, icon library, canvas/WebGL, or an explicitly accepted omission. Do not substitute a different hero composition or new visual driver after approval unless the user approves the change. +For each, decide implementation: semantic HTML/CSS/SVG, generated asset, sourced asset, icon library, canvas/WebGL, or accepted omission. Don't substitute a different hero composition or visual driver post-approval without user sign-off. -Treat the mock as a **north star**, not a screenshot to trace. Do **not** rasterize core UI text or let the mock override the confirmed brief. But if the live result lacks the mock's major visible ingredients, the implementation is wrong. +If a photographic, architectural, product, or place-led mock becomes generic CSS scenery / decorative diagrams / bullets / copy, stop and fix it. That's a broken implementation, not a harmless interpretation. + +Treat the mock as a north star, not a screenshot to trace. Don't rasterize core UI text. But if the live result lacks the mock's major ingredients, the implementation is wrong. ## Step 4: Asset Extraction (Need-Gated) -If the chosen direction includes image-native visual ingredients that would materially improve the implementation, generate them as separate assets before building. +If the approved direction needs raster assets, create them before building. Do not replace required imagery with generic cards, bullets, emoji, fake metrics, decorative CSS panels, or filler copy. -Good candidates: +Use the native asset producer (`impeccable_asset_producer` in Codex, `impeccable-asset-producer` in Claude Code) to create clean assets from the hi-fi mock and crops. If you do not have explicit permission to use agents, stop and ask: -- stickers -- badges -- seals -- tickets -- graphic labels -- textures -- abstract objects -- decorative marks -- non-semantic scene elements +```text +Asset production will work better as a scoped subagent job. Should I spawn the Impeccable asset producer subagent for this step? +``` -For travel, editorial, portfolio, venue, product showcase, entertainment, education, or any other image-led brand surface, visual assets are usually core content, not decoration. Do not ship abstract CSS panels where the approved mock or subject matter calls for real imagery, generated plates, illustrations, maps, product/object renders, or destination scenes. +Do not skip asset production or silently do it inline. Inline asset production is allowed only if the user declines subagents, the harness cannot spawn the authorized agent, or the user explicitly asks for single-thread mode. -Do **not** export assets for core UI text, navigation, body copy, or any structure that should stay semantic and editable in code. +Pass the approved mock, crop/contact-sheet paths, output directory, dimensions/formats, transparency needs, constraints, and avoid list to the asset producer. Attach image generation capability to the spawned agent when the harness supports it; do not load image-generation reference material into the parent thread first. -Usually **1 to 5** extracted assets is enough. If the design can be built cleanly in HTML/CSS/SVG, prefer that over raster assets. If the mock contains major visual content that cannot be built credibly in code, asset extraction is not optional. +Prefer HTML/CSS/SVG/canvas when they can credibly reproduce an ingredient; use real/generated/stock imagery when the mock or subject matter calls for actual visual content. ## Step 5: Build to Production Quality @@ -135,50 +114,35 @@ Implement the feature following the design brief. Build in passes so structure, ### Production bar -- Use real or realistic content. Remove placeholder copy, placeholder images, dead links, fake controls, and unused scaffold before presenting. -- Preserve the approved mock's major ingredients. Missing hero objects, missing world/product imagery, different section structure, downgraded CTA/nav treatment, or generic replacements for distinctive motifs are blocking defects unless the user accepted the change. -- Build semantically first: real headings, landmarks, labels, form associations, button/link semantics, accessible names, and state announcements where needed. -- Calibrate spacing, alignment, grid placement, and vertical rhythm deliberately. Do not accept default gaps, arbitrary margins, unbalanced whitespace, or accidental optical misalignment. -- Make typography intentional: chosen font loading strategy, clear hierarchy, readable measure, stable line breaks, tuned wrapping, and no overflow at mobile or large desktop sizes. -- Design realistic state coverage: default, hover where supported, focus-visible, active, disabled, loading, error, success, empty, overflow, long text, short text, and first-run states where relevant. -- Make interaction quality feel finished: keyboard paths, touch targets, feedback timing, scroll behavior, transitions between states, and no hover-only functionality. -- Use icons from the project's established icon set when available. If no set exists, choose a coherent library or use accessible text controls; do not mix unrelated icon styles. -- Optimize imagery and media: correct dimensions, useful alt text, lazy loading below the fold, modern formats when practical, responsive `srcset` / `picture` for raster assets, and no project-referenced asset left outside the workspace. -- Make motion feel premium: use atmospheric blur, filter, mask, shadow, or reveal effects when they improve the experience; avoid casual layout-property animation, bound expensive effects, verify smoothness in-browser, respect reduced motion, and avoid choreography that blocks task completion. -- Preserve maintainability: reusable local patterns, clear component boundaries, project conventions, no rasterized UI text, and no hard-coded one-off hacks when a better local pattern exists. -- Fit the technical context: production build passes, no obvious console errors, no avoidable layout shift, no needless dependency, and no broken asset path. -- If you discover a design question that materially changes the brief or approved direction, stop and ask rather than guessing. +- **Real content.** No placeholder copy, placeholder images, dead links, fake controls, or unused scaffold at presentation time. +- **Preserve the approved mock's major ingredients.** Missing hero objects, world/product imagery, section structure, CTA/nav treatment, or distinctive motifs are blocking defects unless the user accepted the change. +- **Semantic first.** Real headings, landmarks, labels, form associations, button/link semantics, accessible names, state announcements where needed. +- **Deliberate spacing and alignment.** No default gaps, arbitrary margins, unbalanced whitespace, or accidental optical misalignment. +- **Intentional typography.** Chosen loading strategy, clear hierarchy, readable measure, stable line breaks, no overflow at any width. +- **Realistic state coverage.** Default, hover, focus-visible, active, disabled, loading, error, success, empty, overflow, long/short text, first-run. +- **Finished interaction quality.** Keyboard paths, touch targets, feedback timing, scroll behavior, state transitions, no hover-only functionality. +- **Coherent icon set.** Use the project's established set; otherwise pick one library or use accessible text. Don't mix. +- **Respect the build pipeline.** Edit source files and run the project's build (`npm run build` or equivalent). Don't write to `build/` / `dist/` / `.next/` with `cat`, heredoc, or Bash redirects; that skips asset hashing, image optimization, code splitting, and CSS extraction, and produces output the dev server won't serve. +- **Verify image URLs before referencing them.** Use image-search MCP or web-fetch when available; guessed photo IDs ship as broken-image placeholders. Without verification, prefer fewer images you're confident about. +- **Optimized imagery and media.** Correct dimensions, useful alt text, lazy loading below the fold, modern formats when practical, responsive `srcset`/`picture` for raster, no project-referenced asset left outside the workspace. +- **Premium motion.** Use atmospheric blur, filter, mask, shadow, reveal when they improve the experience. Avoid casual layout-property animation, bound expensive effects, verify smoothness in-browser, respect reduced motion, and avoid choreography that blocks task completion. +- **Maintainable.** Reusable local patterns, clear component boundaries, project conventions. No rasterized UI text or one-off hacks when a local pattern exists. +- **Technically clean.** Production build passes, no console errors, no avoidable layout shift, no needless dependencies, no broken asset paths. +- **Ask when uncertain.** If a discovery materially changes the brief or approved direction, stop and ask. Don't guess. -## Step 6: Browser-Based Iteration +## Step 6: Iterate Visually -**This step is critical.** Do not stop after the first implementation pass. +Look at what you built like a designer would. Your eyes are whatever the harness gives you: a connected browser, a screenshotting tool, Playwright, or asking the user. Use them for responsive testing (mobile, tablet, desktop minimum) and general visual validation. -Open the result in a browser. In Codex, use browser-use or equivalent browser automation when available; otherwise use Playwright or ask the user for screenshots. Inspect screenshots, not just DOM or terminal output. +If your tool returns a file path, read the PNG back into the conversation. A screenshot you didn't read doesn't count. -### Required viewport pass +For long-form brand surfaces, inspect major sections individually. Thumbnails hide spacing, clipping, and cascade defects. -Check the experience at the viewports that matter for the brief. Default minimum: +After the first pass, write an honest critique against the brief, the approved mock's major ingredients (hero silhouette, motifs, imagery, nav/CTA, density), and impeccable's DON'Ts. Patch material defects and re-inspect. **Don't invent defects to demonstrate iteration.** A confident "first pass clean, shipping" beats a fake fix. -- Mobile narrow -- Tablet or small laptop -- Desktop wide +Actively check: responsive behavior (composes, not shrinks), every state (empty / error / loading / edge), craft details (spacing, alignment, hierarchy, contrast, motion timing, focus), performance basics. The exit bar: defensible in a high-end studio review. -For each viewport, capture or inspect the rendered state and look for visual defects: overlap, clipping, weak hierarchy, off-grid alignment, awkward whitespace, cramped controls, unreadable type, broken imagery, hover-only functionality, layout shift, and text overflow. - -### Critique and fix loop - -After the first browser pass, write a short critique for yourself and patch the implementation. Repeat browser inspection after fixes. Continue until no material issues remain against this checklist: - -1. **Does it match the brief?** Compare the live result against every section of the design brief. Fix discrepancies. -2. **Does it match the approved mock?** Compare screenshots against the mock fidelity inventory: hero silhouette, major motifs, imagery, nav/CTA, section sequence, density, color/materials, and second-fold substance. Missing major ingredients are P0 defects. -3. **Does it pass the AI slop test?** If someone saw this and said "AI made this," would they believe it immediately? If yes, it needs more design intention. -4. **Check against impeccable's DON'T guidelines.** Fix any anti-pattern violations. -5. **Check every state.** Navigate through empty, error, loading, and edge case states. Each one should feel intentional, not like an afterthought. -6. **Check responsive behavior.** The design should adapt compositionally, not merely shrink. -7. **Check craft details.** Spacing consistency, optical alignment, type hierarchy, color contrast, image quality, icon coherence, interactive feedback, motion timing, and focus treatment. -8. **Check performance basics.** No obviously oversized images, avoidable layout thrash, blocking animations, or heavy assets without a reason. - -The exit bar is not "it works." It is: the rendered result looks intentional at all checked viewports, all expected states are handled, no placeholders remain unless explicitly accepted, and the implementation quality would be defensible in a high-end studio review. +Detector or QA output is defect evidence only; never proof the work is finished. ## Step 7: Present @@ -189,5 +153,3 @@ Present the result to the user: - Explain design decisions that connect back to the design brief and, when used, the chosen north-star mock. Include any accepted deviations from the mock; do not hide unimplemented mock ingredients. - Note any remaining limitations or follow-up risks honestly - Ask: "What's working? What isn't?" - -Iterate based on feedback. Good design is rarely right on the first pass. diff --git a/.agents/skills/impeccable/reference/critique.md b/.agents/skills/impeccable/reference/critique.md index 4e9b73db0..8079dd3ff 100644 --- a/.agents/skills/impeccable/reference/critique.md +++ b/.agents/skills/impeccable/reference/critique.md @@ -43,7 +43,7 @@ Run the bundled deterministic detector, which flags 27 specific patterns (AI slo **CLI scan**: ```bash -npx impeccable --json [--fast] [target] +npx impeccable detect --json [--fast] [target] ``` - Pass HTML/JSX/TSX/Vue/Svelte files or directories as `[target]` (anything with markup). Do not pass CSS-only files. diff --git a/.agents/skills/impeccable/reference/polish.md b/.agents/skills/impeccable/reference/polish.md index a2a409e48..eed3dbd27 100644 --- a/.agents/skills/impeccable/reference/polish.md +++ b/.agents/skills/impeccable/reference/polish.md @@ -2,6 +2,8 @@ Perform a meticulous final pass to catch all the small details that separate good work from great work. The difference between shipped and polished. +Detector and automated QA output are defect evidence only. A clean script result is never proof that the design is strong; gather browser evidence and inspect the real interaction path. + ## Design System Discovery Aligning the feature to the design system is **not optional**. Polish without alignment is decoration on top of drift, and it makes the next person's job harder. Discovery comes before any other polish work. @@ -216,11 +218,12 @@ Sweat the details. Zoom in until the alignment is right and the spacing reads as Before marking as done: -- **Use it yourself**: Actually interact with the feature -- **Test on real devices**: Not just browser DevTools -- **Ask someone else to review**: Fresh eyes catch things -- **Compare to design**: Match intended design -- **Check all states**: Don't just test happy path +- **Use it yourself**: Actually interact with the feature. +- **Test on real devices**: Not just browser DevTools. +- **Ask someone else to review**: Fresh eyes catch things. +- **Compare to design**: Match intended design. +- **Check all states**: Don't just test happy path. +- **Treat automation carefully**: Run detector or QA commands when they are available and relevant, fix their defects, but never cite a clean result as proof that the work is polished. ## Clean Up @@ -230,4 +233,3 @@ After polishing, ensure code quality: - **Remove orphaned code**: Delete unused styles, components, or files made obsolete by polish. - **Consolidate tokens**: If you introduced new values, check whether they should be tokens. - **Verify DRYness**: Look for duplication introduced during polishing and consolidate. - diff --git a/.agents/skills/impeccable/reference/shape.md b/.agents/skills/impeccable/reference/shape.md index 4eaa99a30..320b9397e 100644 --- a/.agents/skills/impeccable/reference/shape.md +++ b/.agents/skills/impeccable/reference/shape.md @@ -16,14 +16,16 @@ This is a required interaction, not optional guidance. Ask these questions in co ### Interview cadence -Discovery must include at least one user-answer round unless PRODUCT.md, DESIGN.md, or an already-confirmed brief directly answers the needed design inputs. With a sparse prompt, do **not** synthesize a complete brief for confirmation on the first response. +Discovery includes at least one user-answer round unless PRODUCT.md, DESIGN.md, or an already-confirmed brief directly answers the needed inputs. With a sparse prompt, do **not** synthesize a complete brief for confirmation on the first response. - Use the harness's structured question tool when one exists. Otherwise, ask directly in chat and stop. - Ask **2-3 questions per round**, then wait for answers. - Treat PRODUCT.md and DESIGN.md as anchors; they reduce repeated questions but do **not** replace shape for craft. Shape is task-specific. -- Round 1 should clarify purpose, audience/context, and success or emotional outcome. -- Round 2 should clarify content/data/states and scope/fidelity. -- Round 3 should clarify visual direction, constraints, and anti-goals when still unresolved. +- One round is the default. Add a second only if the first answers leave material gaps. Don't run a second round just to feel thorough. +- Round 1 should clarify purpose, audience/context, content/scope, and (for brand) visual direction. +- Round 2, when needed, fills in whatever's still genuinely missing. + +**Assert-then-confirm, not menu-with-escape.** When PRODUCT.md and the user's prompt make one option obvious, name it and ask the user to confirm or override. Don't enumerate "Restrained / Committed / Or something else?" as a real choice; "This reads as Restrained, confirm?" beats a four-option menu when the answer is already clear. ### Purpose & Context - What is this feature for? What problem does it solve? @@ -36,6 +38,7 @@ Discovery must include at least one user-answer round unless PRODUCT.md, DESIGN. - What are the realistic ranges? (Minimum, typical, maximum, e.g., 0 items, 5 items, 500 items) - What are the edge cases? (Empty state, error state, first-time use, power user) - Is any content dynamic? What changes and how often? +- What visual assets are real content here? Note required images, product shots, illustrations, maps, textures, diagrams, generated objects, or existing project assets. ### Design Direction @@ -72,9 +75,9 @@ After the discovery interview, generate a small set of visual direction probes * - The work is **net-new** or directionally ambiguous enough that visual exploration will clarify the brief. - The requested fidelity is **mid-fi, high-fi, or production-ready**. Skip for sketch-only planning. -- The current harness has **built-in image generation capability** (for example, Codex with a native image tool). Do **not** ask the user to set up external APIs, shell scripts, or one-off tooling just to do this. +- The current harness gives you native image generation (Codex's `image_gen`, an equivalent MCP tool, or similar). Don't ask the user to install APIs or tooling. -When those conditions are met, this step is mandatory for Codex and any harness with built-in image generation. Use native image generation; in Codex, use the built-in `image_gen` tool via the imagegen skill. If image generation is unavailable, do not ask the user to install APIs or tooling. State in one line that the image step is skipped because the harness lacks native image generation, then proceed. +When those conditions are met, this step is mandatory. If image generation isn't natively available, skip silently and proceed; don't announce the skip. Use probes to explore visual lanes, not to replace the brief. @@ -104,11 +107,20 @@ The probes should differ in primary visual direction (hierarchy, topology, densi - Do **not** treat generated imagery as final UX specification, final copy, or final accessibility behavior. - Do **not** use this step for minor refinements of existing work. It's for shaping a new surface or clarifying a big directional choice. -If image generation is unavailable, or the task doesn't benefit from it, skip this phase only with a one-line reason and proceed directly to the design brief. +If image generation isn't natively available, skip this phase silently and proceed. ## Phase 2: Design Brief -After the interview and any required probes, synthesize everything into a structured design brief. Present it to the user for explicit confirmation before considering this command complete. Stop after asking for confirmation; do not proceed to craft or implementation in the same response unless the user has already approved the brief. +After the interview and any required probes, present a brief and **end your response**. The user must confirm before any implementation runs. Do not present a brief and then continue to code in the same response, even if the brief feels obvious to you. The user's confirmation is the gate. + +**Choose the brief shape based on how clear the answers are:** + +- **Compact form (3-5 bullets)** when discovery was crisp and the original prompt + PRODUCT.md already pinned scope, content, and direction. State what you're building, the visual lane, and end with one or two specific questions or a clear "confirm or override?" prompt. This is the default for typical craft requests with a clear prompt. +- **Full structured form (sections below)** when the task is genuinely ambiguous, multi-screen, or when the user asked for shape as a standalone step. Use this when the discipline of structure earns its weight. + +Don't pad a clear brief into a long one to look thorough. A 70-line brief restating answers the user just gave is noise, not rigor. Equally, don't skip the confirmation pause to look efficient: the pause is the point. + +If the user already said "approved" or "go" during discovery for the *exact direction you'd present*, that counts as confirmation; you may proceed without asking again. But if your brief adds anything the user hasn't seen and approved, you must stop and confirm. ### Brief Structure @@ -136,16 +148,18 @@ List every state the feature needs: default, empty, loading, error, success, edg How users interact with this feature. What happens on click, hover, scroll? What feedback do they get? What's the flow from entry to completion? **8. Content Requirements** -What copy, labels, empty state messages, error messages, and microcopy are needed. Note any dynamic content and its realistic ranges. +What copy, labels, empty state messages, error messages, and microcopy are needed. Note any dynamic content and its realistic ranges. For image-led surfaces, also list the required image/media roles and their likely source (project asset, generated raster, semantic SVG/CSS, canvas/WebGL, icon library, or accepted omission). **9. Recommended References** Based on the brief, list which impeccable reference files would be most valuable during implementation (e.g., spatial-design.md for complex layouts, motion-design.md for animated features, interaction-design.md for form-heavy features). **10. Open Questions** -Anything unresolved that the implementer should resolve during build. +Anything genuinely unresolved. Don't list "open questions" you've already recommended a default for; assert the default and move on. If you'd write `Recommend: X` next to a question, just decide X. --- -STOP and use Codex's structured user-input/question tool when available; if unavailable, ask directly in chat to clarify what you cannot infer. Ask for explicit confirmation of the brief before finishing. If the user disagrees with any part, revisit the relevant discovery questions. A shape run is incomplete until the brief is confirmed. +STOP and use Codex's structured user-input/question tool when available; if unavailable, ask directly in chat to clarify what you cannot infer. + +If the user disagrees with any part, revisit the relevant discovery questions. A shape run is incomplete until the user confirms direction (or the user already gave a clear go during discovery, which counts). Once confirmed, the brief is complete. The user can now hand it to $impeccable, or use it to guide any other implementation approach. (If the user wants the full discovery-then-build flow in one step, they should use $impeccable craft instead, which runs this command internally.) diff --git a/.claude/skills/impeccable/SKILL.md b/.claude/skills/impeccable/SKILL.md index 5e926ac04..56dd99820 100644 --- a/.claude/skills/impeccable/SKILL.md +++ b/.claude/skills/impeccable/SKILL.md @@ -11,28 +11,15 @@ allowed-tools: Designs and iterates production-grade frontend interfaces. Real working code, committed design choices, exceptional craft. -## Setup (non-optional) +## Setup -Before any design work or file edits, pass these gates. Skipping them produces generic output that ignores the project. +Before any design work or file edits: -| 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. | +1. Load context (PRODUCT.md / DESIGN.md) via the loader script. +2. Identify the register and load the matching register reference (brand.md or product.md). +3. **If the user invoked a sub-command (e.g. `craft`, `shape`, `audit`), load its reference file too.** This is non-negotiable: `craft` without `craft.md` loaded means you'll skip the shape-and-confirm step the user expects. -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: 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. +Skipping these produces generic output that ignores the project. ### 1. Context gathering diff --git a/.claude/skills/impeccable/reference/brand.md b/.claude/skills/impeccable/reference/brand.md index b069f2553..3d83a1cdc 100644 --- a/.claude/skills/impeccable/reference/brand.md +++ b/.claude/skills/impeccable/reference/brand.md @@ -12,6 +12,8 @@ Brand isn't a neutral register. AI-generated landing pages have flooded the inte **The second slop test: aesthetic lane.** Before committing to moves, name the reference. A Klim-style specimen page is one lane; Stripe-minimal is another; Liquid-Death-acid-maximalism is another. Don't drift into editorial-magazine aesthetics on a brief that isn't editorial. A hiking brand with Cormorant italic drop caps has the wrong register within the register. +Then the inverse test: in one sentence, describe what you're about to build the way a competitor would describe theirs. If that sentence fits the modal landing page in the category, restart. + ## Typography ### Font selection procedure @@ -66,6 +68,7 @@ Brand surfaces have permission for Committed, Full palette, and Drenched strateg - Palette IS voice. A calm brand and a restless brand should not share palette mechanics. - When the strategy is Committed or Drenched, color carries the brand. Don't hedge with neutrals around the edges. Commit. - Don't converge across projects. If the last brand surface was restrained-on-cream, this one is not. +- When a cultural-symbol palette is the obvious pull, reach past it. Let the cultural reading come from typography, imagery, and copy, not the palette. ## Layout @@ -79,14 +82,14 @@ Brand surfaces have permission for Committed, Full palette, and Drenched strateg Brand surfaces lean on imagery. A restaurant, hotel, magazine, or product landing page without any imagery reads as incomplete, not as restrained. A solid-color rectangle where a hero image should go is worse than a representative stock photo. -**When the brief implies imagery (restaurants, hotels, magazines, photography, hobbyist communities, food, travel, fashion, product), you must ship imagery.** Zero images is a bug, not a design choice. "Restraint" is not an excuse. +**When the brief implies imagery (restaurants, hotels, magazines, photography, hobbyist communities, food, travel, fashion, product), you must ship imagery.** Zero images is a bug, not a design choice. "Restraint" is not an excuse. If the approved comp or brief is image-led, ship real project assets, generated raster assets, or a credible canvas/SVG/WebGL scene. Do not replace photographic, architectural, product, or place imagery with generic CSS panels, decorative diagrams, cards, bullets, or copy. -- **For greenfield work without local assets, use stock imagery.** Unsplash is the default. The URL shape is `https://images.unsplash.com/photo-{id}?auto=format&fit=crop&w=1600&q=80`. Pick real Unsplash photo IDs you're confident exist (`photo-1559339352-11d035aa65de`, `photo-1590490360182-c33d57733427`, etc.); if unsure, pick fewer photos but don't substitute colored `
` placeholders. +- **For greenfield work without local assets, use stock imagery.** Unsplash is the default. The URL shape is `https://images.unsplash.com/photo-{id}?auto=format&fit=crop&w=1600&q=80`. **Verify the URLs before referencing them.** If you have an image-search MCP, web-fetch tool, or browser access, use it to find real photo IDs and confirm they resolve. Guessed IDs (even ones that look real) often 404 and ship as broken-image placeholders. Without a verification path, pick fewer photos you're confident exist over more that you guessed; never substitute colored `
` placeholders. - **Search for the brand's physical object**, not the generic category: "handmade pasta on a scratched wooden table" beats "Italian food"; "cypress trees above a limestone hotel facade at dusk" beats "luxury hotel". - **One decisive photo beats five mediocre ones.** Hero imagery should commit to a mood; padding with more stock doesn't rescue an indecisive one. - **Alt text is part of the voice.** "Coastal fettuccine, hand-cut, served on the terrace" beats "pasta dish". -Tech / dev-tool brands are the exception where zero imagery can be correct; a developer landing page often carries its voice through typography, code samples, diagrams. Know which kind of brand you're working on. +"Imagery" here is broader than stock photography: product screenshots, custom data visualizations, generated SVG, and canvas/WebGL scenes are all imagery. Text-only pages where typography alone carries the entire visual weight are the failure mode. ## Motion @@ -102,6 +105,7 @@ Tech / dev-tool brands are the exception where zero imagery can be correct; a de - Timid palettes and average layouts. Safe = invisible. - Zero imagery on a brief that implies imagery (restaurant, hotel, food, travel, fashion, photography, hobbyist). Colored blocks where a hero photo belongs. - Defaulting to editorial-magazine aesthetics (display serif + italic + drop caps + broadsheet grid) on briefs that aren't magazine-shaped. Editorial is ONE aesthetic lane, not the default brand aesthetic. +- Repeated tiny uppercase tracked labels above every section heading. A single strong kicker can be voice; repeating it as section grammar is AI scaffolding unless it's a deliberate, named brand system. ## Brand permissions diff --git a/.claude/skills/impeccable/reference/craft.md b/.claude/skills/impeccable/reference/craft.md index bdeee0294..c0cfa7460 100644 --- a/.claude/skills/impeccable/reference/craft.md +++ b/.claude/skills/impeccable/reference/craft.md @@ -1,43 +1,41 @@ # Craft Flow -Build a feature with impeccable UX and UI quality through a structured process: shape the design, land the visual direction, build real production code, then inspect and improve in-browser until the result meets a high-end studio bar. +Build a feature with impeccable UX and UI quality: shape the design, land the visual direction, build real production code, inspect and improve in-browser until it meets a high-end studio bar. -## Build Gate +Before writing code, you need: PRODUCT.md loaded, register identified and the matching reference loaded, and a confirmed design direction for this task (either from `shape` or supplied by the user). PRODUCT.md is project context, not a task-specific brief. -Craft cannot build until all of these are true: +Treat any approved visual direction (generated mock or stated reference) as a concrete contract for composition, hierarchy, density, atmosphere, signature motifs, and distinctive visual moves. Don't let mocks replace structure, copy, accessibility, or state design. But if the live result lacks the approved direction's major ingredients, the implementation is wrong. -1. PRODUCT context is valid and current. -2. The shape design brief is explicitly confirmed by the user for this task, unless the user already provided a confirmed brief. -3. Implementation references from the brief are loaded. -4. The shape visual probe decision is recorded: generated, skipped with reason, or already resolved. -5. The north-star mock decision is recorded: generated, skipped with reason, or not applicable. +## Step 0: Project Foundation -PRODUCT.md and `teach` answers do **not** satisfy the shape gate. They are project context only. A compact self-authored brief does not satisfy the shape gate either. `shape=pass` requires a separate user response approving the shape brief or an already-confirmed brief supplied by the user. +Before shape, before code: figure out what kind of project you're working in. -Invalid image-skip reasons include: "the final implementation will be semantic HTML/CSS/SVG", "the diagram should stay editable", "a raster mock would not be used directly", or "the product is fictional." Generated probes and mocks are direction artifacts; they are not implementation assets. +Look at the working directory. Run `ls`. Check for: -## Craft Contract +- An existing framework: `astro.config.mjs/ts`, `next.config.js/ts`, `nuxt.config.ts`, `svelte.config.js`, `vite.config.js/ts`, `package.json` with framework deps, `Cargo.toml` + Leptos/Yew, `Gemfile` + Rails. **If found, use it.** Do not start a parallel build, do not introduce a second framework, do not write to `dist/` or `build/` directly. Whatever pipeline the project has, respect it. +- An existing component library or design system: `src/components/`, `app/components/`, a `tokens.css` / `theme.ts`, an `astro.config` `integrations`. Read what's there before adding to it. +- An existing icon set: `lucide-react`, `@phosphor-icons/react`, `@iconify/*`, hand-rolled SVG sprites in `assets/icons/`. **Use what's already in the project**; don't introduce a second set. -Craft is not a first pass. It is a loop with these required artifacts: +If the directory is empty (greenfield), don't pick a framework silently. Ask the user via the AskUserQuestion tool, with sensible defaults framed by the brief: -1. Confirmed design brief from `shape`. -2. Approved visual direction, from generated probes / mocks when image generation is available. -3. Mock fidelity inventory: the visible ingredients from the approved direction that must survive into code. -4. Semantic, functional implementation using the project's real stack and conventions. -5. Browser evidence across relevant viewports. -6. At least one critique-and-fix pass after the first browser inspection, unless the first pass has no material defects. +```text +What should this be built on? + - Astro (default for content-led brand sites, landing pages, marketing surfaces) + - SvelteKit / Next.js / Nuxt (when the brief implies an app surface or significant interactivity) + - Single index.html (one-shot demo, prototype, or a deliberately framework-free experiment) +``` -Do not let generated mockups replace interface structure, copy, accessibility, responsive behavior, or state design. But do treat the approved mock as a concrete visual contract for composition, hierarchy, density, atmosphere, signature motifs, image needs, and distinctive visual moves. "North star" means "preserve the important visible ingredients in semantic code," not "use it as loose mood." +Default: Astro for brand briefs, the project's existing framework for product briefs. Ask once; don't re-ask mid-task. ## Step 1: Shape the Design -Run /impeccable shape, passing along whatever feature description the user provided. +Run /impeccable shape, passing along whatever feature description the user provided. Shape is **required** for craft; it is what produces a confirmed direction. -Wait for the design brief to be fully confirmed by the user before proceeding. The brief is your blueprint, and every implementation decision should trace back to it. +Present the shape output and stop. Wait for the user to confirm, override, or course-correct before writing code. -If this craft run resumed after `teach` created PRODUCT.md, run shape now. Do not treat the teach interview, PRODUCT.md, or a summary of project context as a substitute for shape. Shape is task-specific and must cover scope, content/states, visual direction, constraints, anti-goals, probes when applicable, and explicit brief confirmation. +If the user already supplied a confirmed brief or ran shape separately, use it and skip this step. -If the user has already run /impeccable shape and has a confirmed design brief, skip this step and use the existing brief. +When the original prompt + PRODUCT.md already answer scope, content, and visual direction with no real ambiguity, the shape output can be **compact** (3-5 bullets stating what you're building and the visual lane, ending with one or two specific questions or "confirm or override"). The full 10-section structured brief is reserved for genuinely ambiguous, multi-screen, or stakeholder-heavy tasks. Don't pad a clear brief into a long one to look thorough; equally, don't skip the pause to look efficient. ## Step 2: Load References @@ -55,79 +53,60 @@ Then add references based on the brief's needs: ## Step 3: Land the Visual Direction (Capability-Gated) -Before implementation, generate high-fidelity visual comps when all of these are true: +Generate high-fidelity visual comps before implementation when all three are true: -- The work is **net-new** or visually open-ended enough that composition exploration will improve the build. -- The brief's scope is **mid-fi, high-fi, or production-ready**. -- The current harness has **built-in image generation capability** (for example, Codex with a native image tool). Do **not** ask the user to set up external APIs, shell scripts, or one-off tooling just to do this. +- The work is net-new or visually open-ended enough that composition exploration will improve the build. +- The brief's scope is mid-fi, high-fi, or production-ready. +- The harness gives you native image generation (Codex's `image_gen`, an equivalent MCP tool). Don't ask the user to set up external APIs. -When those conditions are met, this step is mandatory for **both brand and product work** in Codex and any harness with built-in image generation. Use native image generation; in Codex, use the built-in `image_gen` tool via the imagegen skill. If image generation is unavailable, do not ask the user to install APIs or tooling. State in one line that the image step is skipped because the harness lacks native image generation, then proceed. - -Do not skip this step because the eventual UI should be semantic, editable, code-native, responsive, or accessible. Those are implementation requirements, not reasons to avoid visual exploration. - -### Purpose - -Use the mock step to find a stronger visual lane than code-first generation would reliably discover on its own. The brief remains authoritative on user, purpose, content, constraints, states, and anti-goals. The mock clarifies composition, hierarchy, density, typography, and visual tone. +When met, this step is mandatory for both brand and product work. If image generation isn't available, skip silently. "The eventual UI is semantic/code-native/accessible" is not a reason to skip; those are implementation requirements, not exploration ones. ### What to generate -Generate **1 to 3** high-fidelity north-star comps based on the confirmed brief. If shape already produced direction probes, use those results as input and generate a more resolved mock from the winning lane, not another unrelated exploration. +Generate **1 to 3** high-fidelity north-star comps from the confirmed brief. If shape already produced direction probes, resolve the winning lane further, not an unrelated exploration. Comps must differ in primary visual direction, not just color. -- For brand work, push visual identity, composition, and mood aggressively. -- For product work, still push hierarchy, topology, density, and tone, but keep the comps grounded in realistic product structure and states. -- For landing pages and long-form brand surfaces, show enough of the next section or second fold to establish the system beyond the hero. - -The comps must be genuinely different in primary visual direction, not just color variants. +- Brand work: push visual identity, composition, and mood aggressively. +- Product work: push hierarchy, topology, density, tone, grounded in realistic product structure. +- Landing pages and long-form brand surfaces: show enough of the second fold to establish the system beyond the hero. ### Approval loop -Show the comps and ask what should carry forward. If the user asks for changes or the best direction is still weak, generate a focused revision before implementation. Continue until one direction is approved, or until the user explicitly delegates the choice. +Show the comps and ask what carries forward. Iterate until one direction is approved or the user delegates. If the user delegates, pick the strongest direction and explain it from the brief, not personal taste. -If the user delegates, pick the strongest direction and explain the decision using the brief, not personal taste. - -Before moving to implementation, summarize: - -- What to carry into code -- What **not** to literalize from the mock - -This summary is required before Step 4. It is the handoff between visual exploration and semantic implementation. +Before Step 4, summarize what to carry into code and what **not** to literalize from the mock. This is the handoff between visual exploration and semantic implementation. ### Mock fidelity inventory -Before building, inventory the approved mock's major visible ingredients: +Inventory the approved mock's major visible ingredients: -- Hero silhouette and dominant composition. -- Signature motifs: planets, devices, portraits, charts, route lines, insets, badges, or other memorable objects. -- Nav and primary CTA treatment. -- Section sequence visible in the mock, especially the second fold. -- Image-native content the concept depends on. -- Typography, density, color/material treatment, and motion cues. +- Hero silhouette and dominant composition +- Signature motifs (planets, devices, portraits, charts, route lines, insets, badges, etc.) +- Nav and primary CTA treatment +- Section sequence, especially the second fold +- Image-native content the concept depends on +- Typography, density, color/material treatment, motion cues -For each ingredient, decide how it will be implemented: semantic HTML/CSS/SVG, generated asset, sourced project asset, icon library, canvas/WebGL, or an explicitly accepted omission. Do not substitute a different hero composition or new visual driver after approval unless the user approves the change. +For each, decide implementation: semantic HTML/CSS/SVG, generated asset, sourced asset, icon library, canvas/WebGL, or accepted omission. Don't substitute a different hero composition or visual driver post-approval without user sign-off. -Treat the mock as a **north star**, not a screenshot to trace. Do **not** rasterize core UI text or let the mock override the confirmed brief. But if the live result lacks the mock's major visible ingredients, the implementation is wrong. +If a photographic, architectural, product, or place-led mock becomes generic CSS scenery / decorative diagrams / bullets / copy, stop and fix it. That's a broken implementation, not a harmless interpretation. + +Treat the mock as a north star, not a screenshot to trace. Don't rasterize core UI text. But if the live result lacks the mock's major ingredients, the implementation is wrong. ## Step 4: Asset Extraction (Need-Gated) -If the chosen direction includes image-native visual ingredients that would materially improve the implementation, generate them as separate assets before building. +If the approved direction needs raster assets, create them before building. Do not replace required imagery with generic cards, bullets, emoji, fake metrics, decorative CSS panels, or filler copy. -Good candidates: +Use the native asset producer (`impeccable_asset_producer` in Codex, `impeccable-asset-producer` in Claude Code) to create clean assets from the hi-fi mock and crops. If you do not have explicit permission to use agents, stop and ask: -- stickers -- badges -- seals -- tickets -- graphic labels -- textures -- abstract objects -- decorative marks -- non-semantic scene elements +```text +Asset production will work better as a scoped subagent job. Should I spawn the Impeccable asset producer subagent for this step? +``` -For travel, editorial, portfolio, venue, product showcase, entertainment, education, or any other image-led brand surface, visual assets are usually core content, not decoration. Do not ship abstract CSS panels where the approved mock or subject matter calls for real imagery, generated plates, illustrations, maps, product/object renders, or destination scenes. +Do not skip asset production or silently do it inline. Inline asset production is allowed only if the user declines subagents, the harness cannot spawn the authorized agent, or the user explicitly asks for single-thread mode. -Do **not** export assets for core UI text, navigation, body copy, or any structure that should stay semantic and editable in code. +Pass the approved mock, crop/contact-sheet paths, output directory, dimensions/formats, transparency needs, constraints, and avoid list to the asset producer. Attach image generation capability to the spawned agent when the harness supports it; do not load image-generation reference material into the parent thread first. -Usually **1 to 5** extracted assets is enough. If the design can be built cleanly in HTML/CSS/SVG, prefer that over raster assets. If the mock contains major visual content that cannot be built credibly in code, asset extraction is not optional. +Prefer HTML/CSS/SVG/canvas when they can credibly reproduce an ingredient; use real/generated/stock imagery when the mock or subject matter calls for actual visual content. ## Step 5: Build to Production Quality @@ -135,50 +114,35 @@ Implement the feature following the design brief. Build in passes so structure, ### Production bar -- Use real or realistic content. Remove placeholder copy, placeholder images, dead links, fake controls, and unused scaffold before presenting. -- Preserve the approved mock's major ingredients. Missing hero objects, missing world/product imagery, different section structure, downgraded CTA/nav treatment, or generic replacements for distinctive motifs are blocking defects unless the user accepted the change. -- Build semantically first: real headings, landmarks, labels, form associations, button/link semantics, accessible names, and state announcements where needed. -- Calibrate spacing, alignment, grid placement, and vertical rhythm deliberately. Do not accept default gaps, arbitrary margins, unbalanced whitespace, or accidental optical misalignment. -- Make typography intentional: chosen font loading strategy, clear hierarchy, readable measure, stable line breaks, tuned wrapping, and no overflow at mobile or large desktop sizes. -- Design realistic state coverage: default, hover where supported, focus-visible, active, disabled, loading, error, success, empty, overflow, long text, short text, and first-run states where relevant. -- Make interaction quality feel finished: keyboard paths, touch targets, feedback timing, scroll behavior, transitions between states, and no hover-only functionality. -- Use icons from the project's established icon set when available. If no set exists, choose a coherent library or use accessible text controls; do not mix unrelated icon styles. -- Optimize imagery and media: correct dimensions, useful alt text, lazy loading below the fold, modern formats when practical, responsive `srcset` / `picture` for raster assets, and no project-referenced asset left outside the workspace. -- Make motion feel premium: use atmospheric blur, filter, mask, shadow, or reveal effects when they improve the experience; avoid casual layout-property animation, bound expensive effects, verify smoothness in-browser, respect reduced motion, and avoid choreography that blocks task completion. -- Preserve maintainability: reusable local patterns, clear component boundaries, project conventions, no rasterized UI text, and no hard-coded one-off hacks when a better local pattern exists. -- Fit the technical context: production build passes, no obvious console errors, no avoidable layout shift, no needless dependency, and no broken asset path. -- If you discover a design question that materially changes the brief or approved direction, stop and ask rather than guessing. +- **Real content.** No placeholder copy, placeholder images, dead links, fake controls, or unused scaffold at presentation time. +- **Preserve the approved mock's major ingredients.** Missing hero objects, world/product imagery, section structure, CTA/nav treatment, or distinctive motifs are blocking defects unless the user accepted the change. +- **Semantic first.** Real headings, landmarks, labels, form associations, button/link semantics, accessible names, state announcements where needed. +- **Deliberate spacing and alignment.** No default gaps, arbitrary margins, unbalanced whitespace, or accidental optical misalignment. +- **Intentional typography.** Chosen loading strategy, clear hierarchy, readable measure, stable line breaks, no overflow at any width. +- **Realistic state coverage.** Default, hover, focus-visible, active, disabled, loading, error, success, empty, overflow, long/short text, first-run. +- **Finished interaction quality.** Keyboard paths, touch targets, feedback timing, scroll behavior, state transitions, no hover-only functionality. +- **Coherent icon set.** Use the project's established set; otherwise pick one library or use accessible text. Don't mix. +- **Respect the build pipeline.** Edit source files and run the project's build (`npm run build` or equivalent). Don't write to `build/` / `dist/` / `.next/` with `cat`, heredoc, or Bash redirects; that skips asset hashing, image optimization, code splitting, and CSS extraction, and produces output the dev server won't serve. +- **Verify image URLs before referencing them.** Use image-search MCP or web-fetch when available; guessed photo IDs ship as broken-image placeholders. Without verification, prefer fewer images you're confident about. +- **Optimized imagery and media.** Correct dimensions, useful alt text, lazy loading below the fold, modern formats when practical, responsive `srcset`/`picture` for raster, no project-referenced asset left outside the workspace. +- **Premium motion.** Use atmospheric blur, filter, mask, shadow, reveal when they improve the experience. Avoid casual layout-property animation, bound expensive effects, verify smoothness in-browser, respect reduced motion, and avoid choreography that blocks task completion. +- **Maintainable.** Reusable local patterns, clear component boundaries, project conventions. No rasterized UI text or one-off hacks when a local pattern exists. +- **Technically clean.** Production build passes, no console errors, no avoidable layout shift, no needless dependencies, no broken asset paths. +- **Ask when uncertain.** If a discovery materially changes the brief or approved direction, stop and ask. Don't guess. -## Step 6: Browser-Based Iteration +## Step 6: Iterate Visually -**This step is critical.** Do not stop after the first implementation pass. +Look at what you built like a designer would. Your eyes are whatever the harness gives you: a connected browser, a screenshotting tool, Playwright, or asking the user. Use them for responsive testing (mobile, tablet, desktop minimum) and general visual validation. -Open the result in a browser. In Codex, use browser-use or equivalent browser automation when available; otherwise use Playwright or ask the user for screenshots. Inspect screenshots, not just DOM or terminal output. +If your tool returns a file path, read the PNG back into the conversation. A screenshot you didn't read doesn't count. -### Required viewport pass +For long-form brand surfaces, inspect major sections individually. Thumbnails hide spacing, clipping, and cascade defects. -Check the experience at the viewports that matter for the brief. Default minimum: +After the first pass, write an honest critique against the brief, the approved mock's major ingredients (hero silhouette, motifs, imagery, nav/CTA, density), and impeccable's DON'Ts. Patch material defects and re-inspect. **Don't invent defects to demonstrate iteration.** A confident "first pass clean, shipping" beats a fake fix. -- Mobile narrow -- Tablet or small laptop -- Desktop wide +Actively check: responsive behavior (composes, not shrinks), every state (empty / error / loading / edge), craft details (spacing, alignment, hierarchy, contrast, motion timing, focus), performance basics. The exit bar: defensible in a high-end studio review. -For each viewport, capture or inspect the rendered state and look for visual defects: overlap, clipping, weak hierarchy, off-grid alignment, awkward whitespace, cramped controls, unreadable type, broken imagery, hover-only functionality, layout shift, and text overflow. - -### Critique and fix loop - -After the first browser pass, write a short critique for yourself and patch the implementation. Repeat browser inspection after fixes. Continue until no material issues remain against this checklist: - -1. **Does it match the brief?** Compare the live result against every section of the design brief. Fix discrepancies. -2. **Does it match the approved mock?** Compare screenshots against the mock fidelity inventory: hero silhouette, major motifs, imagery, nav/CTA, section sequence, density, color/materials, and second-fold substance. Missing major ingredients are P0 defects. -3. **Does it pass the AI slop test?** If someone saw this and said "AI made this," would they believe it immediately? If yes, it needs more design intention. -4. **Check against impeccable's DON'T guidelines.** Fix any anti-pattern violations. -5. **Check every state.** Navigate through empty, error, loading, and edge case states. Each one should feel intentional, not like an afterthought. -6. **Check responsive behavior.** The design should adapt compositionally, not merely shrink. -7. **Check craft details.** Spacing consistency, optical alignment, type hierarchy, color contrast, image quality, icon coherence, interactive feedback, motion timing, and focus treatment. -8. **Check performance basics.** No obviously oversized images, avoidable layout thrash, blocking animations, or heavy assets without a reason. - -The exit bar is not "it works." It is: the rendered result looks intentional at all checked viewports, all expected states are handled, no placeholders remain unless explicitly accepted, and the implementation quality would be defensible in a high-end studio review. +Detector or QA output is defect evidence only; never proof the work is finished. ## Step 7: Present @@ -189,5 +153,3 @@ Present the result to the user: - Explain design decisions that connect back to the design brief and, when used, the chosen north-star mock. Include any accepted deviations from the mock; do not hide unimplemented mock ingredients. - Note any remaining limitations or follow-up risks honestly - Ask: "What's working? What isn't?" - -Iterate based on feedback. Good design is rarely right on the first pass. diff --git a/.claude/skills/impeccable/reference/critique.md b/.claude/skills/impeccable/reference/critique.md index 18f855e62..fddf20f11 100644 --- a/.claude/skills/impeccable/reference/critique.md +++ b/.claude/skills/impeccable/reference/critique.md @@ -43,7 +43,7 @@ Run the bundled deterministic detector, which flags 27 specific patterns (AI slo **CLI scan**: ```bash -npx impeccable --json [--fast] [target] +npx impeccable detect --json [--fast] [target] ``` - Pass HTML/JSX/TSX/Vue/Svelte files or directories as `[target]` (anything with markup). Do not pass CSS-only files. diff --git a/.claude/skills/impeccable/reference/polish.md b/.claude/skills/impeccable/reference/polish.md index a2a409e48..eed3dbd27 100644 --- a/.claude/skills/impeccable/reference/polish.md +++ b/.claude/skills/impeccable/reference/polish.md @@ -2,6 +2,8 @@ Perform a meticulous final pass to catch all the small details that separate good work from great work. The difference between shipped and polished. +Detector and automated QA output are defect evidence only. A clean script result is never proof that the design is strong; gather browser evidence and inspect the real interaction path. + ## Design System Discovery Aligning the feature to the design system is **not optional**. Polish without alignment is decoration on top of drift, and it makes the next person's job harder. Discovery comes before any other polish work. @@ -216,11 +218,12 @@ Sweat the details. Zoom in until the alignment is right and the spacing reads as Before marking as done: -- **Use it yourself**: Actually interact with the feature -- **Test on real devices**: Not just browser DevTools -- **Ask someone else to review**: Fresh eyes catch things -- **Compare to design**: Match intended design -- **Check all states**: Don't just test happy path +- **Use it yourself**: Actually interact with the feature. +- **Test on real devices**: Not just browser DevTools. +- **Ask someone else to review**: Fresh eyes catch things. +- **Compare to design**: Match intended design. +- **Check all states**: Don't just test happy path. +- **Treat automation carefully**: Run detector or QA commands when they are available and relevant, fix their defects, but never cite a clean result as proof that the work is polished. ## Clean Up @@ -230,4 +233,3 @@ After polishing, ensure code quality: - **Remove orphaned code**: Delete unused styles, components, or files made obsolete by polish. - **Consolidate tokens**: If you introduced new values, check whether they should be tokens. - **Verify DRYness**: Look for duplication introduced during polishing and consolidate. - diff --git a/.claude/skills/impeccable/reference/shape.md b/.claude/skills/impeccable/reference/shape.md index 756631825..60348d482 100644 --- a/.claude/skills/impeccable/reference/shape.md +++ b/.claude/skills/impeccable/reference/shape.md @@ -16,14 +16,16 @@ This is a required interaction, not optional guidance. Ask these questions in co ### Interview cadence -Discovery must include at least one user-answer round unless PRODUCT.md, DESIGN.md, or an already-confirmed brief directly answers the needed design inputs. With a sparse prompt, do **not** synthesize a complete brief for confirmation on the first response. +Discovery includes at least one user-answer round unless PRODUCT.md, DESIGN.md, or an already-confirmed brief directly answers the needed inputs. With a sparse prompt, do **not** synthesize a complete brief for confirmation on the first response. - Use the harness's structured question tool when one exists. Otherwise, ask directly in chat and stop. - Ask **2-3 questions per round**, then wait for answers. - Treat PRODUCT.md and DESIGN.md as anchors; they reduce repeated questions but do **not** replace shape for craft. Shape is task-specific. -- Round 1 should clarify purpose, audience/context, and success or emotional outcome. -- Round 2 should clarify content/data/states and scope/fidelity. -- Round 3 should clarify visual direction, constraints, and anti-goals when still unresolved. +- One round is the default. Add a second only if the first answers leave material gaps. Don't run a second round just to feel thorough. +- Round 1 should clarify purpose, audience/context, content/scope, and (for brand) visual direction. +- Round 2, when needed, fills in whatever's still genuinely missing. + +**Assert-then-confirm, not menu-with-escape.** When PRODUCT.md and the user's prompt make one option obvious, name it and ask the user to confirm or override. Don't enumerate "Restrained / Committed / Or something else?" as a real choice; "This reads as Restrained, confirm?" beats a four-option menu when the answer is already clear. ### Purpose & Context - What is this feature for? What problem does it solve? @@ -36,6 +38,7 @@ Discovery must include at least one user-answer round unless PRODUCT.md, DESIGN. - What are the realistic ranges? (Minimum, typical, maximum, e.g., 0 items, 5 items, 500 items) - What are the edge cases? (Empty state, error state, first-time use, power user) - Is any content dynamic? What changes and how often? +- What visual assets are real content here? Note required images, product shots, illustrations, maps, textures, diagrams, generated objects, or existing project assets. ### Design Direction @@ -72,9 +75,9 @@ After the discovery interview, generate a small set of visual direction probes * - The work is **net-new** or directionally ambiguous enough that visual exploration will clarify the brief. - The requested fidelity is **mid-fi, high-fi, or production-ready**. Skip for sketch-only planning. -- The current harness has **built-in image generation capability** (for example, Codex with a native image tool). Do **not** ask the user to set up external APIs, shell scripts, or one-off tooling just to do this. +- The current harness gives you native image generation (Codex's `image_gen`, an equivalent MCP tool, or similar). Don't ask the user to install APIs or tooling. -When those conditions are met, this step is mandatory for Codex and any harness with built-in image generation. Use native image generation; in Codex, use the built-in `image_gen` tool via the imagegen skill. If image generation is unavailable, do not ask the user to install APIs or tooling. State in one line that the image step is skipped because the harness lacks native image generation, then proceed. +When those conditions are met, this step is mandatory. If image generation isn't natively available, skip silently and proceed; don't announce the skip. Use probes to explore visual lanes, not to replace the brief. @@ -104,11 +107,20 @@ The probes should differ in primary visual direction (hierarchy, topology, densi - Do **not** treat generated imagery as final UX specification, final copy, or final accessibility behavior. - Do **not** use this step for minor refinements of existing work. It's for shaping a new surface or clarifying a big directional choice. -If image generation is unavailable, or the task doesn't benefit from it, skip this phase only with a one-line reason and proceed directly to the design brief. +If image generation isn't natively available, skip this phase silently and proceed. ## Phase 2: Design Brief -After the interview and any required probes, synthesize everything into a structured design brief. Present it to the user for explicit confirmation before considering this command complete. Stop after asking for confirmation; do not proceed to craft or implementation in the same response unless the user has already approved the brief. +After the interview and any required probes, present a brief and **end your response**. The user must confirm before any implementation runs. Do not present a brief and then continue to code in the same response, even if the brief feels obvious to you. The user's confirmation is the gate. + +**Choose the brief shape based on how clear the answers are:** + +- **Compact form (3-5 bullets)** when discovery was crisp and the original prompt + PRODUCT.md already pinned scope, content, and direction. State what you're building, the visual lane, and end with one or two specific questions or a clear "confirm or override?" prompt. This is the default for typical craft requests with a clear prompt. +- **Full structured form (sections below)** when the task is genuinely ambiguous, multi-screen, or when the user asked for shape as a standalone step. Use this when the discipline of structure earns its weight. + +Don't pad a clear brief into a long one to look thorough. A 70-line brief restating answers the user just gave is noise, not rigor. Equally, don't skip the confirmation pause to look efficient: the pause is the point. + +If the user already said "approved" or "go" during discovery for the *exact direction you'd present*, that counts as confirmation; you may proceed without asking again. But if your brief adds anything the user hasn't seen and approved, you must stop and confirm. ### Brief Structure @@ -136,16 +148,18 @@ List every state the feature needs: default, empty, loading, error, success, edg How users interact with this feature. What happens on click, hover, scroll? What feedback do they get? What's the flow from entry to completion? **8. Content Requirements** -What copy, labels, empty state messages, error messages, and microcopy are needed. Note any dynamic content and its realistic ranges. +What copy, labels, empty state messages, error messages, and microcopy are needed. Note any dynamic content and its realistic ranges. For image-led surfaces, also list the required image/media roles and their likely source (project asset, generated raster, semantic SVG/CSS, canvas/WebGL, icon library, or accepted omission). **9. Recommended References** Based on the brief, list which impeccable reference files would be most valuable during implementation (e.g., spatial-design.md for complex layouts, motion-design.md for animated features, interaction-design.md for form-heavy features). **10. Open Questions** -Anything unresolved that the implementer should resolve during build. +Anything genuinely unresolved. Don't list "open questions" you've already recommended a default for; assert the default and move on. If you'd write `Recommend: X` next to a question, just decide X. --- -STOP and call the AskUserQuestion tool to clarify. Ask for explicit confirmation of the brief before finishing. If the user disagrees with any part, revisit the relevant discovery questions. A shape run is incomplete until the brief is confirmed. +STOP and call the AskUserQuestion tool to clarify. + +If the user disagrees with any part, revisit the relevant discovery questions. A shape run is incomplete until the user confirms direction (or the user already gave a clear go during discovery, which counts). Once confirmed, the brief is complete. The user can now hand it to /impeccable, or use it to guide any other implementation approach. (If the user wants the full discovery-then-build flow in one step, they should use /impeccable craft instead, which runs this command internally.) diff --git a/.codex/agents/impeccable_asset_producer.toml b/.codex/agents/impeccable_asset_producer.toml new file mode 100644 index 000000000..2419f3ec6 --- /dev/null +++ b/.codex/agents/impeccable_asset_producer.toml @@ -0,0 +1,92 @@ +name = "impeccable_asset_producer" +description = "Produces clean reusable raster assets from approved Impeccable mock references without redesigning the direction." +model_reasoning_effort = "medium" +nickname_candidates = ["Asset Plate", "Clean Plate", "Crop Cutter"] +developer_instructions = ''' +# Impeccable Asset Producer + +You are the asset production agent for Impeccable craft. + +Your job is production cleanup, not new art direction. Work only from the approved mock, assigned crops, contact sheets, and constraints the parent agent gives you. The assets you create will be used to build a real site, so treat every raster as a raw ingredient that HTML, CSS, SVG, canvas, and component code will compose. + +## Core Rule + +Do not redesign. Preserve the reference's visual role, silhouette, palette, lighting, material, texture, camera angle, and composition unless the parent explicitly asks for a change. Preserve perspective only when it belongs to the object or scene itself; if CSS should create the card transform, shadow, rounded clipping, border, or layout, remove that presentation chrome from the raster. + +## Input Contract + +Expect: + +- Approved mock path or screenshot reference. +- Crop paths or a contact sheet with crop ids. +- Output directory. +- Required dimensions, format, transparency needs, and avoid list. +- Notes on what should remain semantic HTML/CSS/SVG instead of raster. + +If the source mock is attached but has no filesystem path, use it for visual planning. Ask for a path only before cropping or writing assets. + +Use defaults unless contradicted: + +- `.webp` for opaque photos, backgrounds, and textures. +- `.png` for transparent cutouts, seals, tickets, and illustrations. +- Target production size or at least 2x display size when dimensions are known. Do not use small full-page mock crop size as the default shipping size. +- Remove UI text, navigation, buttons, labels, and body copy by default. +- Keep physical marks only when the parent says they are part of the asset. +- Remove letterboxing, empty padding, baked card corners, borders, shadows, caption bands, and layout background unless the parent says those pixels are intrinsic to the asset. +- Keep the final assets directory clean: only files the build will consume belong there. Put source crops, reference crops, masks, and contact sheets in a sibling `_sources`, `sources`, or review folder. + +Ask blockers once, globally. Missing source path/crops or output directory blocks production. Exact dimensions, compression targets, retina variants, and format preferences do not block; choose defaults and report them. + +## Workflow + +1. Inventory the full approved mock or every assigned crop. +2. Put each visual role in exactly one bucket: + - `produce`: needs generation, image editing, cleanup, cutout work, or a clean plate before it can ship. + - `direct`: can ship as a crop, format conversion, compression pass, or sourced replacement with no generative cleanup. + - `semantic`: build in HTML/CSS/SVG/canvas, no raster output. +3. Treat full-page mock crops as references, not production-resolution source assets. Put a role in `direct` only when the provided source is already a clean, sufficiently large source asset with no semantic text or presentation chrome. +4. Give the parent an execution order for the `produce` bucket. +5. For produced assets, choose the least inventive strategy: image-to-image clean plate, faithful regeneration from crop reference, transparent cutout, texture/pattern reconstruction, stock/project source, or semantic HTML/CSS/SVG recommendation if raster is wrong. +6. Treat every crop as binding reference. In Codex, use the imagegen skill and built-in `image_gen` path by default when generation or editing is needed. +7. Remove baked-in UI text, navigation, buttons, body copy, and mock chrome unless the text is part of the asset. +8. Think through the final DOM/CSS representation before generating. If CSS will own radius, clipping, shadows, borders, perspective, responsive cropping, captions, or card frames, do not bake those into the bitmap. +9. Save outputs non-destructively in the requested project directory. +10. Compare each output against its source crop. If a review/QA tool is available, run it before the final manifest, then retry each major/fatal finding once before finalizing. + +Use `direct` only for provided source assets that can already ship after crop tightening, conversion, compression, or naming. Do not ship a small crop from the full-page mock as `direct` just because it looks close. + +Use `texture/pattern extraction` only when the source region is already clean enough to sample as texture. If UI, cards, labels, headings, body copy, or footer chrome must be removed to make a reusable texture or background, classify it as crop-derived cleanup or clean-plate work. + +Use `semantic` for dashboards, charts, controls, screenshots of whole UI sections, data widgets, card chrome, app frames, icon toolbars, logos, wordmarks, and anything the final implementation can render crisply in HTML/CSS/SVG/canvas. Only ship a screenshot raster when the parent explicitly says the screenshot itself is the final asset. + +Semantic does not mean ignored. For every semantic role, write a concrete implementation handoff for the parent craft agent: name the DOM/component layers, CSS-owned visual treatment, SVG/canvas/icon-library pieces, responsive behavior, and which nearby produced raster assets it should compose with. For logos and icons, prefer inline SVG/vector or icon-library implementation unless the parent provides a production logo raster. + +For transparency, prefer true alpha output when the tool supports it. If it does not, request a flat chroma-key background in a color that cannot appear in the subject, then post-process that color to alpha before shipping a PNG/WebP. Do not ship the keyed background as the final asset. + +## Prompt Pattern + +Use this shape for image-to-image work: + +```text +Use the provided crop as the approved visual reference. +Recreate the same asset as a clean reusable production image at the target component aspect ratio and at least 2x display resolution. +Preserve silhouette, object/scene perspective, camera angle, palette, lighting, material, texture, and visual role. +Remove baked-in UI copy, navigation, buttons, labels, body text, watermarks, and mock chrome unless explicitly part of the asset. +Remove letterboxing, padding, card borders, rounded clipping, CSS shadows, perspective transforms, caption bands, and layout backgrounds that the implementation should create in code. +Do not add new objects. Do not change the concept. Do not redesign the composition. +``` + +For transparent cutouts, use the imagegen skill's built-in-first chroma-key workflow unless the parent explicitly authorizes a true native transparency fallback. + +## Output Contract + +Return a complete manifest, grouped by `produce`, `direct`, and `semantic`. For each asset include: `id`, `source_crop`, `output_path` when applicable, `strategy`, `prompt_used` when applicable, `dimensions`, `format`, `transparency`, `deviations`, and `qa_status`. + +For each semantic row include `id`, `implementation`, `notes`, and `qa_status`. The `implementation` must be a concrete build handoff, not a short explanation that no asset was produced. It should name the likely HTML/CSS/SVG/canvas/icon/component pieces and the visual responsibilities that code owns. + +`qa_status` must be `accepted`, `needs_parent_review`, or `blocked`. Use `accepted` only after visual comparison passes. Use `needs_parent_review` for cut-off subjects, unwanted borders or rounded-card chrome, letterboxing, baked semantic text, low-resolution output, perspective that should have been CSS, missing transparency, or drift from the crop. Use `blocked` when inputs, permissions, image capability, or asset source quality prevent a credible result. + +End with `execution_order`, `blockers`, and `assumptions` sections. Keep blockers global and minimal. Do not repeat missing inputs in every row; per-asset rows should carry only asset-specific risks or decisions. + +Do not modify implementation code. Do not edit the approved mock. Do not produce final page copy. The parent craft agent owns implementation and final mock fidelity. +''' diff --git a/.cursor/skills/impeccable/SKILL.md b/.cursor/skills/impeccable/SKILL.md index df15564ab..39f9c9709 100644 --- a/.cursor/skills/impeccable/SKILL.md +++ b/.cursor/skills/impeccable/SKILL.md @@ -7,28 +7,15 @@ license: Apache 2.0. Based on Anthropic's frontend-design skill. See NOTICE.md f Designs and iterates production-grade frontend interfaces. Real working code, committed design choices, exceptional craft. -## Setup (non-optional) +## Setup -Before any design work or file edits, pass these gates. Skipping them produces generic output that ignores the project. +Before any design work or file edits: -| 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. | +1. Load context (PRODUCT.md / DESIGN.md) via the loader script. +2. Identify the register and load the matching register reference (brand.md or product.md). +3. **If the user invoked a sub-command (e.g. `craft`, `shape`, `audit`), load its reference file too.** This is non-negotiable: `craft` without `craft.md` loaded means you'll skip the shape-and-confirm step the user expects. -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: 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. +Skipping these produces generic output that ignores the project. ### 1. Context gathering diff --git a/.cursor/skills/impeccable/reference/brand.md b/.cursor/skills/impeccable/reference/brand.md index b069f2553..3d83a1cdc 100644 --- a/.cursor/skills/impeccable/reference/brand.md +++ b/.cursor/skills/impeccable/reference/brand.md @@ -12,6 +12,8 @@ Brand isn't a neutral register. AI-generated landing pages have flooded the inte **The second slop test: aesthetic lane.** Before committing to moves, name the reference. A Klim-style specimen page is one lane; Stripe-minimal is another; Liquid-Death-acid-maximalism is another. Don't drift into editorial-magazine aesthetics on a brief that isn't editorial. A hiking brand with Cormorant italic drop caps has the wrong register within the register. +Then the inverse test: in one sentence, describe what you're about to build the way a competitor would describe theirs. If that sentence fits the modal landing page in the category, restart. + ## Typography ### Font selection procedure @@ -66,6 +68,7 @@ Brand surfaces have permission for Committed, Full palette, and Drenched strateg - Palette IS voice. A calm brand and a restless brand should not share palette mechanics. - When the strategy is Committed or Drenched, color carries the brand. Don't hedge with neutrals around the edges. Commit. - Don't converge across projects. If the last brand surface was restrained-on-cream, this one is not. +- When a cultural-symbol palette is the obvious pull, reach past it. Let the cultural reading come from typography, imagery, and copy, not the palette. ## Layout @@ -79,14 +82,14 @@ Brand surfaces have permission for Committed, Full palette, and Drenched strateg Brand surfaces lean on imagery. A restaurant, hotel, magazine, or product landing page without any imagery reads as incomplete, not as restrained. A solid-color rectangle where a hero image should go is worse than a representative stock photo. -**When the brief implies imagery (restaurants, hotels, magazines, photography, hobbyist communities, food, travel, fashion, product), you must ship imagery.** Zero images is a bug, not a design choice. "Restraint" is not an excuse. +**When the brief implies imagery (restaurants, hotels, magazines, photography, hobbyist communities, food, travel, fashion, product), you must ship imagery.** Zero images is a bug, not a design choice. "Restraint" is not an excuse. If the approved comp or brief is image-led, ship real project assets, generated raster assets, or a credible canvas/SVG/WebGL scene. Do not replace photographic, architectural, product, or place imagery with generic CSS panels, decorative diagrams, cards, bullets, or copy. -- **For greenfield work without local assets, use stock imagery.** Unsplash is the default. The URL shape is `https://images.unsplash.com/photo-{id}?auto=format&fit=crop&w=1600&q=80`. Pick real Unsplash photo IDs you're confident exist (`photo-1559339352-11d035aa65de`, `photo-1590490360182-c33d57733427`, etc.); if unsure, pick fewer photos but don't substitute colored `
` placeholders. +- **For greenfield work without local assets, use stock imagery.** Unsplash is the default. The URL shape is `https://images.unsplash.com/photo-{id}?auto=format&fit=crop&w=1600&q=80`. **Verify the URLs before referencing them.** If you have an image-search MCP, web-fetch tool, or browser access, use it to find real photo IDs and confirm they resolve. Guessed IDs (even ones that look real) often 404 and ship as broken-image placeholders. Without a verification path, pick fewer photos you're confident exist over more that you guessed; never substitute colored `
` placeholders. - **Search for the brand's physical object**, not the generic category: "handmade pasta on a scratched wooden table" beats "Italian food"; "cypress trees above a limestone hotel facade at dusk" beats "luxury hotel". - **One decisive photo beats five mediocre ones.** Hero imagery should commit to a mood; padding with more stock doesn't rescue an indecisive one. - **Alt text is part of the voice.** "Coastal fettuccine, hand-cut, served on the terrace" beats "pasta dish". -Tech / dev-tool brands are the exception where zero imagery can be correct; a developer landing page often carries its voice through typography, code samples, diagrams. Know which kind of brand you're working on. +"Imagery" here is broader than stock photography: product screenshots, custom data visualizations, generated SVG, and canvas/WebGL scenes are all imagery. Text-only pages where typography alone carries the entire visual weight are the failure mode. ## Motion @@ -102,6 +105,7 @@ Tech / dev-tool brands are the exception where zero imagery can be correct; a de - Timid palettes and average layouts. Safe = invisible. - Zero imagery on a brief that implies imagery (restaurant, hotel, food, travel, fashion, photography, hobbyist). Colored blocks where a hero photo belongs. - Defaulting to editorial-magazine aesthetics (display serif + italic + drop caps + broadsheet grid) on briefs that aren't magazine-shaped. Editorial is ONE aesthetic lane, not the default brand aesthetic. +- Repeated tiny uppercase tracked labels above every section heading. A single strong kicker can be voice; repeating it as section grammar is AI scaffolding unless it's a deliberate, named brand system. ## Brand permissions diff --git a/.cursor/skills/impeccable/reference/craft.md b/.cursor/skills/impeccable/reference/craft.md index bdeee0294..c0cfa7460 100644 --- a/.cursor/skills/impeccable/reference/craft.md +++ b/.cursor/skills/impeccable/reference/craft.md @@ -1,43 +1,41 @@ # Craft Flow -Build a feature with impeccable UX and UI quality through a structured process: shape the design, land the visual direction, build real production code, then inspect and improve in-browser until the result meets a high-end studio bar. +Build a feature with impeccable UX and UI quality: shape the design, land the visual direction, build real production code, inspect and improve in-browser until it meets a high-end studio bar. -## Build Gate +Before writing code, you need: PRODUCT.md loaded, register identified and the matching reference loaded, and a confirmed design direction for this task (either from `shape` or supplied by the user). PRODUCT.md is project context, not a task-specific brief. -Craft cannot build until all of these are true: +Treat any approved visual direction (generated mock or stated reference) as a concrete contract for composition, hierarchy, density, atmosphere, signature motifs, and distinctive visual moves. Don't let mocks replace structure, copy, accessibility, or state design. But if the live result lacks the approved direction's major ingredients, the implementation is wrong. -1. PRODUCT context is valid and current. -2. The shape design brief is explicitly confirmed by the user for this task, unless the user already provided a confirmed brief. -3. Implementation references from the brief are loaded. -4. The shape visual probe decision is recorded: generated, skipped with reason, or already resolved. -5. The north-star mock decision is recorded: generated, skipped with reason, or not applicable. +## Step 0: Project Foundation -PRODUCT.md and `teach` answers do **not** satisfy the shape gate. They are project context only. A compact self-authored brief does not satisfy the shape gate either. `shape=pass` requires a separate user response approving the shape brief or an already-confirmed brief supplied by the user. +Before shape, before code: figure out what kind of project you're working in. -Invalid image-skip reasons include: "the final implementation will be semantic HTML/CSS/SVG", "the diagram should stay editable", "a raster mock would not be used directly", or "the product is fictional." Generated probes and mocks are direction artifacts; they are not implementation assets. +Look at the working directory. Run `ls`. Check for: -## Craft Contract +- An existing framework: `astro.config.mjs/ts`, `next.config.js/ts`, `nuxt.config.ts`, `svelte.config.js`, `vite.config.js/ts`, `package.json` with framework deps, `Cargo.toml` + Leptos/Yew, `Gemfile` + Rails. **If found, use it.** Do not start a parallel build, do not introduce a second framework, do not write to `dist/` or `build/` directly. Whatever pipeline the project has, respect it. +- An existing component library or design system: `src/components/`, `app/components/`, a `tokens.css` / `theme.ts`, an `astro.config` `integrations`. Read what's there before adding to it. +- An existing icon set: `lucide-react`, `@phosphor-icons/react`, `@iconify/*`, hand-rolled SVG sprites in `assets/icons/`. **Use what's already in the project**; don't introduce a second set. -Craft is not a first pass. It is a loop with these required artifacts: +If the directory is empty (greenfield), don't pick a framework silently. Ask the user via the AskUserQuestion tool, with sensible defaults framed by the brief: -1. Confirmed design brief from `shape`. -2. Approved visual direction, from generated probes / mocks when image generation is available. -3. Mock fidelity inventory: the visible ingredients from the approved direction that must survive into code. -4. Semantic, functional implementation using the project's real stack and conventions. -5. Browser evidence across relevant viewports. -6. At least one critique-and-fix pass after the first browser inspection, unless the first pass has no material defects. +```text +What should this be built on? + - Astro (default for content-led brand sites, landing pages, marketing surfaces) + - SvelteKit / Next.js / Nuxt (when the brief implies an app surface or significant interactivity) + - Single index.html (one-shot demo, prototype, or a deliberately framework-free experiment) +``` -Do not let generated mockups replace interface structure, copy, accessibility, responsive behavior, or state design. But do treat the approved mock as a concrete visual contract for composition, hierarchy, density, atmosphere, signature motifs, image needs, and distinctive visual moves. "North star" means "preserve the important visible ingredients in semantic code," not "use it as loose mood." +Default: Astro for brand briefs, the project's existing framework for product briefs. Ask once; don't re-ask mid-task. ## Step 1: Shape the Design -Run /impeccable shape, passing along whatever feature description the user provided. +Run /impeccable shape, passing along whatever feature description the user provided. Shape is **required** for craft; it is what produces a confirmed direction. -Wait for the design brief to be fully confirmed by the user before proceeding. The brief is your blueprint, and every implementation decision should trace back to it. +Present the shape output and stop. Wait for the user to confirm, override, or course-correct before writing code. -If this craft run resumed after `teach` created PRODUCT.md, run shape now. Do not treat the teach interview, PRODUCT.md, or a summary of project context as a substitute for shape. Shape is task-specific and must cover scope, content/states, visual direction, constraints, anti-goals, probes when applicable, and explicit brief confirmation. +If the user already supplied a confirmed brief or ran shape separately, use it and skip this step. -If the user has already run /impeccable shape and has a confirmed design brief, skip this step and use the existing brief. +When the original prompt + PRODUCT.md already answer scope, content, and visual direction with no real ambiguity, the shape output can be **compact** (3-5 bullets stating what you're building and the visual lane, ending with one or two specific questions or "confirm or override"). The full 10-section structured brief is reserved for genuinely ambiguous, multi-screen, or stakeholder-heavy tasks. Don't pad a clear brief into a long one to look thorough; equally, don't skip the pause to look efficient. ## Step 2: Load References @@ -55,79 +53,60 @@ Then add references based on the brief's needs: ## Step 3: Land the Visual Direction (Capability-Gated) -Before implementation, generate high-fidelity visual comps when all of these are true: +Generate high-fidelity visual comps before implementation when all three are true: -- The work is **net-new** or visually open-ended enough that composition exploration will improve the build. -- The brief's scope is **mid-fi, high-fi, or production-ready**. -- The current harness has **built-in image generation capability** (for example, Codex with a native image tool). Do **not** ask the user to set up external APIs, shell scripts, or one-off tooling just to do this. +- The work is net-new or visually open-ended enough that composition exploration will improve the build. +- The brief's scope is mid-fi, high-fi, or production-ready. +- The harness gives you native image generation (Codex's `image_gen`, an equivalent MCP tool). Don't ask the user to set up external APIs. -When those conditions are met, this step is mandatory for **both brand and product work** in Codex and any harness with built-in image generation. Use native image generation; in Codex, use the built-in `image_gen` tool via the imagegen skill. If image generation is unavailable, do not ask the user to install APIs or tooling. State in one line that the image step is skipped because the harness lacks native image generation, then proceed. - -Do not skip this step because the eventual UI should be semantic, editable, code-native, responsive, or accessible. Those are implementation requirements, not reasons to avoid visual exploration. - -### Purpose - -Use the mock step to find a stronger visual lane than code-first generation would reliably discover on its own. The brief remains authoritative on user, purpose, content, constraints, states, and anti-goals. The mock clarifies composition, hierarchy, density, typography, and visual tone. +When met, this step is mandatory for both brand and product work. If image generation isn't available, skip silently. "The eventual UI is semantic/code-native/accessible" is not a reason to skip; those are implementation requirements, not exploration ones. ### What to generate -Generate **1 to 3** high-fidelity north-star comps based on the confirmed brief. If shape already produced direction probes, use those results as input and generate a more resolved mock from the winning lane, not another unrelated exploration. +Generate **1 to 3** high-fidelity north-star comps from the confirmed brief. If shape already produced direction probes, resolve the winning lane further, not an unrelated exploration. Comps must differ in primary visual direction, not just color. -- For brand work, push visual identity, composition, and mood aggressively. -- For product work, still push hierarchy, topology, density, and tone, but keep the comps grounded in realistic product structure and states. -- For landing pages and long-form brand surfaces, show enough of the next section or second fold to establish the system beyond the hero. - -The comps must be genuinely different in primary visual direction, not just color variants. +- Brand work: push visual identity, composition, and mood aggressively. +- Product work: push hierarchy, topology, density, tone, grounded in realistic product structure. +- Landing pages and long-form brand surfaces: show enough of the second fold to establish the system beyond the hero. ### Approval loop -Show the comps and ask what should carry forward. If the user asks for changes or the best direction is still weak, generate a focused revision before implementation. Continue until one direction is approved, or until the user explicitly delegates the choice. +Show the comps and ask what carries forward. Iterate until one direction is approved or the user delegates. If the user delegates, pick the strongest direction and explain it from the brief, not personal taste. -If the user delegates, pick the strongest direction and explain the decision using the brief, not personal taste. - -Before moving to implementation, summarize: - -- What to carry into code -- What **not** to literalize from the mock - -This summary is required before Step 4. It is the handoff between visual exploration and semantic implementation. +Before Step 4, summarize what to carry into code and what **not** to literalize from the mock. This is the handoff between visual exploration and semantic implementation. ### Mock fidelity inventory -Before building, inventory the approved mock's major visible ingredients: +Inventory the approved mock's major visible ingredients: -- Hero silhouette and dominant composition. -- Signature motifs: planets, devices, portraits, charts, route lines, insets, badges, or other memorable objects. -- Nav and primary CTA treatment. -- Section sequence visible in the mock, especially the second fold. -- Image-native content the concept depends on. -- Typography, density, color/material treatment, and motion cues. +- Hero silhouette and dominant composition +- Signature motifs (planets, devices, portraits, charts, route lines, insets, badges, etc.) +- Nav and primary CTA treatment +- Section sequence, especially the second fold +- Image-native content the concept depends on +- Typography, density, color/material treatment, motion cues -For each ingredient, decide how it will be implemented: semantic HTML/CSS/SVG, generated asset, sourced project asset, icon library, canvas/WebGL, or an explicitly accepted omission. Do not substitute a different hero composition or new visual driver after approval unless the user approves the change. +For each, decide implementation: semantic HTML/CSS/SVG, generated asset, sourced asset, icon library, canvas/WebGL, or accepted omission. Don't substitute a different hero composition or visual driver post-approval without user sign-off. -Treat the mock as a **north star**, not a screenshot to trace. Do **not** rasterize core UI text or let the mock override the confirmed brief. But if the live result lacks the mock's major visible ingredients, the implementation is wrong. +If a photographic, architectural, product, or place-led mock becomes generic CSS scenery / decorative diagrams / bullets / copy, stop and fix it. That's a broken implementation, not a harmless interpretation. + +Treat the mock as a north star, not a screenshot to trace. Don't rasterize core UI text. But if the live result lacks the mock's major ingredients, the implementation is wrong. ## Step 4: Asset Extraction (Need-Gated) -If the chosen direction includes image-native visual ingredients that would materially improve the implementation, generate them as separate assets before building. +If the approved direction needs raster assets, create them before building. Do not replace required imagery with generic cards, bullets, emoji, fake metrics, decorative CSS panels, or filler copy. -Good candidates: +Use the native asset producer (`impeccable_asset_producer` in Codex, `impeccable-asset-producer` in Claude Code) to create clean assets from the hi-fi mock and crops. If you do not have explicit permission to use agents, stop and ask: -- stickers -- badges -- seals -- tickets -- graphic labels -- textures -- abstract objects -- decorative marks -- non-semantic scene elements +```text +Asset production will work better as a scoped subagent job. Should I spawn the Impeccable asset producer subagent for this step? +``` -For travel, editorial, portfolio, venue, product showcase, entertainment, education, or any other image-led brand surface, visual assets are usually core content, not decoration. Do not ship abstract CSS panels where the approved mock or subject matter calls for real imagery, generated plates, illustrations, maps, product/object renders, or destination scenes. +Do not skip asset production or silently do it inline. Inline asset production is allowed only if the user declines subagents, the harness cannot spawn the authorized agent, or the user explicitly asks for single-thread mode. -Do **not** export assets for core UI text, navigation, body copy, or any structure that should stay semantic and editable in code. +Pass the approved mock, crop/contact-sheet paths, output directory, dimensions/formats, transparency needs, constraints, and avoid list to the asset producer. Attach image generation capability to the spawned agent when the harness supports it; do not load image-generation reference material into the parent thread first. -Usually **1 to 5** extracted assets is enough. If the design can be built cleanly in HTML/CSS/SVG, prefer that over raster assets. If the mock contains major visual content that cannot be built credibly in code, asset extraction is not optional. +Prefer HTML/CSS/SVG/canvas when they can credibly reproduce an ingredient; use real/generated/stock imagery when the mock or subject matter calls for actual visual content. ## Step 5: Build to Production Quality @@ -135,50 +114,35 @@ Implement the feature following the design brief. Build in passes so structure, ### Production bar -- Use real or realistic content. Remove placeholder copy, placeholder images, dead links, fake controls, and unused scaffold before presenting. -- Preserve the approved mock's major ingredients. Missing hero objects, missing world/product imagery, different section structure, downgraded CTA/nav treatment, or generic replacements for distinctive motifs are blocking defects unless the user accepted the change. -- Build semantically first: real headings, landmarks, labels, form associations, button/link semantics, accessible names, and state announcements where needed. -- Calibrate spacing, alignment, grid placement, and vertical rhythm deliberately. Do not accept default gaps, arbitrary margins, unbalanced whitespace, or accidental optical misalignment. -- Make typography intentional: chosen font loading strategy, clear hierarchy, readable measure, stable line breaks, tuned wrapping, and no overflow at mobile or large desktop sizes. -- Design realistic state coverage: default, hover where supported, focus-visible, active, disabled, loading, error, success, empty, overflow, long text, short text, and first-run states where relevant. -- Make interaction quality feel finished: keyboard paths, touch targets, feedback timing, scroll behavior, transitions between states, and no hover-only functionality. -- Use icons from the project's established icon set when available. If no set exists, choose a coherent library or use accessible text controls; do not mix unrelated icon styles. -- Optimize imagery and media: correct dimensions, useful alt text, lazy loading below the fold, modern formats when practical, responsive `srcset` / `picture` for raster assets, and no project-referenced asset left outside the workspace. -- Make motion feel premium: use atmospheric blur, filter, mask, shadow, or reveal effects when they improve the experience; avoid casual layout-property animation, bound expensive effects, verify smoothness in-browser, respect reduced motion, and avoid choreography that blocks task completion. -- Preserve maintainability: reusable local patterns, clear component boundaries, project conventions, no rasterized UI text, and no hard-coded one-off hacks when a better local pattern exists. -- Fit the technical context: production build passes, no obvious console errors, no avoidable layout shift, no needless dependency, and no broken asset path. -- If you discover a design question that materially changes the brief or approved direction, stop and ask rather than guessing. +- **Real content.** No placeholder copy, placeholder images, dead links, fake controls, or unused scaffold at presentation time. +- **Preserve the approved mock's major ingredients.** Missing hero objects, world/product imagery, section structure, CTA/nav treatment, or distinctive motifs are blocking defects unless the user accepted the change. +- **Semantic first.** Real headings, landmarks, labels, form associations, button/link semantics, accessible names, state announcements where needed. +- **Deliberate spacing and alignment.** No default gaps, arbitrary margins, unbalanced whitespace, or accidental optical misalignment. +- **Intentional typography.** Chosen loading strategy, clear hierarchy, readable measure, stable line breaks, no overflow at any width. +- **Realistic state coverage.** Default, hover, focus-visible, active, disabled, loading, error, success, empty, overflow, long/short text, first-run. +- **Finished interaction quality.** Keyboard paths, touch targets, feedback timing, scroll behavior, state transitions, no hover-only functionality. +- **Coherent icon set.** Use the project's established set; otherwise pick one library or use accessible text. Don't mix. +- **Respect the build pipeline.** Edit source files and run the project's build (`npm run build` or equivalent). Don't write to `build/` / `dist/` / `.next/` with `cat`, heredoc, or Bash redirects; that skips asset hashing, image optimization, code splitting, and CSS extraction, and produces output the dev server won't serve. +- **Verify image URLs before referencing them.** Use image-search MCP or web-fetch when available; guessed photo IDs ship as broken-image placeholders. Without verification, prefer fewer images you're confident about. +- **Optimized imagery and media.** Correct dimensions, useful alt text, lazy loading below the fold, modern formats when practical, responsive `srcset`/`picture` for raster, no project-referenced asset left outside the workspace. +- **Premium motion.** Use atmospheric blur, filter, mask, shadow, reveal when they improve the experience. Avoid casual layout-property animation, bound expensive effects, verify smoothness in-browser, respect reduced motion, and avoid choreography that blocks task completion. +- **Maintainable.** Reusable local patterns, clear component boundaries, project conventions. No rasterized UI text or one-off hacks when a local pattern exists. +- **Technically clean.** Production build passes, no console errors, no avoidable layout shift, no needless dependencies, no broken asset paths. +- **Ask when uncertain.** If a discovery materially changes the brief or approved direction, stop and ask. Don't guess. -## Step 6: Browser-Based Iteration +## Step 6: Iterate Visually -**This step is critical.** Do not stop after the first implementation pass. +Look at what you built like a designer would. Your eyes are whatever the harness gives you: a connected browser, a screenshotting tool, Playwright, or asking the user. Use them for responsive testing (mobile, tablet, desktop minimum) and general visual validation. -Open the result in a browser. In Codex, use browser-use or equivalent browser automation when available; otherwise use Playwright or ask the user for screenshots. Inspect screenshots, not just DOM or terminal output. +If your tool returns a file path, read the PNG back into the conversation. A screenshot you didn't read doesn't count. -### Required viewport pass +For long-form brand surfaces, inspect major sections individually. Thumbnails hide spacing, clipping, and cascade defects. -Check the experience at the viewports that matter for the brief. Default minimum: +After the first pass, write an honest critique against the brief, the approved mock's major ingredients (hero silhouette, motifs, imagery, nav/CTA, density), and impeccable's DON'Ts. Patch material defects and re-inspect. **Don't invent defects to demonstrate iteration.** A confident "first pass clean, shipping" beats a fake fix. -- Mobile narrow -- Tablet or small laptop -- Desktop wide +Actively check: responsive behavior (composes, not shrinks), every state (empty / error / loading / edge), craft details (spacing, alignment, hierarchy, contrast, motion timing, focus), performance basics. The exit bar: defensible in a high-end studio review. -For each viewport, capture or inspect the rendered state and look for visual defects: overlap, clipping, weak hierarchy, off-grid alignment, awkward whitespace, cramped controls, unreadable type, broken imagery, hover-only functionality, layout shift, and text overflow. - -### Critique and fix loop - -After the first browser pass, write a short critique for yourself and patch the implementation. Repeat browser inspection after fixes. Continue until no material issues remain against this checklist: - -1. **Does it match the brief?** Compare the live result against every section of the design brief. Fix discrepancies. -2. **Does it match the approved mock?** Compare screenshots against the mock fidelity inventory: hero silhouette, major motifs, imagery, nav/CTA, section sequence, density, color/materials, and second-fold substance. Missing major ingredients are P0 defects. -3. **Does it pass the AI slop test?** If someone saw this and said "AI made this," would they believe it immediately? If yes, it needs more design intention. -4. **Check against impeccable's DON'T guidelines.** Fix any anti-pattern violations. -5. **Check every state.** Navigate through empty, error, loading, and edge case states. Each one should feel intentional, not like an afterthought. -6. **Check responsive behavior.** The design should adapt compositionally, not merely shrink. -7. **Check craft details.** Spacing consistency, optical alignment, type hierarchy, color contrast, image quality, icon coherence, interactive feedback, motion timing, and focus treatment. -8. **Check performance basics.** No obviously oversized images, avoidable layout thrash, blocking animations, or heavy assets without a reason. - -The exit bar is not "it works." It is: the rendered result looks intentional at all checked viewports, all expected states are handled, no placeholders remain unless explicitly accepted, and the implementation quality would be defensible in a high-end studio review. +Detector or QA output is defect evidence only; never proof the work is finished. ## Step 7: Present @@ -189,5 +153,3 @@ Present the result to the user: - Explain design decisions that connect back to the design brief and, when used, the chosen north-star mock. Include any accepted deviations from the mock; do not hide unimplemented mock ingredients. - Note any remaining limitations or follow-up risks honestly - Ask: "What's working? What isn't?" - -Iterate based on feedback. Good design is rarely right on the first pass. diff --git a/.cursor/skills/impeccable/reference/critique.md b/.cursor/skills/impeccable/reference/critique.md index 712e8f757..1f8ab2868 100644 --- a/.cursor/skills/impeccable/reference/critique.md +++ b/.cursor/skills/impeccable/reference/critique.md @@ -43,7 +43,7 @@ Run the bundled deterministic detector, which flags 27 specific patterns (AI slo **CLI scan**: ```bash -npx impeccable --json [--fast] [target] +npx impeccable detect --json [--fast] [target] ``` - Pass HTML/JSX/TSX/Vue/Svelte files or directories as `[target]` (anything with markup). Do not pass CSS-only files. diff --git a/.cursor/skills/impeccable/reference/polish.md b/.cursor/skills/impeccable/reference/polish.md index a2a409e48..eed3dbd27 100644 --- a/.cursor/skills/impeccable/reference/polish.md +++ b/.cursor/skills/impeccable/reference/polish.md @@ -2,6 +2,8 @@ Perform a meticulous final pass to catch all the small details that separate good work from great work. The difference between shipped and polished. +Detector and automated QA output are defect evidence only. A clean script result is never proof that the design is strong; gather browser evidence and inspect the real interaction path. + ## Design System Discovery Aligning the feature to the design system is **not optional**. Polish without alignment is decoration on top of drift, and it makes the next person's job harder. Discovery comes before any other polish work. @@ -216,11 +218,12 @@ Sweat the details. Zoom in until the alignment is right and the spacing reads as Before marking as done: -- **Use it yourself**: Actually interact with the feature -- **Test on real devices**: Not just browser DevTools -- **Ask someone else to review**: Fresh eyes catch things -- **Compare to design**: Match intended design -- **Check all states**: Don't just test happy path +- **Use it yourself**: Actually interact with the feature. +- **Test on real devices**: Not just browser DevTools. +- **Ask someone else to review**: Fresh eyes catch things. +- **Compare to design**: Match intended design. +- **Check all states**: Don't just test happy path. +- **Treat automation carefully**: Run detector or QA commands when they are available and relevant, fix their defects, but never cite a clean result as proof that the work is polished. ## Clean Up @@ -230,4 +233,3 @@ After polishing, ensure code quality: - **Remove orphaned code**: Delete unused styles, components, or files made obsolete by polish. - **Consolidate tokens**: If you introduced new values, check whether they should be tokens. - **Verify DRYness**: Look for duplication introduced during polishing and consolidate. - diff --git a/.cursor/skills/impeccable/reference/shape.md b/.cursor/skills/impeccable/reference/shape.md index 0785187ef..d1c983ff4 100644 --- a/.cursor/skills/impeccable/reference/shape.md +++ b/.cursor/skills/impeccable/reference/shape.md @@ -16,14 +16,16 @@ This is a required interaction, not optional guidance. Ask these questions in co ### Interview cadence -Discovery must include at least one user-answer round unless PRODUCT.md, DESIGN.md, or an already-confirmed brief directly answers the needed design inputs. With a sparse prompt, do **not** synthesize a complete brief for confirmation on the first response. +Discovery includes at least one user-answer round unless PRODUCT.md, DESIGN.md, or an already-confirmed brief directly answers the needed inputs. With a sparse prompt, do **not** synthesize a complete brief for confirmation on the first response. - Use the harness's structured question tool when one exists. Otherwise, ask directly in chat and stop. - Ask **2-3 questions per round**, then wait for answers. - Treat PRODUCT.md and DESIGN.md as anchors; they reduce repeated questions but do **not** replace shape for craft. Shape is task-specific. -- Round 1 should clarify purpose, audience/context, and success or emotional outcome. -- Round 2 should clarify content/data/states and scope/fidelity. -- Round 3 should clarify visual direction, constraints, and anti-goals when still unresolved. +- One round is the default. Add a second only if the first answers leave material gaps. Don't run a second round just to feel thorough. +- Round 1 should clarify purpose, audience/context, content/scope, and (for brand) visual direction. +- Round 2, when needed, fills in whatever's still genuinely missing. + +**Assert-then-confirm, not menu-with-escape.** When PRODUCT.md and the user's prompt make one option obvious, name it and ask the user to confirm or override. Don't enumerate "Restrained / Committed / Or something else?" as a real choice; "This reads as Restrained, confirm?" beats a four-option menu when the answer is already clear. ### Purpose & Context - What is this feature for? What problem does it solve? @@ -36,6 +38,7 @@ Discovery must include at least one user-answer round unless PRODUCT.md, DESIGN. - What are the realistic ranges? (Minimum, typical, maximum, e.g., 0 items, 5 items, 500 items) - What are the edge cases? (Empty state, error state, first-time use, power user) - Is any content dynamic? What changes and how often? +- What visual assets are real content here? Note required images, product shots, illustrations, maps, textures, diagrams, generated objects, or existing project assets. ### Design Direction @@ -72,9 +75,9 @@ After the discovery interview, generate a small set of visual direction probes * - The work is **net-new** or directionally ambiguous enough that visual exploration will clarify the brief. - The requested fidelity is **mid-fi, high-fi, or production-ready**. Skip for sketch-only planning. -- The current harness has **built-in image generation capability** (for example, Codex with a native image tool). Do **not** ask the user to set up external APIs, shell scripts, or one-off tooling just to do this. +- The current harness gives you native image generation (Codex's `image_gen`, an equivalent MCP tool, or similar). Don't ask the user to install APIs or tooling. -When those conditions are met, this step is mandatory for Codex and any harness with built-in image generation. Use native image generation; in Codex, use the built-in `image_gen` tool via the imagegen skill. If image generation is unavailable, do not ask the user to install APIs or tooling. State in one line that the image step is skipped because the harness lacks native image generation, then proceed. +When those conditions are met, this step is mandatory. If image generation isn't natively available, skip silently and proceed; don't announce the skip. Use probes to explore visual lanes, not to replace the brief. @@ -104,11 +107,20 @@ The probes should differ in primary visual direction (hierarchy, topology, densi - Do **not** treat generated imagery as final UX specification, final copy, or final accessibility behavior. - Do **not** use this step for minor refinements of existing work. It's for shaping a new surface or clarifying a big directional choice. -If image generation is unavailable, or the task doesn't benefit from it, skip this phase only with a one-line reason and proceed directly to the design brief. +If image generation isn't natively available, skip this phase silently and proceed. ## Phase 2: Design Brief -After the interview and any required probes, synthesize everything into a structured design brief. Present it to the user for explicit confirmation before considering this command complete. Stop after asking for confirmation; do not proceed to craft or implementation in the same response unless the user has already approved the brief. +After the interview and any required probes, present a brief and **end your response**. The user must confirm before any implementation runs. Do not present a brief and then continue to code in the same response, even if the brief feels obvious to you. The user's confirmation is the gate. + +**Choose the brief shape based on how clear the answers are:** + +- **Compact form (3-5 bullets)** when discovery was crisp and the original prompt + PRODUCT.md already pinned scope, content, and direction. State what you're building, the visual lane, and end with one or two specific questions or a clear "confirm or override?" prompt. This is the default for typical craft requests with a clear prompt. +- **Full structured form (sections below)** when the task is genuinely ambiguous, multi-screen, or when the user asked for shape as a standalone step. Use this when the discipline of structure earns its weight. + +Don't pad a clear brief into a long one to look thorough. A 70-line brief restating answers the user just gave is noise, not rigor. Equally, don't skip the confirmation pause to look efficient: the pause is the point. + +If the user already said "approved" or "go" during discovery for the *exact direction you'd present*, that counts as confirmation; you may proceed without asking again. But if your brief adds anything the user hasn't seen and approved, you must stop and confirm. ### Brief Structure @@ -136,16 +148,18 @@ List every state the feature needs: default, empty, loading, error, success, edg How users interact with this feature. What happens on click, hover, scroll? What feedback do they get? What's the flow from entry to completion? **8. Content Requirements** -What copy, labels, empty state messages, error messages, and microcopy are needed. Note any dynamic content and its realistic ranges. +What copy, labels, empty state messages, error messages, and microcopy are needed. Note any dynamic content and its realistic ranges. For image-led surfaces, also list the required image/media roles and their likely source (project asset, generated raster, semantic SVG/CSS, canvas/WebGL, icon library, or accepted omission). **9. Recommended References** Based on the brief, list which impeccable reference files would be most valuable during implementation (e.g., spatial-design.md for complex layouts, motion-design.md for animated features, interaction-design.md for form-heavy features). **10. Open Questions** -Anything unresolved that the implementer should resolve during build. +Anything genuinely unresolved. Don't list "open questions" you've already recommended a default for; assert the default and move on. If you'd write `Recommend: X` next to a question, just decide X. --- -ask the user directly to clarify what you cannot infer. Ask for explicit confirmation of the brief before finishing. If the user disagrees with any part, revisit the relevant discovery questions. A shape run is incomplete until the brief is confirmed. +ask the user directly to clarify what you cannot infer. + +If the user disagrees with any part, revisit the relevant discovery questions. A shape run is incomplete until the user confirms direction (or the user already gave a clear go during discovery, which counts). Once confirmed, the brief is complete. The user can now hand it to /impeccable, or use it to guide any other implementation approach. (If the user wants the full discovery-then-build flow in one step, they should use /impeccable craft instead, which runs this command internally.) diff --git a/.gemini/skills/impeccable/SKILL.md b/.gemini/skills/impeccable/SKILL.md index fe6ba645e..cca0ecd71 100644 --- a/.gemini/skills/impeccable/SKILL.md +++ b/.gemini/skills/impeccable/SKILL.md @@ -6,28 +6,15 @@ version: 3.0.7 Designs and iterates production-grade frontend interfaces. Real working code, committed design choices, exceptional craft. -## Setup (non-optional) +## Setup -Before any design work or file edits, pass these gates. Skipping them produces generic output that ignores the project. +Before any design work or file edits: -| 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. | +1. Load context (PRODUCT.md / DESIGN.md) via the loader script. +2. Identify the register and load the matching register reference (brand.md or product.md). +3. **If the user invoked a sub-command (e.g. `craft`, `shape`, `audit`), load its reference file too.** This is non-negotiable: `craft` without `craft.md` loaded means you'll skip the shape-and-confirm step the user expects. -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: 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. +Skipping these produces generic output that ignores the project. ### 1. Context gathering diff --git a/.gemini/skills/impeccable/reference/brand.md b/.gemini/skills/impeccable/reference/brand.md index b069f2553..3d83a1cdc 100644 --- a/.gemini/skills/impeccable/reference/brand.md +++ b/.gemini/skills/impeccable/reference/brand.md @@ -12,6 +12,8 @@ Brand isn't a neutral register. AI-generated landing pages have flooded the inte **The second slop test: aesthetic lane.** Before committing to moves, name the reference. A Klim-style specimen page is one lane; Stripe-minimal is another; Liquid-Death-acid-maximalism is another. Don't drift into editorial-magazine aesthetics on a brief that isn't editorial. A hiking brand with Cormorant italic drop caps has the wrong register within the register. +Then the inverse test: in one sentence, describe what you're about to build the way a competitor would describe theirs. If that sentence fits the modal landing page in the category, restart. + ## Typography ### Font selection procedure @@ -66,6 +68,7 @@ Brand surfaces have permission for Committed, Full palette, and Drenched strateg - Palette IS voice. A calm brand and a restless brand should not share palette mechanics. - When the strategy is Committed or Drenched, color carries the brand. Don't hedge with neutrals around the edges. Commit. - Don't converge across projects. If the last brand surface was restrained-on-cream, this one is not. +- When a cultural-symbol palette is the obvious pull, reach past it. Let the cultural reading come from typography, imagery, and copy, not the palette. ## Layout @@ -79,14 +82,14 @@ Brand surfaces have permission for Committed, Full palette, and Drenched strateg Brand surfaces lean on imagery. A restaurant, hotel, magazine, or product landing page without any imagery reads as incomplete, not as restrained. A solid-color rectangle where a hero image should go is worse than a representative stock photo. -**When the brief implies imagery (restaurants, hotels, magazines, photography, hobbyist communities, food, travel, fashion, product), you must ship imagery.** Zero images is a bug, not a design choice. "Restraint" is not an excuse. +**When the brief implies imagery (restaurants, hotels, magazines, photography, hobbyist communities, food, travel, fashion, product), you must ship imagery.** Zero images is a bug, not a design choice. "Restraint" is not an excuse. If the approved comp or brief is image-led, ship real project assets, generated raster assets, or a credible canvas/SVG/WebGL scene. Do not replace photographic, architectural, product, or place imagery with generic CSS panels, decorative diagrams, cards, bullets, or copy. -- **For greenfield work without local assets, use stock imagery.** Unsplash is the default. The URL shape is `https://images.unsplash.com/photo-{id}?auto=format&fit=crop&w=1600&q=80`. Pick real Unsplash photo IDs you're confident exist (`photo-1559339352-11d035aa65de`, `photo-1590490360182-c33d57733427`, etc.); if unsure, pick fewer photos but don't substitute colored `
` placeholders. +- **For greenfield work without local assets, use stock imagery.** Unsplash is the default. The URL shape is `https://images.unsplash.com/photo-{id}?auto=format&fit=crop&w=1600&q=80`. **Verify the URLs before referencing them.** If you have an image-search MCP, web-fetch tool, or browser access, use it to find real photo IDs and confirm they resolve. Guessed IDs (even ones that look real) often 404 and ship as broken-image placeholders. Without a verification path, pick fewer photos you're confident exist over more that you guessed; never substitute colored `
` placeholders. - **Search for the brand's physical object**, not the generic category: "handmade pasta on a scratched wooden table" beats "Italian food"; "cypress trees above a limestone hotel facade at dusk" beats "luxury hotel". - **One decisive photo beats five mediocre ones.** Hero imagery should commit to a mood; padding with more stock doesn't rescue an indecisive one. - **Alt text is part of the voice.** "Coastal fettuccine, hand-cut, served on the terrace" beats "pasta dish". -Tech / dev-tool brands are the exception where zero imagery can be correct; a developer landing page often carries its voice through typography, code samples, diagrams. Know which kind of brand you're working on. +"Imagery" here is broader than stock photography: product screenshots, custom data visualizations, generated SVG, and canvas/WebGL scenes are all imagery. Text-only pages where typography alone carries the entire visual weight are the failure mode. ## Motion @@ -102,6 +105,7 @@ Tech / dev-tool brands are the exception where zero imagery can be correct; a de - Timid palettes and average layouts. Safe = invisible. - Zero imagery on a brief that implies imagery (restaurant, hotel, food, travel, fashion, photography, hobbyist). Colored blocks where a hero photo belongs. - Defaulting to editorial-magazine aesthetics (display serif + italic + drop caps + broadsheet grid) on briefs that aren't magazine-shaped. Editorial is ONE aesthetic lane, not the default brand aesthetic. +- Repeated tiny uppercase tracked labels above every section heading. A single strong kicker can be voice; repeating it as section grammar is AI scaffolding unless it's a deliberate, named brand system. ## Brand permissions diff --git a/.gemini/skills/impeccable/reference/craft.md b/.gemini/skills/impeccable/reference/craft.md index bdeee0294..c0cfa7460 100644 --- a/.gemini/skills/impeccable/reference/craft.md +++ b/.gemini/skills/impeccable/reference/craft.md @@ -1,43 +1,41 @@ # Craft Flow -Build a feature with impeccable UX and UI quality through a structured process: shape the design, land the visual direction, build real production code, then inspect and improve in-browser until the result meets a high-end studio bar. +Build a feature with impeccable UX and UI quality: shape the design, land the visual direction, build real production code, inspect and improve in-browser until it meets a high-end studio bar. -## Build Gate +Before writing code, you need: PRODUCT.md loaded, register identified and the matching reference loaded, and a confirmed design direction for this task (either from `shape` or supplied by the user). PRODUCT.md is project context, not a task-specific brief. -Craft cannot build until all of these are true: +Treat any approved visual direction (generated mock or stated reference) as a concrete contract for composition, hierarchy, density, atmosphere, signature motifs, and distinctive visual moves. Don't let mocks replace structure, copy, accessibility, or state design. But if the live result lacks the approved direction's major ingredients, the implementation is wrong. -1. PRODUCT context is valid and current. -2. The shape design brief is explicitly confirmed by the user for this task, unless the user already provided a confirmed brief. -3. Implementation references from the brief are loaded. -4. The shape visual probe decision is recorded: generated, skipped with reason, or already resolved. -5. The north-star mock decision is recorded: generated, skipped with reason, or not applicable. +## Step 0: Project Foundation -PRODUCT.md and `teach` answers do **not** satisfy the shape gate. They are project context only. A compact self-authored brief does not satisfy the shape gate either. `shape=pass` requires a separate user response approving the shape brief or an already-confirmed brief supplied by the user. +Before shape, before code: figure out what kind of project you're working in. -Invalid image-skip reasons include: "the final implementation will be semantic HTML/CSS/SVG", "the diagram should stay editable", "a raster mock would not be used directly", or "the product is fictional." Generated probes and mocks are direction artifacts; they are not implementation assets. +Look at the working directory. Run `ls`. Check for: -## Craft Contract +- An existing framework: `astro.config.mjs/ts`, `next.config.js/ts`, `nuxt.config.ts`, `svelte.config.js`, `vite.config.js/ts`, `package.json` with framework deps, `Cargo.toml` + Leptos/Yew, `Gemfile` + Rails. **If found, use it.** Do not start a parallel build, do not introduce a second framework, do not write to `dist/` or `build/` directly. Whatever pipeline the project has, respect it. +- An existing component library or design system: `src/components/`, `app/components/`, a `tokens.css` / `theme.ts`, an `astro.config` `integrations`. Read what's there before adding to it. +- An existing icon set: `lucide-react`, `@phosphor-icons/react`, `@iconify/*`, hand-rolled SVG sprites in `assets/icons/`. **Use what's already in the project**; don't introduce a second set. -Craft is not a first pass. It is a loop with these required artifacts: +If the directory is empty (greenfield), don't pick a framework silently. Ask the user via the AskUserQuestion tool, with sensible defaults framed by the brief: -1. Confirmed design brief from `shape`. -2. Approved visual direction, from generated probes / mocks when image generation is available. -3. Mock fidelity inventory: the visible ingredients from the approved direction that must survive into code. -4. Semantic, functional implementation using the project's real stack and conventions. -5. Browser evidence across relevant viewports. -6. At least one critique-and-fix pass after the first browser inspection, unless the first pass has no material defects. +```text +What should this be built on? + - Astro (default for content-led brand sites, landing pages, marketing surfaces) + - SvelteKit / Next.js / Nuxt (when the brief implies an app surface or significant interactivity) + - Single index.html (one-shot demo, prototype, or a deliberately framework-free experiment) +``` -Do not let generated mockups replace interface structure, copy, accessibility, responsive behavior, or state design. But do treat the approved mock as a concrete visual contract for composition, hierarchy, density, atmosphere, signature motifs, image needs, and distinctive visual moves. "North star" means "preserve the important visible ingredients in semantic code," not "use it as loose mood." +Default: Astro for brand briefs, the project's existing framework for product briefs. Ask once; don't re-ask mid-task. ## Step 1: Shape the Design -Run /impeccable shape, passing along whatever feature description the user provided. +Run /impeccable shape, passing along whatever feature description the user provided. Shape is **required** for craft; it is what produces a confirmed direction. -Wait for the design brief to be fully confirmed by the user before proceeding. The brief is your blueprint, and every implementation decision should trace back to it. +Present the shape output and stop. Wait for the user to confirm, override, or course-correct before writing code. -If this craft run resumed after `teach` created PRODUCT.md, run shape now. Do not treat the teach interview, PRODUCT.md, or a summary of project context as a substitute for shape. Shape is task-specific and must cover scope, content/states, visual direction, constraints, anti-goals, probes when applicable, and explicit brief confirmation. +If the user already supplied a confirmed brief or ran shape separately, use it and skip this step. -If the user has already run /impeccable shape and has a confirmed design brief, skip this step and use the existing brief. +When the original prompt + PRODUCT.md already answer scope, content, and visual direction with no real ambiguity, the shape output can be **compact** (3-5 bullets stating what you're building and the visual lane, ending with one or two specific questions or "confirm or override"). The full 10-section structured brief is reserved for genuinely ambiguous, multi-screen, or stakeholder-heavy tasks. Don't pad a clear brief into a long one to look thorough; equally, don't skip the pause to look efficient. ## Step 2: Load References @@ -55,79 +53,60 @@ Then add references based on the brief's needs: ## Step 3: Land the Visual Direction (Capability-Gated) -Before implementation, generate high-fidelity visual comps when all of these are true: +Generate high-fidelity visual comps before implementation when all three are true: -- The work is **net-new** or visually open-ended enough that composition exploration will improve the build. -- The brief's scope is **mid-fi, high-fi, or production-ready**. -- The current harness has **built-in image generation capability** (for example, Codex with a native image tool). Do **not** ask the user to set up external APIs, shell scripts, or one-off tooling just to do this. +- The work is net-new or visually open-ended enough that composition exploration will improve the build. +- The brief's scope is mid-fi, high-fi, or production-ready. +- The harness gives you native image generation (Codex's `image_gen`, an equivalent MCP tool). Don't ask the user to set up external APIs. -When those conditions are met, this step is mandatory for **both brand and product work** in Codex and any harness with built-in image generation. Use native image generation; in Codex, use the built-in `image_gen` tool via the imagegen skill. If image generation is unavailable, do not ask the user to install APIs or tooling. State in one line that the image step is skipped because the harness lacks native image generation, then proceed. - -Do not skip this step because the eventual UI should be semantic, editable, code-native, responsive, or accessible. Those are implementation requirements, not reasons to avoid visual exploration. - -### Purpose - -Use the mock step to find a stronger visual lane than code-first generation would reliably discover on its own. The brief remains authoritative on user, purpose, content, constraints, states, and anti-goals. The mock clarifies composition, hierarchy, density, typography, and visual tone. +When met, this step is mandatory for both brand and product work. If image generation isn't available, skip silently. "The eventual UI is semantic/code-native/accessible" is not a reason to skip; those are implementation requirements, not exploration ones. ### What to generate -Generate **1 to 3** high-fidelity north-star comps based on the confirmed brief. If shape already produced direction probes, use those results as input and generate a more resolved mock from the winning lane, not another unrelated exploration. +Generate **1 to 3** high-fidelity north-star comps from the confirmed brief. If shape already produced direction probes, resolve the winning lane further, not an unrelated exploration. Comps must differ in primary visual direction, not just color. -- For brand work, push visual identity, composition, and mood aggressively. -- For product work, still push hierarchy, topology, density, and tone, but keep the comps grounded in realistic product structure and states. -- For landing pages and long-form brand surfaces, show enough of the next section or second fold to establish the system beyond the hero. - -The comps must be genuinely different in primary visual direction, not just color variants. +- Brand work: push visual identity, composition, and mood aggressively. +- Product work: push hierarchy, topology, density, tone, grounded in realistic product structure. +- Landing pages and long-form brand surfaces: show enough of the second fold to establish the system beyond the hero. ### Approval loop -Show the comps and ask what should carry forward. If the user asks for changes or the best direction is still weak, generate a focused revision before implementation. Continue until one direction is approved, or until the user explicitly delegates the choice. +Show the comps and ask what carries forward. Iterate until one direction is approved or the user delegates. If the user delegates, pick the strongest direction and explain it from the brief, not personal taste. -If the user delegates, pick the strongest direction and explain the decision using the brief, not personal taste. - -Before moving to implementation, summarize: - -- What to carry into code -- What **not** to literalize from the mock - -This summary is required before Step 4. It is the handoff between visual exploration and semantic implementation. +Before Step 4, summarize what to carry into code and what **not** to literalize from the mock. This is the handoff between visual exploration and semantic implementation. ### Mock fidelity inventory -Before building, inventory the approved mock's major visible ingredients: +Inventory the approved mock's major visible ingredients: -- Hero silhouette and dominant composition. -- Signature motifs: planets, devices, portraits, charts, route lines, insets, badges, or other memorable objects. -- Nav and primary CTA treatment. -- Section sequence visible in the mock, especially the second fold. -- Image-native content the concept depends on. -- Typography, density, color/material treatment, and motion cues. +- Hero silhouette and dominant composition +- Signature motifs (planets, devices, portraits, charts, route lines, insets, badges, etc.) +- Nav and primary CTA treatment +- Section sequence, especially the second fold +- Image-native content the concept depends on +- Typography, density, color/material treatment, motion cues -For each ingredient, decide how it will be implemented: semantic HTML/CSS/SVG, generated asset, sourced project asset, icon library, canvas/WebGL, or an explicitly accepted omission. Do not substitute a different hero composition or new visual driver after approval unless the user approves the change. +For each, decide implementation: semantic HTML/CSS/SVG, generated asset, sourced asset, icon library, canvas/WebGL, or accepted omission. Don't substitute a different hero composition or visual driver post-approval without user sign-off. -Treat the mock as a **north star**, not a screenshot to trace. Do **not** rasterize core UI text or let the mock override the confirmed brief. But if the live result lacks the mock's major visible ingredients, the implementation is wrong. +If a photographic, architectural, product, or place-led mock becomes generic CSS scenery / decorative diagrams / bullets / copy, stop and fix it. That's a broken implementation, not a harmless interpretation. + +Treat the mock as a north star, not a screenshot to trace. Don't rasterize core UI text. But if the live result lacks the mock's major ingredients, the implementation is wrong. ## Step 4: Asset Extraction (Need-Gated) -If the chosen direction includes image-native visual ingredients that would materially improve the implementation, generate them as separate assets before building. +If the approved direction needs raster assets, create them before building. Do not replace required imagery with generic cards, bullets, emoji, fake metrics, decorative CSS panels, or filler copy. -Good candidates: +Use the native asset producer (`impeccable_asset_producer` in Codex, `impeccable-asset-producer` in Claude Code) to create clean assets from the hi-fi mock and crops. If you do not have explicit permission to use agents, stop and ask: -- stickers -- badges -- seals -- tickets -- graphic labels -- textures -- abstract objects -- decorative marks -- non-semantic scene elements +```text +Asset production will work better as a scoped subagent job. Should I spawn the Impeccable asset producer subagent for this step? +``` -For travel, editorial, portfolio, venue, product showcase, entertainment, education, or any other image-led brand surface, visual assets are usually core content, not decoration. Do not ship abstract CSS panels where the approved mock or subject matter calls for real imagery, generated plates, illustrations, maps, product/object renders, or destination scenes. +Do not skip asset production or silently do it inline. Inline asset production is allowed only if the user declines subagents, the harness cannot spawn the authorized agent, or the user explicitly asks for single-thread mode. -Do **not** export assets for core UI text, navigation, body copy, or any structure that should stay semantic and editable in code. +Pass the approved mock, crop/contact-sheet paths, output directory, dimensions/formats, transparency needs, constraints, and avoid list to the asset producer. Attach image generation capability to the spawned agent when the harness supports it; do not load image-generation reference material into the parent thread first. -Usually **1 to 5** extracted assets is enough. If the design can be built cleanly in HTML/CSS/SVG, prefer that over raster assets. If the mock contains major visual content that cannot be built credibly in code, asset extraction is not optional. +Prefer HTML/CSS/SVG/canvas when they can credibly reproduce an ingredient; use real/generated/stock imagery when the mock or subject matter calls for actual visual content. ## Step 5: Build to Production Quality @@ -135,50 +114,35 @@ Implement the feature following the design brief. Build in passes so structure, ### Production bar -- Use real or realistic content. Remove placeholder copy, placeholder images, dead links, fake controls, and unused scaffold before presenting. -- Preserve the approved mock's major ingredients. Missing hero objects, missing world/product imagery, different section structure, downgraded CTA/nav treatment, or generic replacements for distinctive motifs are blocking defects unless the user accepted the change. -- Build semantically first: real headings, landmarks, labels, form associations, button/link semantics, accessible names, and state announcements where needed. -- Calibrate spacing, alignment, grid placement, and vertical rhythm deliberately. Do not accept default gaps, arbitrary margins, unbalanced whitespace, or accidental optical misalignment. -- Make typography intentional: chosen font loading strategy, clear hierarchy, readable measure, stable line breaks, tuned wrapping, and no overflow at mobile or large desktop sizes. -- Design realistic state coverage: default, hover where supported, focus-visible, active, disabled, loading, error, success, empty, overflow, long text, short text, and first-run states where relevant. -- Make interaction quality feel finished: keyboard paths, touch targets, feedback timing, scroll behavior, transitions between states, and no hover-only functionality. -- Use icons from the project's established icon set when available. If no set exists, choose a coherent library or use accessible text controls; do not mix unrelated icon styles. -- Optimize imagery and media: correct dimensions, useful alt text, lazy loading below the fold, modern formats when practical, responsive `srcset` / `picture` for raster assets, and no project-referenced asset left outside the workspace. -- Make motion feel premium: use atmospheric blur, filter, mask, shadow, or reveal effects when they improve the experience; avoid casual layout-property animation, bound expensive effects, verify smoothness in-browser, respect reduced motion, and avoid choreography that blocks task completion. -- Preserve maintainability: reusable local patterns, clear component boundaries, project conventions, no rasterized UI text, and no hard-coded one-off hacks when a better local pattern exists. -- Fit the technical context: production build passes, no obvious console errors, no avoidable layout shift, no needless dependency, and no broken asset path. -- If you discover a design question that materially changes the brief or approved direction, stop and ask rather than guessing. +- **Real content.** No placeholder copy, placeholder images, dead links, fake controls, or unused scaffold at presentation time. +- **Preserve the approved mock's major ingredients.** Missing hero objects, world/product imagery, section structure, CTA/nav treatment, or distinctive motifs are blocking defects unless the user accepted the change. +- **Semantic first.** Real headings, landmarks, labels, form associations, button/link semantics, accessible names, state announcements where needed. +- **Deliberate spacing and alignment.** No default gaps, arbitrary margins, unbalanced whitespace, or accidental optical misalignment. +- **Intentional typography.** Chosen loading strategy, clear hierarchy, readable measure, stable line breaks, no overflow at any width. +- **Realistic state coverage.** Default, hover, focus-visible, active, disabled, loading, error, success, empty, overflow, long/short text, first-run. +- **Finished interaction quality.** Keyboard paths, touch targets, feedback timing, scroll behavior, state transitions, no hover-only functionality. +- **Coherent icon set.** Use the project's established set; otherwise pick one library or use accessible text. Don't mix. +- **Respect the build pipeline.** Edit source files and run the project's build (`npm run build` or equivalent). Don't write to `build/` / `dist/` / `.next/` with `cat`, heredoc, or Bash redirects; that skips asset hashing, image optimization, code splitting, and CSS extraction, and produces output the dev server won't serve. +- **Verify image URLs before referencing them.** Use image-search MCP or web-fetch when available; guessed photo IDs ship as broken-image placeholders. Without verification, prefer fewer images you're confident about. +- **Optimized imagery and media.** Correct dimensions, useful alt text, lazy loading below the fold, modern formats when practical, responsive `srcset`/`picture` for raster, no project-referenced asset left outside the workspace. +- **Premium motion.** Use atmospheric blur, filter, mask, shadow, reveal when they improve the experience. Avoid casual layout-property animation, bound expensive effects, verify smoothness in-browser, respect reduced motion, and avoid choreography that blocks task completion. +- **Maintainable.** Reusable local patterns, clear component boundaries, project conventions. No rasterized UI text or one-off hacks when a local pattern exists. +- **Technically clean.** Production build passes, no console errors, no avoidable layout shift, no needless dependencies, no broken asset paths. +- **Ask when uncertain.** If a discovery materially changes the brief or approved direction, stop and ask. Don't guess. -## Step 6: Browser-Based Iteration +## Step 6: Iterate Visually -**This step is critical.** Do not stop after the first implementation pass. +Look at what you built like a designer would. Your eyes are whatever the harness gives you: a connected browser, a screenshotting tool, Playwright, or asking the user. Use them for responsive testing (mobile, tablet, desktop minimum) and general visual validation. -Open the result in a browser. In Codex, use browser-use or equivalent browser automation when available; otherwise use Playwright or ask the user for screenshots. Inspect screenshots, not just DOM or terminal output. +If your tool returns a file path, read the PNG back into the conversation. A screenshot you didn't read doesn't count. -### Required viewport pass +For long-form brand surfaces, inspect major sections individually. Thumbnails hide spacing, clipping, and cascade defects. -Check the experience at the viewports that matter for the brief. Default minimum: +After the first pass, write an honest critique against the brief, the approved mock's major ingredients (hero silhouette, motifs, imagery, nav/CTA, density), and impeccable's DON'Ts. Patch material defects and re-inspect. **Don't invent defects to demonstrate iteration.** A confident "first pass clean, shipping" beats a fake fix. -- Mobile narrow -- Tablet or small laptop -- Desktop wide +Actively check: responsive behavior (composes, not shrinks), every state (empty / error / loading / edge), craft details (spacing, alignment, hierarchy, contrast, motion timing, focus), performance basics. The exit bar: defensible in a high-end studio review. -For each viewport, capture or inspect the rendered state and look for visual defects: overlap, clipping, weak hierarchy, off-grid alignment, awkward whitespace, cramped controls, unreadable type, broken imagery, hover-only functionality, layout shift, and text overflow. - -### Critique and fix loop - -After the first browser pass, write a short critique for yourself and patch the implementation. Repeat browser inspection after fixes. Continue until no material issues remain against this checklist: - -1. **Does it match the brief?** Compare the live result against every section of the design brief. Fix discrepancies. -2. **Does it match the approved mock?** Compare screenshots against the mock fidelity inventory: hero silhouette, major motifs, imagery, nav/CTA, section sequence, density, color/materials, and second-fold substance. Missing major ingredients are P0 defects. -3. **Does it pass the AI slop test?** If someone saw this and said "AI made this," would they believe it immediately? If yes, it needs more design intention. -4. **Check against impeccable's DON'T guidelines.** Fix any anti-pattern violations. -5. **Check every state.** Navigate through empty, error, loading, and edge case states. Each one should feel intentional, not like an afterthought. -6. **Check responsive behavior.** The design should adapt compositionally, not merely shrink. -7. **Check craft details.** Spacing consistency, optical alignment, type hierarchy, color contrast, image quality, icon coherence, interactive feedback, motion timing, and focus treatment. -8. **Check performance basics.** No obviously oversized images, avoidable layout thrash, blocking animations, or heavy assets without a reason. - -The exit bar is not "it works." It is: the rendered result looks intentional at all checked viewports, all expected states are handled, no placeholders remain unless explicitly accepted, and the implementation quality would be defensible in a high-end studio review. +Detector or QA output is defect evidence only; never proof the work is finished. ## Step 7: Present @@ -189,5 +153,3 @@ Present the result to the user: - Explain design decisions that connect back to the design brief and, when used, the chosen north-star mock. Include any accepted deviations from the mock; do not hide unimplemented mock ingredients. - Note any remaining limitations or follow-up risks honestly - Ask: "What's working? What isn't?" - -Iterate based on feedback. Good design is rarely right on the first pass. diff --git a/.gemini/skills/impeccable/reference/critique.md b/.gemini/skills/impeccable/reference/critique.md index 225badb88..0c63f1b7d 100644 --- a/.gemini/skills/impeccable/reference/critique.md +++ b/.gemini/skills/impeccable/reference/critique.md @@ -43,7 +43,7 @@ Run the bundled deterministic detector, which flags 27 specific patterns (AI slo **CLI scan**: ```bash -npx impeccable --json [--fast] [target] +npx impeccable detect --json [--fast] [target] ``` - Pass HTML/JSX/TSX/Vue/Svelte files or directories as `[target]` (anything with markup). Do not pass CSS-only files. diff --git a/.gemini/skills/impeccable/reference/polish.md b/.gemini/skills/impeccable/reference/polish.md index a2a409e48..eed3dbd27 100644 --- a/.gemini/skills/impeccable/reference/polish.md +++ b/.gemini/skills/impeccable/reference/polish.md @@ -2,6 +2,8 @@ Perform a meticulous final pass to catch all the small details that separate good work from great work. The difference between shipped and polished. +Detector and automated QA output are defect evidence only. A clean script result is never proof that the design is strong; gather browser evidence and inspect the real interaction path. + ## Design System Discovery Aligning the feature to the design system is **not optional**. Polish without alignment is decoration on top of drift, and it makes the next person's job harder. Discovery comes before any other polish work. @@ -216,11 +218,12 @@ Sweat the details. Zoom in until the alignment is right and the spacing reads as Before marking as done: -- **Use it yourself**: Actually interact with the feature -- **Test on real devices**: Not just browser DevTools -- **Ask someone else to review**: Fresh eyes catch things -- **Compare to design**: Match intended design -- **Check all states**: Don't just test happy path +- **Use it yourself**: Actually interact with the feature. +- **Test on real devices**: Not just browser DevTools. +- **Ask someone else to review**: Fresh eyes catch things. +- **Compare to design**: Match intended design. +- **Check all states**: Don't just test happy path. +- **Treat automation carefully**: Run detector or QA commands when they are available and relevant, fix their defects, but never cite a clean result as proof that the work is polished. ## Clean Up @@ -230,4 +233,3 @@ After polishing, ensure code quality: - **Remove orphaned code**: Delete unused styles, components, or files made obsolete by polish. - **Consolidate tokens**: If you introduced new values, check whether they should be tokens. - **Verify DRYness**: Look for duplication introduced during polishing and consolidate. - diff --git a/.gemini/skills/impeccable/reference/shape.md b/.gemini/skills/impeccable/reference/shape.md index 0785187ef..d1c983ff4 100644 --- a/.gemini/skills/impeccable/reference/shape.md +++ b/.gemini/skills/impeccable/reference/shape.md @@ -16,14 +16,16 @@ This is a required interaction, not optional guidance. Ask these questions in co ### Interview cadence -Discovery must include at least one user-answer round unless PRODUCT.md, DESIGN.md, or an already-confirmed brief directly answers the needed design inputs. With a sparse prompt, do **not** synthesize a complete brief for confirmation on the first response. +Discovery includes at least one user-answer round unless PRODUCT.md, DESIGN.md, or an already-confirmed brief directly answers the needed inputs. With a sparse prompt, do **not** synthesize a complete brief for confirmation on the first response. - Use the harness's structured question tool when one exists. Otherwise, ask directly in chat and stop. - Ask **2-3 questions per round**, then wait for answers. - Treat PRODUCT.md and DESIGN.md as anchors; they reduce repeated questions but do **not** replace shape for craft. Shape is task-specific. -- Round 1 should clarify purpose, audience/context, and success or emotional outcome. -- Round 2 should clarify content/data/states and scope/fidelity. -- Round 3 should clarify visual direction, constraints, and anti-goals when still unresolved. +- One round is the default. Add a second only if the first answers leave material gaps. Don't run a second round just to feel thorough. +- Round 1 should clarify purpose, audience/context, content/scope, and (for brand) visual direction. +- Round 2, when needed, fills in whatever's still genuinely missing. + +**Assert-then-confirm, not menu-with-escape.** When PRODUCT.md and the user's prompt make one option obvious, name it and ask the user to confirm or override. Don't enumerate "Restrained / Committed / Or something else?" as a real choice; "This reads as Restrained, confirm?" beats a four-option menu when the answer is already clear. ### Purpose & Context - What is this feature for? What problem does it solve? @@ -36,6 +38,7 @@ Discovery must include at least one user-answer round unless PRODUCT.md, DESIGN. - What are the realistic ranges? (Minimum, typical, maximum, e.g., 0 items, 5 items, 500 items) - What are the edge cases? (Empty state, error state, first-time use, power user) - Is any content dynamic? What changes and how often? +- What visual assets are real content here? Note required images, product shots, illustrations, maps, textures, diagrams, generated objects, or existing project assets. ### Design Direction @@ -72,9 +75,9 @@ After the discovery interview, generate a small set of visual direction probes * - The work is **net-new** or directionally ambiguous enough that visual exploration will clarify the brief. - The requested fidelity is **mid-fi, high-fi, or production-ready**. Skip for sketch-only planning. -- The current harness has **built-in image generation capability** (for example, Codex with a native image tool). Do **not** ask the user to set up external APIs, shell scripts, or one-off tooling just to do this. +- The current harness gives you native image generation (Codex's `image_gen`, an equivalent MCP tool, or similar). Don't ask the user to install APIs or tooling. -When those conditions are met, this step is mandatory for Codex and any harness with built-in image generation. Use native image generation; in Codex, use the built-in `image_gen` tool via the imagegen skill. If image generation is unavailable, do not ask the user to install APIs or tooling. State in one line that the image step is skipped because the harness lacks native image generation, then proceed. +When those conditions are met, this step is mandatory. If image generation isn't natively available, skip silently and proceed; don't announce the skip. Use probes to explore visual lanes, not to replace the brief. @@ -104,11 +107,20 @@ The probes should differ in primary visual direction (hierarchy, topology, densi - Do **not** treat generated imagery as final UX specification, final copy, or final accessibility behavior. - Do **not** use this step for minor refinements of existing work. It's for shaping a new surface or clarifying a big directional choice. -If image generation is unavailable, or the task doesn't benefit from it, skip this phase only with a one-line reason and proceed directly to the design brief. +If image generation isn't natively available, skip this phase silently and proceed. ## Phase 2: Design Brief -After the interview and any required probes, synthesize everything into a structured design brief. Present it to the user for explicit confirmation before considering this command complete. Stop after asking for confirmation; do not proceed to craft or implementation in the same response unless the user has already approved the brief. +After the interview and any required probes, present a brief and **end your response**. The user must confirm before any implementation runs. Do not present a brief and then continue to code in the same response, even if the brief feels obvious to you. The user's confirmation is the gate. + +**Choose the brief shape based on how clear the answers are:** + +- **Compact form (3-5 bullets)** when discovery was crisp and the original prompt + PRODUCT.md already pinned scope, content, and direction. State what you're building, the visual lane, and end with one or two specific questions or a clear "confirm or override?" prompt. This is the default for typical craft requests with a clear prompt. +- **Full structured form (sections below)** when the task is genuinely ambiguous, multi-screen, or when the user asked for shape as a standalone step. Use this when the discipline of structure earns its weight. + +Don't pad a clear brief into a long one to look thorough. A 70-line brief restating answers the user just gave is noise, not rigor. Equally, don't skip the confirmation pause to look efficient: the pause is the point. + +If the user already said "approved" or "go" during discovery for the *exact direction you'd present*, that counts as confirmation; you may proceed without asking again. But if your brief adds anything the user hasn't seen and approved, you must stop and confirm. ### Brief Structure @@ -136,16 +148,18 @@ List every state the feature needs: default, empty, loading, error, success, edg How users interact with this feature. What happens on click, hover, scroll? What feedback do they get? What's the flow from entry to completion? **8. Content Requirements** -What copy, labels, empty state messages, error messages, and microcopy are needed. Note any dynamic content and its realistic ranges. +What copy, labels, empty state messages, error messages, and microcopy are needed. Note any dynamic content and its realistic ranges. For image-led surfaces, also list the required image/media roles and their likely source (project asset, generated raster, semantic SVG/CSS, canvas/WebGL, icon library, or accepted omission). **9. Recommended References** Based on the brief, list which impeccable reference files would be most valuable during implementation (e.g., spatial-design.md for complex layouts, motion-design.md for animated features, interaction-design.md for form-heavy features). **10. Open Questions** -Anything unresolved that the implementer should resolve during build. +Anything genuinely unresolved. Don't list "open questions" you've already recommended a default for; assert the default and move on. If you'd write `Recommend: X` next to a question, just decide X. --- -ask the user directly to clarify what you cannot infer. Ask for explicit confirmation of the brief before finishing. If the user disagrees with any part, revisit the relevant discovery questions. A shape run is incomplete until the brief is confirmed. +ask the user directly to clarify what you cannot infer. + +If the user disagrees with any part, revisit the relevant discovery questions. A shape run is incomplete until the user confirms direction (or the user already gave a clear go during discovery, which counts). Once confirmed, the brief is complete. The user can now hand it to /impeccable, or use it to guide any other implementation approach. (If the user wants the full discovery-then-build flow in one step, they should use /impeccable craft instead, which runs this command internally.) diff --git a/.github/skills/impeccable/SKILL.md b/.github/skills/impeccable/SKILL.md index 011a492ac..c5fa7be37 100644 --- a/.github/skills/impeccable/SKILL.md +++ b/.github/skills/impeccable/SKILL.md @@ -9,28 +9,15 @@ license: Apache 2.0. Based on Anthropic's frontend-design skill. See NOTICE.md f Designs and iterates production-grade frontend interfaces. Real working code, committed design choices, exceptional craft. -## Setup (non-optional) +## Setup -Before any design work or file edits, pass these gates. Skipping them produces generic output that ignores the project. +Before any design work or file edits: -| 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. | +1. Load context (PRODUCT.md / DESIGN.md) via the loader script. +2. Identify the register and load the matching register reference (brand.md or product.md). +3. **If the user invoked a sub-command (e.g. `craft`, `shape`, `audit`), load its reference file too.** This is non-negotiable: `craft` without `craft.md` loaded means you'll skip the shape-and-confirm step the user expects. -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: 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. +Skipping these produces generic output that ignores the project. ### 1. Context gathering diff --git a/.github/skills/impeccable/reference/brand.md b/.github/skills/impeccable/reference/brand.md index b069f2553..3d83a1cdc 100644 --- a/.github/skills/impeccable/reference/brand.md +++ b/.github/skills/impeccable/reference/brand.md @@ -12,6 +12,8 @@ Brand isn't a neutral register. AI-generated landing pages have flooded the inte **The second slop test: aesthetic lane.** Before committing to moves, name the reference. A Klim-style specimen page is one lane; Stripe-minimal is another; Liquid-Death-acid-maximalism is another. Don't drift into editorial-magazine aesthetics on a brief that isn't editorial. A hiking brand with Cormorant italic drop caps has the wrong register within the register. +Then the inverse test: in one sentence, describe what you're about to build the way a competitor would describe theirs. If that sentence fits the modal landing page in the category, restart. + ## Typography ### Font selection procedure @@ -66,6 +68,7 @@ Brand surfaces have permission for Committed, Full palette, and Drenched strateg - Palette IS voice. A calm brand and a restless brand should not share palette mechanics. - When the strategy is Committed or Drenched, color carries the brand. Don't hedge with neutrals around the edges. Commit. - Don't converge across projects. If the last brand surface was restrained-on-cream, this one is not. +- When a cultural-symbol palette is the obvious pull, reach past it. Let the cultural reading come from typography, imagery, and copy, not the palette. ## Layout @@ -79,14 +82,14 @@ Brand surfaces have permission for Committed, Full palette, and Drenched strateg Brand surfaces lean on imagery. A restaurant, hotel, magazine, or product landing page without any imagery reads as incomplete, not as restrained. A solid-color rectangle where a hero image should go is worse than a representative stock photo. -**When the brief implies imagery (restaurants, hotels, magazines, photography, hobbyist communities, food, travel, fashion, product), you must ship imagery.** Zero images is a bug, not a design choice. "Restraint" is not an excuse. +**When the brief implies imagery (restaurants, hotels, magazines, photography, hobbyist communities, food, travel, fashion, product), you must ship imagery.** Zero images is a bug, not a design choice. "Restraint" is not an excuse. If the approved comp or brief is image-led, ship real project assets, generated raster assets, or a credible canvas/SVG/WebGL scene. Do not replace photographic, architectural, product, or place imagery with generic CSS panels, decorative diagrams, cards, bullets, or copy. -- **For greenfield work without local assets, use stock imagery.** Unsplash is the default. The URL shape is `https://images.unsplash.com/photo-{id}?auto=format&fit=crop&w=1600&q=80`. Pick real Unsplash photo IDs you're confident exist (`photo-1559339352-11d035aa65de`, `photo-1590490360182-c33d57733427`, etc.); if unsure, pick fewer photos but don't substitute colored `
` placeholders. +- **For greenfield work without local assets, use stock imagery.** Unsplash is the default. The URL shape is `https://images.unsplash.com/photo-{id}?auto=format&fit=crop&w=1600&q=80`. **Verify the URLs before referencing them.** If you have an image-search MCP, web-fetch tool, or browser access, use it to find real photo IDs and confirm they resolve. Guessed IDs (even ones that look real) often 404 and ship as broken-image placeholders. Without a verification path, pick fewer photos you're confident exist over more that you guessed; never substitute colored `
` placeholders. - **Search for the brand's physical object**, not the generic category: "handmade pasta on a scratched wooden table" beats "Italian food"; "cypress trees above a limestone hotel facade at dusk" beats "luxury hotel". - **One decisive photo beats five mediocre ones.** Hero imagery should commit to a mood; padding with more stock doesn't rescue an indecisive one. - **Alt text is part of the voice.** "Coastal fettuccine, hand-cut, served on the terrace" beats "pasta dish". -Tech / dev-tool brands are the exception where zero imagery can be correct; a developer landing page often carries its voice through typography, code samples, diagrams. Know which kind of brand you're working on. +"Imagery" here is broader than stock photography: product screenshots, custom data visualizations, generated SVG, and canvas/WebGL scenes are all imagery. Text-only pages where typography alone carries the entire visual weight are the failure mode. ## Motion @@ -102,6 +105,7 @@ Tech / dev-tool brands are the exception where zero imagery can be correct; a de - Timid palettes and average layouts. Safe = invisible. - Zero imagery on a brief that implies imagery (restaurant, hotel, food, travel, fashion, photography, hobbyist). Colored blocks where a hero photo belongs. - Defaulting to editorial-magazine aesthetics (display serif + italic + drop caps + broadsheet grid) on briefs that aren't magazine-shaped. Editorial is ONE aesthetic lane, not the default brand aesthetic. +- Repeated tiny uppercase tracked labels above every section heading. A single strong kicker can be voice; repeating it as section grammar is AI scaffolding unless it's a deliberate, named brand system. ## Brand permissions diff --git a/.github/skills/impeccable/reference/craft.md b/.github/skills/impeccable/reference/craft.md index bdeee0294..c0cfa7460 100644 --- a/.github/skills/impeccable/reference/craft.md +++ b/.github/skills/impeccable/reference/craft.md @@ -1,43 +1,41 @@ # Craft Flow -Build a feature with impeccable UX and UI quality through a structured process: shape the design, land the visual direction, build real production code, then inspect and improve in-browser until the result meets a high-end studio bar. +Build a feature with impeccable UX and UI quality: shape the design, land the visual direction, build real production code, inspect and improve in-browser until it meets a high-end studio bar. -## Build Gate +Before writing code, you need: PRODUCT.md loaded, register identified and the matching reference loaded, and a confirmed design direction for this task (either from `shape` or supplied by the user). PRODUCT.md is project context, not a task-specific brief. -Craft cannot build until all of these are true: +Treat any approved visual direction (generated mock or stated reference) as a concrete contract for composition, hierarchy, density, atmosphere, signature motifs, and distinctive visual moves. Don't let mocks replace structure, copy, accessibility, or state design. But if the live result lacks the approved direction's major ingredients, the implementation is wrong. -1. PRODUCT context is valid and current. -2. The shape design brief is explicitly confirmed by the user for this task, unless the user already provided a confirmed brief. -3. Implementation references from the brief are loaded. -4. The shape visual probe decision is recorded: generated, skipped with reason, or already resolved. -5. The north-star mock decision is recorded: generated, skipped with reason, or not applicable. +## Step 0: Project Foundation -PRODUCT.md and `teach` answers do **not** satisfy the shape gate. They are project context only. A compact self-authored brief does not satisfy the shape gate either. `shape=pass` requires a separate user response approving the shape brief or an already-confirmed brief supplied by the user. +Before shape, before code: figure out what kind of project you're working in. -Invalid image-skip reasons include: "the final implementation will be semantic HTML/CSS/SVG", "the diagram should stay editable", "a raster mock would not be used directly", or "the product is fictional." Generated probes and mocks are direction artifacts; they are not implementation assets. +Look at the working directory. Run `ls`. Check for: -## Craft Contract +- An existing framework: `astro.config.mjs/ts`, `next.config.js/ts`, `nuxt.config.ts`, `svelte.config.js`, `vite.config.js/ts`, `package.json` with framework deps, `Cargo.toml` + Leptos/Yew, `Gemfile` + Rails. **If found, use it.** Do not start a parallel build, do not introduce a second framework, do not write to `dist/` or `build/` directly. Whatever pipeline the project has, respect it. +- An existing component library or design system: `src/components/`, `app/components/`, a `tokens.css` / `theme.ts`, an `astro.config` `integrations`. Read what's there before adding to it. +- An existing icon set: `lucide-react`, `@phosphor-icons/react`, `@iconify/*`, hand-rolled SVG sprites in `assets/icons/`. **Use what's already in the project**; don't introduce a second set. -Craft is not a first pass. It is a loop with these required artifacts: +If the directory is empty (greenfield), don't pick a framework silently. Ask the user via the AskUserQuestion tool, with sensible defaults framed by the brief: -1. Confirmed design brief from `shape`. -2. Approved visual direction, from generated probes / mocks when image generation is available. -3. Mock fidelity inventory: the visible ingredients from the approved direction that must survive into code. -4. Semantic, functional implementation using the project's real stack and conventions. -5. Browser evidence across relevant viewports. -6. At least one critique-and-fix pass after the first browser inspection, unless the first pass has no material defects. +```text +What should this be built on? + - Astro (default for content-led brand sites, landing pages, marketing surfaces) + - SvelteKit / Next.js / Nuxt (when the brief implies an app surface or significant interactivity) + - Single index.html (one-shot demo, prototype, or a deliberately framework-free experiment) +``` -Do not let generated mockups replace interface structure, copy, accessibility, responsive behavior, or state design. But do treat the approved mock as a concrete visual contract for composition, hierarchy, density, atmosphere, signature motifs, image needs, and distinctive visual moves. "North star" means "preserve the important visible ingredients in semantic code," not "use it as loose mood." +Default: Astro for brand briefs, the project's existing framework for product briefs. Ask once; don't re-ask mid-task. ## Step 1: Shape the Design -Run /impeccable shape, passing along whatever feature description the user provided. +Run /impeccable shape, passing along whatever feature description the user provided. Shape is **required** for craft; it is what produces a confirmed direction. -Wait for the design brief to be fully confirmed by the user before proceeding. The brief is your blueprint, and every implementation decision should trace back to it. +Present the shape output and stop. Wait for the user to confirm, override, or course-correct before writing code. -If this craft run resumed after `teach` created PRODUCT.md, run shape now. Do not treat the teach interview, PRODUCT.md, or a summary of project context as a substitute for shape. Shape is task-specific and must cover scope, content/states, visual direction, constraints, anti-goals, probes when applicable, and explicit brief confirmation. +If the user already supplied a confirmed brief or ran shape separately, use it and skip this step. -If the user has already run /impeccable shape and has a confirmed design brief, skip this step and use the existing brief. +When the original prompt + PRODUCT.md already answer scope, content, and visual direction with no real ambiguity, the shape output can be **compact** (3-5 bullets stating what you're building and the visual lane, ending with one or two specific questions or "confirm or override"). The full 10-section structured brief is reserved for genuinely ambiguous, multi-screen, or stakeholder-heavy tasks. Don't pad a clear brief into a long one to look thorough; equally, don't skip the pause to look efficient. ## Step 2: Load References @@ -55,79 +53,60 @@ Then add references based on the brief's needs: ## Step 3: Land the Visual Direction (Capability-Gated) -Before implementation, generate high-fidelity visual comps when all of these are true: +Generate high-fidelity visual comps before implementation when all three are true: -- The work is **net-new** or visually open-ended enough that composition exploration will improve the build. -- The brief's scope is **mid-fi, high-fi, or production-ready**. -- The current harness has **built-in image generation capability** (for example, Codex with a native image tool). Do **not** ask the user to set up external APIs, shell scripts, or one-off tooling just to do this. +- The work is net-new or visually open-ended enough that composition exploration will improve the build. +- The brief's scope is mid-fi, high-fi, or production-ready. +- The harness gives you native image generation (Codex's `image_gen`, an equivalent MCP tool). Don't ask the user to set up external APIs. -When those conditions are met, this step is mandatory for **both brand and product work** in Codex and any harness with built-in image generation. Use native image generation; in Codex, use the built-in `image_gen` tool via the imagegen skill. If image generation is unavailable, do not ask the user to install APIs or tooling. State in one line that the image step is skipped because the harness lacks native image generation, then proceed. - -Do not skip this step because the eventual UI should be semantic, editable, code-native, responsive, or accessible. Those are implementation requirements, not reasons to avoid visual exploration. - -### Purpose - -Use the mock step to find a stronger visual lane than code-first generation would reliably discover on its own. The brief remains authoritative on user, purpose, content, constraints, states, and anti-goals. The mock clarifies composition, hierarchy, density, typography, and visual tone. +When met, this step is mandatory for both brand and product work. If image generation isn't available, skip silently. "The eventual UI is semantic/code-native/accessible" is not a reason to skip; those are implementation requirements, not exploration ones. ### What to generate -Generate **1 to 3** high-fidelity north-star comps based on the confirmed brief. If shape already produced direction probes, use those results as input and generate a more resolved mock from the winning lane, not another unrelated exploration. +Generate **1 to 3** high-fidelity north-star comps from the confirmed brief. If shape already produced direction probes, resolve the winning lane further, not an unrelated exploration. Comps must differ in primary visual direction, not just color. -- For brand work, push visual identity, composition, and mood aggressively. -- For product work, still push hierarchy, topology, density, and tone, but keep the comps grounded in realistic product structure and states. -- For landing pages and long-form brand surfaces, show enough of the next section or second fold to establish the system beyond the hero. - -The comps must be genuinely different in primary visual direction, not just color variants. +- Brand work: push visual identity, composition, and mood aggressively. +- Product work: push hierarchy, topology, density, tone, grounded in realistic product structure. +- Landing pages and long-form brand surfaces: show enough of the second fold to establish the system beyond the hero. ### Approval loop -Show the comps and ask what should carry forward. If the user asks for changes or the best direction is still weak, generate a focused revision before implementation. Continue until one direction is approved, or until the user explicitly delegates the choice. +Show the comps and ask what carries forward. Iterate until one direction is approved or the user delegates. If the user delegates, pick the strongest direction and explain it from the brief, not personal taste. -If the user delegates, pick the strongest direction and explain the decision using the brief, not personal taste. - -Before moving to implementation, summarize: - -- What to carry into code -- What **not** to literalize from the mock - -This summary is required before Step 4. It is the handoff between visual exploration and semantic implementation. +Before Step 4, summarize what to carry into code and what **not** to literalize from the mock. This is the handoff between visual exploration and semantic implementation. ### Mock fidelity inventory -Before building, inventory the approved mock's major visible ingredients: +Inventory the approved mock's major visible ingredients: -- Hero silhouette and dominant composition. -- Signature motifs: planets, devices, portraits, charts, route lines, insets, badges, or other memorable objects. -- Nav and primary CTA treatment. -- Section sequence visible in the mock, especially the second fold. -- Image-native content the concept depends on. -- Typography, density, color/material treatment, and motion cues. +- Hero silhouette and dominant composition +- Signature motifs (planets, devices, portraits, charts, route lines, insets, badges, etc.) +- Nav and primary CTA treatment +- Section sequence, especially the second fold +- Image-native content the concept depends on +- Typography, density, color/material treatment, motion cues -For each ingredient, decide how it will be implemented: semantic HTML/CSS/SVG, generated asset, sourced project asset, icon library, canvas/WebGL, or an explicitly accepted omission. Do not substitute a different hero composition or new visual driver after approval unless the user approves the change. +For each, decide implementation: semantic HTML/CSS/SVG, generated asset, sourced asset, icon library, canvas/WebGL, or accepted omission. Don't substitute a different hero composition or visual driver post-approval without user sign-off. -Treat the mock as a **north star**, not a screenshot to trace. Do **not** rasterize core UI text or let the mock override the confirmed brief. But if the live result lacks the mock's major visible ingredients, the implementation is wrong. +If a photographic, architectural, product, or place-led mock becomes generic CSS scenery / decorative diagrams / bullets / copy, stop and fix it. That's a broken implementation, not a harmless interpretation. + +Treat the mock as a north star, not a screenshot to trace. Don't rasterize core UI text. But if the live result lacks the mock's major ingredients, the implementation is wrong. ## Step 4: Asset Extraction (Need-Gated) -If the chosen direction includes image-native visual ingredients that would materially improve the implementation, generate them as separate assets before building. +If the approved direction needs raster assets, create them before building. Do not replace required imagery with generic cards, bullets, emoji, fake metrics, decorative CSS panels, or filler copy. -Good candidates: +Use the native asset producer (`impeccable_asset_producer` in Codex, `impeccable-asset-producer` in Claude Code) to create clean assets from the hi-fi mock and crops. If you do not have explicit permission to use agents, stop and ask: -- stickers -- badges -- seals -- tickets -- graphic labels -- textures -- abstract objects -- decorative marks -- non-semantic scene elements +```text +Asset production will work better as a scoped subagent job. Should I spawn the Impeccable asset producer subagent for this step? +``` -For travel, editorial, portfolio, venue, product showcase, entertainment, education, or any other image-led brand surface, visual assets are usually core content, not decoration. Do not ship abstract CSS panels where the approved mock or subject matter calls for real imagery, generated plates, illustrations, maps, product/object renders, or destination scenes. +Do not skip asset production or silently do it inline. Inline asset production is allowed only if the user declines subagents, the harness cannot spawn the authorized agent, or the user explicitly asks for single-thread mode. -Do **not** export assets for core UI text, navigation, body copy, or any structure that should stay semantic and editable in code. +Pass the approved mock, crop/contact-sheet paths, output directory, dimensions/formats, transparency needs, constraints, and avoid list to the asset producer. Attach image generation capability to the spawned agent when the harness supports it; do not load image-generation reference material into the parent thread first. -Usually **1 to 5** extracted assets is enough. If the design can be built cleanly in HTML/CSS/SVG, prefer that over raster assets. If the mock contains major visual content that cannot be built credibly in code, asset extraction is not optional. +Prefer HTML/CSS/SVG/canvas when they can credibly reproduce an ingredient; use real/generated/stock imagery when the mock or subject matter calls for actual visual content. ## Step 5: Build to Production Quality @@ -135,50 +114,35 @@ Implement the feature following the design brief. Build in passes so structure, ### Production bar -- Use real or realistic content. Remove placeholder copy, placeholder images, dead links, fake controls, and unused scaffold before presenting. -- Preserve the approved mock's major ingredients. Missing hero objects, missing world/product imagery, different section structure, downgraded CTA/nav treatment, or generic replacements for distinctive motifs are blocking defects unless the user accepted the change. -- Build semantically first: real headings, landmarks, labels, form associations, button/link semantics, accessible names, and state announcements where needed. -- Calibrate spacing, alignment, grid placement, and vertical rhythm deliberately. Do not accept default gaps, arbitrary margins, unbalanced whitespace, or accidental optical misalignment. -- Make typography intentional: chosen font loading strategy, clear hierarchy, readable measure, stable line breaks, tuned wrapping, and no overflow at mobile or large desktop sizes. -- Design realistic state coverage: default, hover where supported, focus-visible, active, disabled, loading, error, success, empty, overflow, long text, short text, and first-run states where relevant. -- Make interaction quality feel finished: keyboard paths, touch targets, feedback timing, scroll behavior, transitions between states, and no hover-only functionality. -- Use icons from the project's established icon set when available. If no set exists, choose a coherent library or use accessible text controls; do not mix unrelated icon styles. -- Optimize imagery and media: correct dimensions, useful alt text, lazy loading below the fold, modern formats when practical, responsive `srcset` / `picture` for raster assets, and no project-referenced asset left outside the workspace. -- Make motion feel premium: use atmospheric blur, filter, mask, shadow, or reveal effects when they improve the experience; avoid casual layout-property animation, bound expensive effects, verify smoothness in-browser, respect reduced motion, and avoid choreography that blocks task completion. -- Preserve maintainability: reusable local patterns, clear component boundaries, project conventions, no rasterized UI text, and no hard-coded one-off hacks when a better local pattern exists. -- Fit the technical context: production build passes, no obvious console errors, no avoidable layout shift, no needless dependency, and no broken asset path. -- If you discover a design question that materially changes the brief or approved direction, stop and ask rather than guessing. +- **Real content.** No placeholder copy, placeholder images, dead links, fake controls, or unused scaffold at presentation time. +- **Preserve the approved mock's major ingredients.** Missing hero objects, world/product imagery, section structure, CTA/nav treatment, or distinctive motifs are blocking defects unless the user accepted the change. +- **Semantic first.** Real headings, landmarks, labels, form associations, button/link semantics, accessible names, state announcements where needed. +- **Deliberate spacing and alignment.** No default gaps, arbitrary margins, unbalanced whitespace, or accidental optical misalignment. +- **Intentional typography.** Chosen loading strategy, clear hierarchy, readable measure, stable line breaks, no overflow at any width. +- **Realistic state coverage.** Default, hover, focus-visible, active, disabled, loading, error, success, empty, overflow, long/short text, first-run. +- **Finished interaction quality.** Keyboard paths, touch targets, feedback timing, scroll behavior, state transitions, no hover-only functionality. +- **Coherent icon set.** Use the project's established set; otherwise pick one library or use accessible text. Don't mix. +- **Respect the build pipeline.** Edit source files and run the project's build (`npm run build` or equivalent). Don't write to `build/` / `dist/` / `.next/` with `cat`, heredoc, or Bash redirects; that skips asset hashing, image optimization, code splitting, and CSS extraction, and produces output the dev server won't serve. +- **Verify image URLs before referencing them.** Use image-search MCP or web-fetch when available; guessed photo IDs ship as broken-image placeholders. Without verification, prefer fewer images you're confident about. +- **Optimized imagery and media.** Correct dimensions, useful alt text, lazy loading below the fold, modern formats when practical, responsive `srcset`/`picture` for raster, no project-referenced asset left outside the workspace. +- **Premium motion.** Use atmospheric blur, filter, mask, shadow, reveal when they improve the experience. Avoid casual layout-property animation, bound expensive effects, verify smoothness in-browser, respect reduced motion, and avoid choreography that blocks task completion. +- **Maintainable.** Reusable local patterns, clear component boundaries, project conventions. No rasterized UI text or one-off hacks when a local pattern exists. +- **Technically clean.** Production build passes, no console errors, no avoidable layout shift, no needless dependencies, no broken asset paths. +- **Ask when uncertain.** If a discovery materially changes the brief or approved direction, stop and ask. Don't guess. -## Step 6: Browser-Based Iteration +## Step 6: Iterate Visually -**This step is critical.** Do not stop after the first implementation pass. +Look at what you built like a designer would. Your eyes are whatever the harness gives you: a connected browser, a screenshotting tool, Playwright, or asking the user. Use them for responsive testing (mobile, tablet, desktop minimum) and general visual validation. -Open the result in a browser. In Codex, use browser-use or equivalent browser automation when available; otherwise use Playwright or ask the user for screenshots. Inspect screenshots, not just DOM or terminal output. +If your tool returns a file path, read the PNG back into the conversation. A screenshot you didn't read doesn't count. -### Required viewport pass +For long-form brand surfaces, inspect major sections individually. Thumbnails hide spacing, clipping, and cascade defects. -Check the experience at the viewports that matter for the brief. Default minimum: +After the first pass, write an honest critique against the brief, the approved mock's major ingredients (hero silhouette, motifs, imagery, nav/CTA, density), and impeccable's DON'Ts. Patch material defects and re-inspect. **Don't invent defects to demonstrate iteration.** A confident "first pass clean, shipping" beats a fake fix. -- Mobile narrow -- Tablet or small laptop -- Desktop wide +Actively check: responsive behavior (composes, not shrinks), every state (empty / error / loading / edge), craft details (spacing, alignment, hierarchy, contrast, motion timing, focus), performance basics. The exit bar: defensible in a high-end studio review. -For each viewport, capture or inspect the rendered state and look for visual defects: overlap, clipping, weak hierarchy, off-grid alignment, awkward whitespace, cramped controls, unreadable type, broken imagery, hover-only functionality, layout shift, and text overflow. - -### Critique and fix loop - -After the first browser pass, write a short critique for yourself and patch the implementation. Repeat browser inspection after fixes. Continue until no material issues remain against this checklist: - -1. **Does it match the brief?** Compare the live result against every section of the design brief. Fix discrepancies. -2. **Does it match the approved mock?** Compare screenshots against the mock fidelity inventory: hero silhouette, major motifs, imagery, nav/CTA, section sequence, density, color/materials, and second-fold substance. Missing major ingredients are P0 defects. -3. **Does it pass the AI slop test?** If someone saw this and said "AI made this," would they believe it immediately? If yes, it needs more design intention. -4. **Check against impeccable's DON'T guidelines.** Fix any anti-pattern violations. -5. **Check every state.** Navigate through empty, error, loading, and edge case states. Each one should feel intentional, not like an afterthought. -6. **Check responsive behavior.** The design should adapt compositionally, not merely shrink. -7. **Check craft details.** Spacing consistency, optical alignment, type hierarchy, color contrast, image quality, icon coherence, interactive feedback, motion timing, and focus treatment. -8. **Check performance basics.** No obviously oversized images, avoidable layout thrash, blocking animations, or heavy assets without a reason. - -The exit bar is not "it works." It is: the rendered result looks intentional at all checked viewports, all expected states are handled, no placeholders remain unless explicitly accepted, and the implementation quality would be defensible in a high-end studio review. +Detector or QA output is defect evidence only; never proof the work is finished. ## Step 7: Present @@ -189,5 +153,3 @@ Present the result to the user: - Explain design decisions that connect back to the design brief and, when used, the chosen north-star mock. Include any accepted deviations from the mock; do not hide unimplemented mock ingredients. - Note any remaining limitations or follow-up risks honestly - Ask: "What's working? What isn't?" - -Iterate based on feedback. Good design is rarely right on the first pass. diff --git a/.github/skills/impeccable/reference/critique.md b/.github/skills/impeccable/reference/critique.md index 39028f39a..abb442146 100644 --- a/.github/skills/impeccable/reference/critique.md +++ b/.github/skills/impeccable/reference/critique.md @@ -43,7 +43,7 @@ Run the bundled deterministic detector, which flags 27 specific patterns (AI slo **CLI scan**: ```bash -npx impeccable --json [--fast] [target] +npx impeccable detect --json [--fast] [target] ``` - Pass HTML/JSX/TSX/Vue/Svelte files or directories as `[target]` (anything with markup). Do not pass CSS-only files. diff --git a/.github/skills/impeccable/reference/polish.md b/.github/skills/impeccable/reference/polish.md index a2a409e48..eed3dbd27 100644 --- a/.github/skills/impeccable/reference/polish.md +++ b/.github/skills/impeccable/reference/polish.md @@ -2,6 +2,8 @@ Perform a meticulous final pass to catch all the small details that separate good work from great work. The difference between shipped and polished. +Detector and automated QA output are defect evidence only. A clean script result is never proof that the design is strong; gather browser evidence and inspect the real interaction path. + ## Design System Discovery Aligning the feature to the design system is **not optional**. Polish without alignment is decoration on top of drift, and it makes the next person's job harder. Discovery comes before any other polish work. @@ -216,11 +218,12 @@ Sweat the details. Zoom in until the alignment is right and the spacing reads as Before marking as done: -- **Use it yourself**: Actually interact with the feature -- **Test on real devices**: Not just browser DevTools -- **Ask someone else to review**: Fresh eyes catch things -- **Compare to design**: Match intended design -- **Check all states**: Don't just test happy path +- **Use it yourself**: Actually interact with the feature. +- **Test on real devices**: Not just browser DevTools. +- **Ask someone else to review**: Fresh eyes catch things. +- **Compare to design**: Match intended design. +- **Check all states**: Don't just test happy path. +- **Treat automation carefully**: Run detector or QA commands when they are available and relevant, fix their defects, but never cite a clean result as proof that the work is polished. ## Clean Up @@ -230,4 +233,3 @@ After polishing, ensure code quality: - **Remove orphaned code**: Delete unused styles, components, or files made obsolete by polish. - **Consolidate tokens**: If you introduced new values, check whether they should be tokens. - **Verify DRYness**: Look for duplication introduced during polishing and consolidate. - diff --git a/.github/skills/impeccable/reference/shape.md b/.github/skills/impeccable/reference/shape.md index 0785187ef..d1c983ff4 100644 --- a/.github/skills/impeccable/reference/shape.md +++ b/.github/skills/impeccable/reference/shape.md @@ -16,14 +16,16 @@ This is a required interaction, not optional guidance. Ask these questions in co ### Interview cadence -Discovery must include at least one user-answer round unless PRODUCT.md, DESIGN.md, or an already-confirmed brief directly answers the needed design inputs. With a sparse prompt, do **not** synthesize a complete brief for confirmation on the first response. +Discovery includes at least one user-answer round unless PRODUCT.md, DESIGN.md, or an already-confirmed brief directly answers the needed inputs. With a sparse prompt, do **not** synthesize a complete brief for confirmation on the first response. - Use the harness's structured question tool when one exists. Otherwise, ask directly in chat and stop. - Ask **2-3 questions per round**, then wait for answers. - Treat PRODUCT.md and DESIGN.md as anchors; they reduce repeated questions but do **not** replace shape for craft. Shape is task-specific. -- Round 1 should clarify purpose, audience/context, and success or emotional outcome. -- Round 2 should clarify content/data/states and scope/fidelity. -- Round 3 should clarify visual direction, constraints, and anti-goals when still unresolved. +- One round is the default. Add a second only if the first answers leave material gaps. Don't run a second round just to feel thorough. +- Round 1 should clarify purpose, audience/context, content/scope, and (for brand) visual direction. +- Round 2, when needed, fills in whatever's still genuinely missing. + +**Assert-then-confirm, not menu-with-escape.** When PRODUCT.md and the user's prompt make one option obvious, name it and ask the user to confirm or override. Don't enumerate "Restrained / Committed / Or something else?" as a real choice; "This reads as Restrained, confirm?" beats a four-option menu when the answer is already clear. ### Purpose & Context - What is this feature for? What problem does it solve? @@ -36,6 +38,7 @@ Discovery must include at least one user-answer round unless PRODUCT.md, DESIGN. - What are the realistic ranges? (Minimum, typical, maximum, e.g., 0 items, 5 items, 500 items) - What are the edge cases? (Empty state, error state, first-time use, power user) - Is any content dynamic? What changes and how often? +- What visual assets are real content here? Note required images, product shots, illustrations, maps, textures, diagrams, generated objects, or existing project assets. ### Design Direction @@ -72,9 +75,9 @@ After the discovery interview, generate a small set of visual direction probes * - The work is **net-new** or directionally ambiguous enough that visual exploration will clarify the brief. - The requested fidelity is **mid-fi, high-fi, or production-ready**. Skip for sketch-only planning. -- The current harness has **built-in image generation capability** (for example, Codex with a native image tool). Do **not** ask the user to set up external APIs, shell scripts, or one-off tooling just to do this. +- The current harness gives you native image generation (Codex's `image_gen`, an equivalent MCP tool, or similar). Don't ask the user to install APIs or tooling. -When those conditions are met, this step is mandatory for Codex and any harness with built-in image generation. Use native image generation; in Codex, use the built-in `image_gen` tool via the imagegen skill. If image generation is unavailable, do not ask the user to install APIs or tooling. State in one line that the image step is skipped because the harness lacks native image generation, then proceed. +When those conditions are met, this step is mandatory. If image generation isn't natively available, skip silently and proceed; don't announce the skip. Use probes to explore visual lanes, not to replace the brief. @@ -104,11 +107,20 @@ The probes should differ in primary visual direction (hierarchy, topology, densi - Do **not** treat generated imagery as final UX specification, final copy, or final accessibility behavior. - Do **not** use this step for minor refinements of existing work. It's for shaping a new surface or clarifying a big directional choice. -If image generation is unavailable, or the task doesn't benefit from it, skip this phase only with a one-line reason and proceed directly to the design brief. +If image generation isn't natively available, skip this phase silently and proceed. ## Phase 2: Design Brief -After the interview and any required probes, synthesize everything into a structured design brief. Present it to the user for explicit confirmation before considering this command complete. Stop after asking for confirmation; do not proceed to craft or implementation in the same response unless the user has already approved the brief. +After the interview and any required probes, present a brief and **end your response**. The user must confirm before any implementation runs. Do not present a brief and then continue to code in the same response, even if the brief feels obvious to you. The user's confirmation is the gate. + +**Choose the brief shape based on how clear the answers are:** + +- **Compact form (3-5 bullets)** when discovery was crisp and the original prompt + PRODUCT.md already pinned scope, content, and direction. State what you're building, the visual lane, and end with one or two specific questions or a clear "confirm or override?" prompt. This is the default for typical craft requests with a clear prompt. +- **Full structured form (sections below)** when the task is genuinely ambiguous, multi-screen, or when the user asked for shape as a standalone step. Use this when the discipline of structure earns its weight. + +Don't pad a clear brief into a long one to look thorough. A 70-line brief restating answers the user just gave is noise, not rigor. Equally, don't skip the confirmation pause to look efficient: the pause is the point. + +If the user already said "approved" or "go" during discovery for the *exact direction you'd present*, that counts as confirmation; you may proceed without asking again. But if your brief adds anything the user hasn't seen and approved, you must stop and confirm. ### Brief Structure @@ -136,16 +148,18 @@ List every state the feature needs: default, empty, loading, error, success, edg How users interact with this feature. What happens on click, hover, scroll? What feedback do they get? What's the flow from entry to completion? **8. Content Requirements** -What copy, labels, empty state messages, error messages, and microcopy are needed. Note any dynamic content and its realistic ranges. +What copy, labels, empty state messages, error messages, and microcopy are needed. Note any dynamic content and its realistic ranges. For image-led surfaces, also list the required image/media roles and their likely source (project asset, generated raster, semantic SVG/CSS, canvas/WebGL, icon library, or accepted omission). **9. Recommended References** Based on the brief, list which impeccable reference files would be most valuable during implementation (e.g., spatial-design.md for complex layouts, motion-design.md for animated features, interaction-design.md for form-heavy features). **10. Open Questions** -Anything unresolved that the implementer should resolve during build. +Anything genuinely unresolved. Don't list "open questions" you've already recommended a default for; assert the default and move on. If you'd write `Recommend: X` next to a question, just decide X. --- -ask the user directly to clarify what you cannot infer. Ask for explicit confirmation of the brief before finishing. If the user disagrees with any part, revisit the relevant discovery questions. A shape run is incomplete until the brief is confirmed. +ask the user directly to clarify what you cannot infer. + +If the user disagrees with any part, revisit the relevant discovery questions. A shape run is incomplete until the user confirms direction (or the user already gave a clear go during discovery, which counts). Once confirmed, the brief is complete. The user can now hand it to /impeccable, or use it to guide any other implementation approach. (If the user wants the full discovery-then-build flow in one step, they should use /impeccable craft instead, which runs this command internally.) diff --git a/.gitignore b/.gitignore index 0dc0fa336..6a4b1356e 100644 --- a/.gitignore +++ b/.gitignore @@ -66,6 +66,9 @@ extension/detector/ evals/ tests/evals-v2/ +# Video backlog & scripts (local working files, not for distribution) +videos/ + # Generated sub-pages (legacy, now replaced by Astro content collections) site/public/docs/ site/public/anti-patterns/ @@ -86,7 +89,9 @@ site/public/js/generated/ # time, and they enable clean submodule use. Run `bun run build` to refresh # them after editing skill/. # -# Codex CLI consumes `.agents/skills/`; `.codex/` is not used. Ignore it so -# local artifacts or old trees are never committed. -.codex/ +# Codex CLI consumes `.agents/skills/`; native custom agents live under +# `.codex/agents/`. Keep only those agent definitions tracked. +.codex/* +!.codex/agents/ +!.codex/agents/** .astro/ diff --git a/.kiro/skills/impeccable/SKILL.md b/.kiro/skills/impeccable/SKILL.md index 3d69b6358..482250f18 100644 --- a/.kiro/skills/impeccable/SKILL.md +++ b/.kiro/skills/impeccable/SKILL.md @@ -7,28 +7,15 @@ license: Apache 2.0. Based on Anthropic's frontend-design skill. See NOTICE.md f Designs and iterates production-grade frontend interfaces. Real working code, committed design choices, exceptional craft. -## Setup (non-optional) +## Setup -Before any design work or file edits, pass these gates. Skipping them produces generic output that ignores the project. +Before any design work or file edits: -| 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. | +1. Load context (PRODUCT.md / DESIGN.md) via the loader script. +2. Identify the register and load the matching register reference (brand.md or product.md). +3. **If the user invoked a sub-command (e.g. `craft`, `shape`, `audit`), load its reference file too.** This is non-negotiable: `craft` without `craft.md` loaded means you'll skip the shape-and-confirm step the user expects. -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: 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. +Skipping these produces generic output that ignores the project. ### 1. Context gathering diff --git a/.kiro/skills/impeccable/reference/brand.md b/.kiro/skills/impeccable/reference/brand.md index b069f2553..3d83a1cdc 100644 --- a/.kiro/skills/impeccable/reference/brand.md +++ b/.kiro/skills/impeccable/reference/brand.md @@ -12,6 +12,8 @@ Brand isn't a neutral register. AI-generated landing pages have flooded the inte **The second slop test: aesthetic lane.** Before committing to moves, name the reference. A Klim-style specimen page is one lane; Stripe-minimal is another; Liquid-Death-acid-maximalism is another. Don't drift into editorial-magazine aesthetics on a brief that isn't editorial. A hiking brand with Cormorant italic drop caps has the wrong register within the register. +Then the inverse test: in one sentence, describe what you're about to build the way a competitor would describe theirs. If that sentence fits the modal landing page in the category, restart. + ## Typography ### Font selection procedure @@ -66,6 +68,7 @@ Brand surfaces have permission for Committed, Full palette, and Drenched strateg - Palette IS voice. A calm brand and a restless brand should not share palette mechanics. - When the strategy is Committed or Drenched, color carries the brand. Don't hedge with neutrals around the edges. Commit. - Don't converge across projects. If the last brand surface was restrained-on-cream, this one is not. +- When a cultural-symbol palette is the obvious pull, reach past it. Let the cultural reading come from typography, imagery, and copy, not the palette. ## Layout @@ -79,14 +82,14 @@ Brand surfaces have permission for Committed, Full palette, and Drenched strateg Brand surfaces lean on imagery. A restaurant, hotel, magazine, or product landing page without any imagery reads as incomplete, not as restrained. A solid-color rectangle where a hero image should go is worse than a representative stock photo. -**When the brief implies imagery (restaurants, hotels, magazines, photography, hobbyist communities, food, travel, fashion, product), you must ship imagery.** Zero images is a bug, not a design choice. "Restraint" is not an excuse. +**When the brief implies imagery (restaurants, hotels, magazines, photography, hobbyist communities, food, travel, fashion, product), you must ship imagery.** Zero images is a bug, not a design choice. "Restraint" is not an excuse. If the approved comp or brief is image-led, ship real project assets, generated raster assets, or a credible canvas/SVG/WebGL scene. Do not replace photographic, architectural, product, or place imagery with generic CSS panels, decorative diagrams, cards, bullets, or copy. -- **For greenfield work without local assets, use stock imagery.** Unsplash is the default. The URL shape is `https://images.unsplash.com/photo-{id}?auto=format&fit=crop&w=1600&q=80`. Pick real Unsplash photo IDs you're confident exist (`photo-1559339352-11d035aa65de`, `photo-1590490360182-c33d57733427`, etc.); if unsure, pick fewer photos but don't substitute colored `
` placeholders. +- **For greenfield work without local assets, use stock imagery.** Unsplash is the default. The URL shape is `https://images.unsplash.com/photo-{id}?auto=format&fit=crop&w=1600&q=80`. **Verify the URLs before referencing them.** If you have an image-search MCP, web-fetch tool, or browser access, use it to find real photo IDs and confirm they resolve. Guessed IDs (even ones that look real) often 404 and ship as broken-image placeholders. Without a verification path, pick fewer photos you're confident exist over more that you guessed; never substitute colored `
` placeholders. - **Search for the brand's physical object**, not the generic category: "handmade pasta on a scratched wooden table" beats "Italian food"; "cypress trees above a limestone hotel facade at dusk" beats "luxury hotel". - **One decisive photo beats five mediocre ones.** Hero imagery should commit to a mood; padding with more stock doesn't rescue an indecisive one. - **Alt text is part of the voice.** "Coastal fettuccine, hand-cut, served on the terrace" beats "pasta dish". -Tech / dev-tool brands are the exception where zero imagery can be correct; a developer landing page often carries its voice through typography, code samples, diagrams. Know which kind of brand you're working on. +"Imagery" here is broader than stock photography: product screenshots, custom data visualizations, generated SVG, and canvas/WebGL scenes are all imagery. Text-only pages where typography alone carries the entire visual weight are the failure mode. ## Motion @@ -102,6 +105,7 @@ Tech / dev-tool brands are the exception where zero imagery can be correct; a de - Timid palettes and average layouts. Safe = invisible. - Zero imagery on a brief that implies imagery (restaurant, hotel, food, travel, fashion, photography, hobbyist). Colored blocks where a hero photo belongs. - Defaulting to editorial-magazine aesthetics (display serif + italic + drop caps + broadsheet grid) on briefs that aren't magazine-shaped. Editorial is ONE aesthetic lane, not the default brand aesthetic. +- Repeated tiny uppercase tracked labels above every section heading. A single strong kicker can be voice; repeating it as section grammar is AI scaffolding unless it's a deliberate, named brand system. ## Brand permissions diff --git a/.kiro/skills/impeccable/reference/craft.md b/.kiro/skills/impeccable/reference/craft.md index bdeee0294..c0cfa7460 100644 --- a/.kiro/skills/impeccable/reference/craft.md +++ b/.kiro/skills/impeccable/reference/craft.md @@ -1,43 +1,41 @@ # Craft Flow -Build a feature with impeccable UX and UI quality through a structured process: shape the design, land the visual direction, build real production code, then inspect and improve in-browser until the result meets a high-end studio bar. +Build a feature with impeccable UX and UI quality: shape the design, land the visual direction, build real production code, inspect and improve in-browser until it meets a high-end studio bar. -## Build Gate +Before writing code, you need: PRODUCT.md loaded, register identified and the matching reference loaded, and a confirmed design direction for this task (either from `shape` or supplied by the user). PRODUCT.md is project context, not a task-specific brief. -Craft cannot build until all of these are true: +Treat any approved visual direction (generated mock or stated reference) as a concrete contract for composition, hierarchy, density, atmosphere, signature motifs, and distinctive visual moves. Don't let mocks replace structure, copy, accessibility, or state design. But if the live result lacks the approved direction's major ingredients, the implementation is wrong. -1. PRODUCT context is valid and current. -2. The shape design brief is explicitly confirmed by the user for this task, unless the user already provided a confirmed brief. -3. Implementation references from the brief are loaded. -4. The shape visual probe decision is recorded: generated, skipped with reason, or already resolved. -5. The north-star mock decision is recorded: generated, skipped with reason, or not applicable. +## Step 0: Project Foundation -PRODUCT.md and `teach` answers do **not** satisfy the shape gate. They are project context only. A compact self-authored brief does not satisfy the shape gate either. `shape=pass` requires a separate user response approving the shape brief or an already-confirmed brief supplied by the user. +Before shape, before code: figure out what kind of project you're working in. -Invalid image-skip reasons include: "the final implementation will be semantic HTML/CSS/SVG", "the diagram should stay editable", "a raster mock would not be used directly", or "the product is fictional." Generated probes and mocks are direction artifacts; they are not implementation assets. +Look at the working directory. Run `ls`. Check for: -## Craft Contract +- An existing framework: `astro.config.mjs/ts`, `next.config.js/ts`, `nuxt.config.ts`, `svelte.config.js`, `vite.config.js/ts`, `package.json` with framework deps, `Cargo.toml` + Leptos/Yew, `Gemfile` + Rails. **If found, use it.** Do not start a parallel build, do not introduce a second framework, do not write to `dist/` or `build/` directly. Whatever pipeline the project has, respect it. +- An existing component library or design system: `src/components/`, `app/components/`, a `tokens.css` / `theme.ts`, an `astro.config` `integrations`. Read what's there before adding to it. +- An existing icon set: `lucide-react`, `@phosphor-icons/react`, `@iconify/*`, hand-rolled SVG sprites in `assets/icons/`. **Use what's already in the project**; don't introduce a second set. -Craft is not a first pass. It is a loop with these required artifacts: +If the directory is empty (greenfield), don't pick a framework silently. Ask the user via the AskUserQuestion tool, with sensible defaults framed by the brief: -1. Confirmed design brief from `shape`. -2. Approved visual direction, from generated probes / mocks when image generation is available. -3. Mock fidelity inventory: the visible ingredients from the approved direction that must survive into code. -4. Semantic, functional implementation using the project's real stack and conventions. -5. Browser evidence across relevant viewports. -6. At least one critique-and-fix pass after the first browser inspection, unless the first pass has no material defects. +```text +What should this be built on? + - Astro (default for content-led brand sites, landing pages, marketing surfaces) + - SvelteKit / Next.js / Nuxt (when the brief implies an app surface or significant interactivity) + - Single index.html (one-shot demo, prototype, or a deliberately framework-free experiment) +``` -Do not let generated mockups replace interface structure, copy, accessibility, responsive behavior, or state design. But do treat the approved mock as a concrete visual contract for composition, hierarchy, density, atmosphere, signature motifs, image needs, and distinctive visual moves. "North star" means "preserve the important visible ingredients in semantic code," not "use it as loose mood." +Default: Astro for brand briefs, the project's existing framework for product briefs. Ask once; don't re-ask mid-task. ## Step 1: Shape the Design -Run /impeccable shape, passing along whatever feature description the user provided. +Run /impeccable shape, passing along whatever feature description the user provided. Shape is **required** for craft; it is what produces a confirmed direction. -Wait for the design brief to be fully confirmed by the user before proceeding. The brief is your blueprint, and every implementation decision should trace back to it. +Present the shape output and stop. Wait for the user to confirm, override, or course-correct before writing code. -If this craft run resumed after `teach` created PRODUCT.md, run shape now. Do not treat the teach interview, PRODUCT.md, or a summary of project context as a substitute for shape. Shape is task-specific and must cover scope, content/states, visual direction, constraints, anti-goals, probes when applicable, and explicit brief confirmation. +If the user already supplied a confirmed brief or ran shape separately, use it and skip this step. -If the user has already run /impeccable shape and has a confirmed design brief, skip this step and use the existing brief. +When the original prompt + PRODUCT.md already answer scope, content, and visual direction with no real ambiguity, the shape output can be **compact** (3-5 bullets stating what you're building and the visual lane, ending with one or two specific questions or "confirm or override"). The full 10-section structured brief is reserved for genuinely ambiguous, multi-screen, or stakeholder-heavy tasks. Don't pad a clear brief into a long one to look thorough; equally, don't skip the pause to look efficient. ## Step 2: Load References @@ -55,79 +53,60 @@ Then add references based on the brief's needs: ## Step 3: Land the Visual Direction (Capability-Gated) -Before implementation, generate high-fidelity visual comps when all of these are true: +Generate high-fidelity visual comps before implementation when all three are true: -- The work is **net-new** or visually open-ended enough that composition exploration will improve the build. -- The brief's scope is **mid-fi, high-fi, or production-ready**. -- The current harness has **built-in image generation capability** (for example, Codex with a native image tool). Do **not** ask the user to set up external APIs, shell scripts, or one-off tooling just to do this. +- The work is net-new or visually open-ended enough that composition exploration will improve the build. +- The brief's scope is mid-fi, high-fi, or production-ready. +- The harness gives you native image generation (Codex's `image_gen`, an equivalent MCP tool). Don't ask the user to set up external APIs. -When those conditions are met, this step is mandatory for **both brand and product work** in Codex and any harness with built-in image generation. Use native image generation; in Codex, use the built-in `image_gen` tool via the imagegen skill. If image generation is unavailable, do not ask the user to install APIs or tooling. State in one line that the image step is skipped because the harness lacks native image generation, then proceed. - -Do not skip this step because the eventual UI should be semantic, editable, code-native, responsive, or accessible. Those are implementation requirements, not reasons to avoid visual exploration. - -### Purpose - -Use the mock step to find a stronger visual lane than code-first generation would reliably discover on its own. The brief remains authoritative on user, purpose, content, constraints, states, and anti-goals. The mock clarifies composition, hierarchy, density, typography, and visual tone. +When met, this step is mandatory for both brand and product work. If image generation isn't available, skip silently. "The eventual UI is semantic/code-native/accessible" is not a reason to skip; those are implementation requirements, not exploration ones. ### What to generate -Generate **1 to 3** high-fidelity north-star comps based on the confirmed brief. If shape already produced direction probes, use those results as input and generate a more resolved mock from the winning lane, not another unrelated exploration. +Generate **1 to 3** high-fidelity north-star comps from the confirmed brief. If shape already produced direction probes, resolve the winning lane further, not an unrelated exploration. Comps must differ in primary visual direction, not just color. -- For brand work, push visual identity, composition, and mood aggressively. -- For product work, still push hierarchy, topology, density, and tone, but keep the comps grounded in realistic product structure and states. -- For landing pages and long-form brand surfaces, show enough of the next section or second fold to establish the system beyond the hero. - -The comps must be genuinely different in primary visual direction, not just color variants. +- Brand work: push visual identity, composition, and mood aggressively. +- Product work: push hierarchy, topology, density, tone, grounded in realistic product structure. +- Landing pages and long-form brand surfaces: show enough of the second fold to establish the system beyond the hero. ### Approval loop -Show the comps and ask what should carry forward. If the user asks for changes or the best direction is still weak, generate a focused revision before implementation. Continue until one direction is approved, or until the user explicitly delegates the choice. +Show the comps and ask what carries forward. Iterate until one direction is approved or the user delegates. If the user delegates, pick the strongest direction and explain it from the brief, not personal taste. -If the user delegates, pick the strongest direction and explain the decision using the brief, not personal taste. - -Before moving to implementation, summarize: - -- What to carry into code -- What **not** to literalize from the mock - -This summary is required before Step 4. It is the handoff between visual exploration and semantic implementation. +Before Step 4, summarize what to carry into code and what **not** to literalize from the mock. This is the handoff between visual exploration and semantic implementation. ### Mock fidelity inventory -Before building, inventory the approved mock's major visible ingredients: +Inventory the approved mock's major visible ingredients: -- Hero silhouette and dominant composition. -- Signature motifs: planets, devices, portraits, charts, route lines, insets, badges, or other memorable objects. -- Nav and primary CTA treatment. -- Section sequence visible in the mock, especially the second fold. -- Image-native content the concept depends on. -- Typography, density, color/material treatment, and motion cues. +- Hero silhouette and dominant composition +- Signature motifs (planets, devices, portraits, charts, route lines, insets, badges, etc.) +- Nav and primary CTA treatment +- Section sequence, especially the second fold +- Image-native content the concept depends on +- Typography, density, color/material treatment, motion cues -For each ingredient, decide how it will be implemented: semantic HTML/CSS/SVG, generated asset, sourced project asset, icon library, canvas/WebGL, or an explicitly accepted omission. Do not substitute a different hero composition or new visual driver after approval unless the user approves the change. +For each, decide implementation: semantic HTML/CSS/SVG, generated asset, sourced asset, icon library, canvas/WebGL, or accepted omission. Don't substitute a different hero composition or visual driver post-approval without user sign-off. -Treat the mock as a **north star**, not a screenshot to trace. Do **not** rasterize core UI text or let the mock override the confirmed brief. But if the live result lacks the mock's major visible ingredients, the implementation is wrong. +If a photographic, architectural, product, or place-led mock becomes generic CSS scenery / decorative diagrams / bullets / copy, stop and fix it. That's a broken implementation, not a harmless interpretation. + +Treat the mock as a north star, not a screenshot to trace. Don't rasterize core UI text. But if the live result lacks the mock's major ingredients, the implementation is wrong. ## Step 4: Asset Extraction (Need-Gated) -If the chosen direction includes image-native visual ingredients that would materially improve the implementation, generate them as separate assets before building. +If the approved direction needs raster assets, create them before building. Do not replace required imagery with generic cards, bullets, emoji, fake metrics, decorative CSS panels, or filler copy. -Good candidates: +Use the native asset producer (`impeccable_asset_producer` in Codex, `impeccable-asset-producer` in Claude Code) to create clean assets from the hi-fi mock and crops. If you do not have explicit permission to use agents, stop and ask: -- stickers -- badges -- seals -- tickets -- graphic labels -- textures -- abstract objects -- decorative marks -- non-semantic scene elements +```text +Asset production will work better as a scoped subagent job. Should I spawn the Impeccable asset producer subagent for this step? +``` -For travel, editorial, portfolio, venue, product showcase, entertainment, education, or any other image-led brand surface, visual assets are usually core content, not decoration. Do not ship abstract CSS panels where the approved mock or subject matter calls for real imagery, generated plates, illustrations, maps, product/object renders, or destination scenes. +Do not skip asset production or silently do it inline. Inline asset production is allowed only if the user declines subagents, the harness cannot spawn the authorized agent, or the user explicitly asks for single-thread mode. -Do **not** export assets for core UI text, navigation, body copy, or any structure that should stay semantic and editable in code. +Pass the approved mock, crop/contact-sheet paths, output directory, dimensions/formats, transparency needs, constraints, and avoid list to the asset producer. Attach image generation capability to the spawned agent when the harness supports it; do not load image-generation reference material into the parent thread first. -Usually **1 to 5** extracted assets is enough. If the design can be built cleanly in HTML/CSS/SVG, prefer that over raster assets. If the mock contains major visual content that cannot be built credibly in code, asset extraction is not optional. +Prefer HTML/CSS/SVG/canvas when they can credibly reproduce an ingredient; use real/generated/stock imagery when the mock or subject matter calls for actual visual content. ## Step 5: Build to Production Quality @@ -135,50 +114,35 @@ Implement the feature following the design brief. Build in passes so structure, ### Production bar -- Use real or realistic content. Remove placeholder copy, placeholder images, dead links, fake controls, and unused scaffold before presenting. -- Preserve the approved mock's major ingredients. Missing hero objects, missing world/product imagery, different section structure, downgraded CTA/nav treatment, or generic replacements for distinctive motifs are blocking defects unless the user accepted the change. -- Build semantically first: real headings, landmarks, labels, form associations, button/link semantics, accessible names, and state announcements where needed. -- Calibrate spacing, alignment, grid placement, and vertical rhythm deliberately. Do not accept default gaps, arbitrary margins, unbalanced whitespace, or accidental optical misalignment. -- Make typography intentional: chosen font loading strategy, clear hierarchy, readable measure, stable line breaks, tuned wrapping, and no overflow at mobile or large desktop sizes. -- Design realistic state coverage: default, hover where supported, focus-visible, active, disabled, loading, error, success, empty, overflow, long text, short text, and first-run states where relevant. -- Make interaction quality feel finished: keyboard paths, touch targets, feedback timing, scroll behavior, transitions between states, and no hover-only functionality. -- Use icons from the project's established icon set when available. If no set exists, choose a coherent library or use accessible text controls; do not mix unrelated icon styles. -- Optimize imagery and media: correct dimensions, useful alt text, lazy loading below the fold, modern formats when practical, responsive `srcset` / `picture` for raster assets, and no project-referenced asset left outside the workspace. -- Make motion feel premium: use atmospheric blur, filter, mask, shadow, or reveal effects when they improve the experience; avoid casual layout-property animation, bound expensive effects, verify smoothness in-browser, respect reduced motion, and avoid choreography that blocks task completion. -- Preserve maintainability: reusable local patterns, clear component boundaries, project conventions, no rasterized UI text, and no hard-coded one-off hacks when a better local pattern exists. -- Fit the technical context: production build passes, no obvious console errors, no avoidable layout shift, no needless dependency, and no broken asset path. -- If you discover a design question that materially changes the brief or approved direction, stop and ask rather than guessing. +- **Real content.** No placeholder copy, placeholder images, dead links, fake controls, or unused scaffold at presentation time. +- **Preserve the approved mock's major ingredients.** Missing hero objects, world/product imagery, section structure, CTA/nav treatment, or distinctive motifs are blocking defects unless the user accepted the change. +- **Semantic first.** Real headings, landmarks, labels, form associations, button/link semantics, accessible names, state announcements where needed. +- **Deliberate spacing and alignment.** No default gaps, arbitrary margins, unbalanced whitespace, or accidental optical misalignment. +- **Intentional typography.** Chosen loading strategy, clear hierarchy, readable measure, stable line breaks, no overflow at any width. +- **Realistic state coverage.** Default, hover, focus-visible, active, disabled, loading, error, success, empty, overflow, long/short text, first-run. +- **Finished interaction quality.** Keyboard paths, touch targets, feedback timing, scroll behavior, state transitions, no hover-only functionality. +- **Coherent icon set.** Use the project's established set; otherwise pick one library or use accessible text. Don't mix. +- **Respect the build pipeline.** Edit source files and run the project's build (`npm run build` or equivalent). Don't write to `build/` / `dist/` / `.next/` with `cat`, heredoc, or Bash redirects; that skips asset hashing, image optimization, code splitting, and CSS extraction, and produces output the dev server won't serve. +- **Verify image URLs before referencing them.** Use image-search MCP or web-fetch when available; guessed photo IDs ship as broken-image placeholders. Without verification, prefer fewer images you're confident about. +- **Optimized imagery and media.** Correct dimensions, useful alt text, lazy loading below the fold, modern formats when practical, responsive `srcset`/`picture` for raster, no project-referenced asset left outside the workspace. +- **Premium motion.** Use atmospheric blur, filter, mask, shadow, reveal when they improve the experience. Avoid casual layout-property animation, bound expensive effects, verify smoothness in-browser, respect reduced motion, and avoid choreography that blocks task completion. +- **Maintainable.** Reusable local patterns, clear component boundaries, project conventions. No rasterized UI text or one-off hacks when a local pattern exists. +- **Technically clean.** Production build passes, no console errors, no avoidable layout shift, no needless dependencies, no broken asset paths. +- **Ask when uncertain.** If a discovery materially changes the brief or approved direction, stop and ask. Don't guess. -## Step 6: Browser-Based Iteration +## Step 6: Iterate Visually -**This step is critical.** Do not stop after the first implementation pass. +Look at what you built like a designer would. Your eyes are whatever the harness gives you: a connected browser, a screenshotting tool, Playwright, or asking the user. Use them for responsive testing (mobile, tablet, desktop minimum) and general visual validation. -Open the result in a browser. In Codex, use browser-use or equivalent browser automation when available; otherwise use Playwright or ask the user for screenshots. Inspect screenshots, not just DOM or terminal output. +If your tool returns a file path, read the PNG back into the conversation. A screenshot you didn't read doesn't count. -### Required viewport pass +For long-form brand surfaces, inspect major sections individually. Thumbnails hide spacing, clipping, and cascade defects. -Check the experience at the viewports that matter for the brief. Default minimum: +After the first pass, write an honest critique against the brief, the approved mock's major ingredients (hero silhouette, motifs, imagery, nav/CTA, density), and impeccable's DON'Ts. Patch material defects and re-inspect. **Don't invent defects to demonstrate iteration.** A confident "first pass clean, shipping" beats a fake fix. -- Mobile narrow -- Tablet or small laptop -- Desktop wide +Actively check: responsive behavior (composes, not shrinks), every state (empty / error / loading / edge), craft details (spacing, alignment, hierarchy, contrast, motion timing, focus), performance basics. The exit bar: defensible in a high-end studio review. -For each viewport, capture or inspect the rendered state and look for visual defects: overlap, clipping, weak hierarchy, off-grid alignment, awkward whitespace, cramped controls, unreadable type, broken imagery, hover-only functionality, layout shift, and text overflow. - -### Critique and fix loop - -After the first browser pass, write a short critique for yourself and patch the implementation. Repeat browser inspection after fixes. Continue until no material issues remain against this checklist: - -1. **Does it match the brief?** Compare the live result against every section of the design brief. Fix discrepancies. -2. **Does it match the approved mock?** Compare screenshots against the mock fidelity inventory: hero silhouette, major motifs, imagery, nav/CTA, section sequence, density, color/materials, and second-fold substance. Missing major ingredients are P0 defects. -3. **Does it pass the AI slop test?** If someone saw this and said "AI made this," would they believe it immediately? If yes, it needs more design intention. -4. **Check against impeccable's DON'T guidelines.** Fix any anti-pattern violations. -5. **Check every state.** Navigate through empty, error, loading, and edge case states. Each one should feel intentional, not like an afterthought. -6. **Check responsive behavior.** The design should adapt compositionally, not merely shrink. -7. **Check craft details.** Spacing consistency, optical alignment, type hierarchy, color contrast, image quality, icon coherence, interactive feedback, motion timing, and focus treatment. -8. **Check performance basics.** No obviously oversized images, avoidable layout thrash, blocking animations, or heavy assets without a reason. - -The exit bar is not "it works." It is: the rendered result looks intentional at all checked viewports, all expected states are handled, no placeholders remain unless explicitly accepted, and the implementation quality would be defensible in a high-end studio review. +Detector or QA output is defect evidence only; never proof the work is finished. ## Step 7: Present @@ -189,5 +153,3 @@ Present the result to the user: - Explain design decisions that connect back to the design brief and, when used, the chosen north-star mock. Include any accepted deviations from the mock; do not hide unimplemented mock ingredients. - Note any remaining limitations or follow-up risks honestly - Ask: "What's working? What isn't?" - -Iterate based on feedback. Good design is rarely right on the first pass. diff --git a/.kiro/skills/impeccable/reference/critique.md b/.kiro/skills/impeccable/reference/critique.md index cf5ac3725..5ed7159be 100644 --- a/.kiro/skills/impeccable/reference/critique.md +++ b/.kiro/skills/impeccable/reference/critique.md @@ -43,7 +43,7 @@ Run the bundled deterministic detector, which flags 27 specific patterns (AI slo **CLI scan**: ```bash -npx impeccable --json [--fast] [target] +npx impeccable detect --json [--fast] [target] ``` - Pass HTML/JSX/TSX/Vue/Svelte files or directories as `[target]` (anything with markup). Do not pass CSS-only files. diff --git a/.kiro/skills/impeccable/reference/polish.md b/.kiro/skills/impeccable/reference/polish.md index a2a409e48..eed3dbd27 100644 --- a/.kiro/skills/impeccable/reference/polish.md +++ b/.kiro/skills/impeccable/reference/polish.md @@ -2,6 +2,8 @@ Perform a meticulous final pass to catch all the small details that separate good work from great work. The difference between shipped and polished. +Detector and automated QA output are defect evidence only. A clean script result is never proof that the design is strong; gather browser evidence and inspect the real interaction path. + ## Design System Discovery Aligning the feature to the design system is **not optional**. Polish without alignment is decoration on top of drift, and it makes the next person's job harder. Discovery comes before any other polish work. @@ -216,11 +218,12 @@ Sweat the details. Zoom in until the alignment is right and the spacing reads as Before marking as done: -- **Use it yourself**: Actually interact with the feature -- **Test on real devices**: Not just browser DevTools -- **Ask someone else to review**: Fresh eyes catch things -- **Compare to design**: Match intended design -- **Check all states**: Don't just test happy path +- **Use it yourself**: Actually interact with the feature. +- **Test on real devices**: Not just browser DevTools. +- **Ask someone else to review**: Fresh eyes catch things. +- **Compare to design**: Match intended design. +- **Check all states**: Don't just test happy path. +- **Treat automation carefully**: Run detector or QA commands when they are available and relevant, fix their defects, but never cite a clean result as proof that the work is polished. ## Clean Up @@ -230,4 +233,3 @@ After polishing, ensure code quality: - **Remove orphaned code**: Delete unused styles, components, or files made obsolete by polish. - **Consolidate tokens**: If you introduced new values, check whether they should be tokens. - **Verify DRYness**: Look for duplication introduced during polishing and consolidate. - diff --git a/.kiro/skills/impeccable/reference/shape.md b/.kiro/skills/impeccable/reference/shape.md index 0785187ef..d1c983ff4 100644 --- a/.kiro/skills/impeccable/reference/shape.md +++ b/.kiro/skills/impeccable/reference/shape.md @@ -16,14 +16,16 @@ This is a required interaction, not optional guidance. Ask these questions in co ### Interview cadence -Discovery must include at least one user-answer round unless PRODUCT.md, DESIGN.md, or an already-confirmed brief directly answers the needed design inputs. With a sparse prompt, do **not** synthesize a complete brief for confirmation on the first response. +Discovery includes at least one user-answer round unless PRODUCT.md, DESIGN.md, or an already-confirmed brief directly answers the needed inputs. With a sparse prompt, do **not** synthesize a complete brief for confirmation on the first response. - Use the harness's structured question tool when one exists. Otherwise, ask directly in chat and stop. - Ask **2-3 questions per round**, then wait for answers. - Treat PRODUCT.md and DESIGN.md as anchors; they reduce repeated questions but do **not** replace shape for craft. Shape is task-specific. -- Round 1 should clarify purpose, audience/context, and success or emotional outcome. -- Round 2 should clarify content/data/states and scope/fidelity. -- Round 3 should clarify visual direction, constraints, and anti-goals when still unresolved. +- One round is the default. Add a second only if the first answers leave material gaps. Don't run a second round just to feel thorough. +- Round 1 should clarify purpose, audience/context, content/scope, and (for brand) visual direction. +- Round 2, when needed, fills in whatever's still genuinely missing. + +**Assert-then-confirm, not menu-with-escape.** When PRODUCT.md and the user's prompt make one option obvious, name it and ask the user to confirm or override. Don't enumerate "Restrained / Committed / Or something else?" as a real choice; "This reads as Restrained, confirm?" beats a four-option menu when the answer is already clear. ### Purpose & Context - What is this feature for? What problem does it solve? @@ -36,6 +38,7 @@ Discovery must include at least one user-answer round unless PRODUCT.md, DESIGN. - What are the realistic ranges? (Minimum, typical, maximum, e.g., 0 items, 5 items, 500 items) - What are the edge cases? (Empty state, error state, first-time use, power user) - Is any content dynamic? What changes and how often? +- What visual assets are real content here? Note required images, product shots, illustrations, maps, textures, diagrams, generated objects, or existing project assets. ### Design Direction @@ -72,9 +75,9 @@ After the discovery interview, generate a small set of visual direction probes * - The work is **net-new** or directionally ambiguous enough that visual exploration will clarify the brief. - The requested fidelity is **mid-fi, high-fi, or production-ready**. Skip for sketch-only planning. -- The current harness has **built-in image generation capability** (for example, Codex with a native image tool). Do **not** ask the user to set up external APIs, shell scripts, or one-off tooling just to do this. +- The current harness gives you native image generation (Codex's `image_gen`, an equivalent MCP tool, or similar). Don't ask the user to install APIs or tooling. -When those conditions are met, this step is mandatory for Codex and any harness with built-in image generation. Use native image generation; in Codex, use the built-in `image_gen` tool via the imagegen skill. If image generation is unavailable, do not ask the user to install APIs or tooling. State in one line that the image step is skipped because the harness lacks native image generation, then proceed. +When those conditions are met, this step is mandatory. If image generation isn't natively available, skip silently and proceed; don't announce the skip. Use probes to explore visual lanes, not to replace the brief. @@ -104,11 +107,20 @@ The probes should differ in primary visual direction (hierarchy, topology, densi - Do **not** treat generated imagery as final UX specification, final copy, or final accessibility behavior. - Do **not** use this step for minor refinements of existing work. It's for shaping a new surface or clarifying a big directional choice. -If image generation is unavailable, or the task doesn't benefit from it, skip this phase only with a one-line reason and proceed directly to the design brief. +If image generation isn't natively available, skip this phase silently and proceed. ## Phase 2: Design Brief -After the interview and any required probes, synthesize everything into a structured design brief. Present it to the user for explicit confirmation before considering this command complete. Stop after asking for confirmation; do not proceed to craft or implementation in the same response unless the user has already approved the brief. +After the interview and any required probes, present a brief and **end your response**. The user must confirm before any implementation runs. Do not present a brief and then continue to code in the same response, even if the brief feels obvious to you. The user's confirmation is the gate. + +**Choose the brief shape based on how clear the answers are:** + +- **Compact form (3-5 bullets)** when discovery was crisp and the original prompt + PRODUCT.md already pinned scope, content, and direction. State what you're building, the visual lane, and end with one or two specific questions or a clear "confirm or override?" prompt. This is the default for typical craft requests with a clear prompt. +- **Full structured form (sections below)** when the task is genuinely ambiguous, multi-screen, or when the user asked for shape as a standalone step. Use this when the discipline of structure earns its weight. + +Don't pad a clear brief into a long one to look thorough. A 70-line brief restating answers the user just gave is noise, not rigor. Equally, don't skip the confirmation pause to look efficient: the pause is the point. + +If the user already said "approved" or "go" during discovery for the *exact direction you'd present*, that counts as confirmation; you may proceed without asking again. But if your brief adds anything the user hasn't seen and approved, you must stop and confirm. ### Brief Structure @@ -136,16 +148,18 @@ List every state the feature needs: default, empty, loading, error, success, edg How users interact with this feature. What happens on click, hover, scroll? What feedback do they get? What's the flow from entry to completion? **8. Content Requirements** -What copy, labels, empty state messages, error messages, and microcopy are needed. Note any dynamic content and its realistic ranges. +What copy, labels, empty state messages, error messages, and microcopy are needed. Note any dynamic content and its realistic ranges. For image-led surfaces, also list the required image/media roles and their likely source (project asset, generated raster, semantic SVG/CSS, canvas/WebGL, icon library, or accepted omission). **9. Recommended References** Based on the brief, list which impeccable reference files would be most valuable during implementation (e.g., spatial-design.md for complex layouts, motion-design.md for animated features, interaction-design.md for form-heavy features). **10. Open Questions** -Anything unresolved that the implementer should resolve during build. +Anything genuinely unresolved. Don't list "open questions" you've already recommended a default for; assert the default and move on. If you'd write `Recommend: X` next to a question, just decide X. --- -ask the user directly to clarify what you cannot infer. Ask for explicit confirmation of the brief before finishing. If the user disagrees with any part, revisit the relevant discovery questions. A shape run is incomplete until the brief is confirmed. +ask the user directly to clarify what you cannot infer. + +If the user disagrees with any part, revisit the relevant discovery questions. A shape run is incomplete until the user confirms direction (or the user already gave a clear go during discovery, which counts). Once confirmed, the brief is complete. The user can now hand it to /impeccable, or use it to guide any other implementation approach. (If the user wants the full discovery-then-build flow in one step, they should use /impeccable craft instead, which runs this command internally.) diff --git a/.opencode/skills/impeccable/SKILL.md b/.opencode/skills/impeccable/SKILL.md index 2ea593923..2ecc77f1c 100644 --- a/.opencode/skills/impeccable/SKILL.md +++ b/.opencode/skills/impeccable/SKILL.md @@ -11,28 +11,15 @@ allowed-tools: Designs and iterates production-grade frontend interfaces. Real working code, committed design choices, exceptional craft. -## Setup (non-optional) +## Setup -Before any design work or file edits, pass these gates. Skipping them produces generic output that ignores the project. +Before any design work or file edits: -| 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. | +1. Load context (PRODUCT.md / DESIGN.md) via the loader script. +2. Identify the register and load the matching register reference (brand.md or product.md). +3. **If the user invoked a sub-command (e.g. `craft`, `shape`, `audit`), load its reference file too.** This is non-negotiable: `craft` without `craft.md` loaded means you'll skip the shape-and-confirm step the user expects. -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: 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. +Skipping these produces generic output that ignores the project. ### 1. Context gathering diff --git a/.opencode/skills/impeccable/reference/brand.md b/.opencode/skills/impeccable/reference/brand.md index b069f2553..3d83a1cdc 100644 --- a/.opencode/skills/impeccable/reference/brand.md +++ b/.opencode/skills/impeccable/reference/brand.md @@ -12,6 +12,8 @@ Brand isn't a neutral register. AI-generated landing pages have flooded the inte **The second slop test: aesthetic lane.** Before committing to moves, name the reference. A Klim-style specimen page is one lane; Stripe-minimal is another; Liquid-Death-acid-maximalism is another. Don't drift into editorial-magazine aesthetics on a brief that isn't editorial. A hiking brand with Cormorant italic drop caps has the wrong register within the register. +Then the inverse test: in one sentence, describe what you're about to build the way a competitor would describe theirs. If that sentence fits the modal landing page in the category, restart. + ## Typography ### Font selection procedure @@ -66,6 +68,7 @@ Brand surfaces have permission for Committed, Full palette, and Drenched strateg - Palette IS voice. A calm brand and a restless brand should not share palette mechanics. - When the strategy is Committed or Drenched, color carries the brand. Don't hedge with neutrals around the edges. Commit. - Don't converge across projects. If the last brand surface was restrained-on-cream, this one is not. +- When a cultural-symbol palette is the obvious pull, reach past it. Let the cultural reading come from typography, imagery, and copy, not the palette. ## Layout @@ -79,14 +82,14 @@ Brand surfaces have permission for Committed, Full palette, and Drenched strateg Brand surfaces lean on imagery. A restaurant, hotel, magazine, or product landing page without any imagery reads as incomplete, not as restrained. A solid-color rectangle where a hero image should go is worse than a representative stock photo. -**When the brief implies imagery (restaurants, hotels, magazines, photography, hobbyist communities, food, travel, fashion, product), you must ship imagery.** Zero images is a bug, not a design choice. "Restraint" is not an excuse. +**When the brief implies imagery (restaurants, hotels, magazines, photography, hobbyist communities, food, travel, fashion, product), you must ship imagery.** Zero images is a bug, not a design choice. "Restraint" is not an excuse. If the approved comp or brief is image-led, ship real project assets, generated raster assets, or a credible canvas/SVG/WebGL scene. Do not replace photographic, architectural, product, or place imagery with generic CSS panels, decorative diagrams, cards, bullets, or copy. -- **For greenfield work without local assets, use stock imagery.** Unsplash is the default. The URL shape is `https://images.unsplash.com/photo-{id}?auto=format&fit=crop&w=1600&q=80`. Pick real Unsplash photo IDs you're confident exist (`photo-1559339352-11d035aa65de`, `photo-1590490360182-c33d57733427`, etc.); if unsure, pick fewer photos but don't substitute colored `
` placeholders. +- **For greenfield work without local assets, use stock imagery.** Unsplash is the default. The URL shape is `https://images.unsplash.com/photo-{id}?auto=format&fit=crop&w=1600&q=80`. **Verify the URLs before referencing them.** If you have an image-search MCP, web-fetch tool, or browser access, use it to find real photo IDs and confirm they resolve. Guessed IDs (even ones that look real) often 404 and ship as broken-image placeholders. Without a verification path, pick fewer photos you're confident exist over more that you guessed; never substitute colored `
` placeholders. - **Search for the brand's physical object**, not the generic category: "handmade pasta on a scratched wooden table" beats "Italian food"; "cypress trees above a limestone hotel facade at dusk" beats "luxury hotel". - **One decisive photo beats five mediocre ones.** Hero imagery should commit to a mood; padding with more stock doesn't rescue an indecisive one. - **Alt text is part of the voice.** "Coastal fettuccine, hand-cut, served on the terrace" beats "pasta dish". -Tech / dev-tool brands are the exception where zero imagery can be correct; a developer landing page often carries its voice through typography, code samples, diagrams. Know which kind of brand you're working on. +"Imagery" here is broader than stock photography: product screenshots, custom data visualizations, generated SVG, and canvas/WebGL scenes are all imagery. Text-only pages where typography alone carries the entire visual weight are the failure mode. ## Motion @@ -102,6 +105,7 @@ Tech / dev-tool brands are the exception where zero imagery can be correct; a de - Timid palettes and average layouts. Safe = invisible. - Zero imagery on a brief that implies imagery (restaurant, hotel, food, travel, fashion, photography, hobbyist). Colored blocks where a hero photo belongs. - Defaulting to editorial-magazine aesthetics (display serif + italic + drop caps + broadsheet grid) on briefs that aren't magazine-shaped. Editorial is ONE aesthetic lane, not the default brand aesthetic. +- Repeated tiny uppercase tracked labels above every section heading. A single strong kicker can be voice; repeating it as section grammar is AI scaffolding unless it's a deliberate, named brand system. ## Brand permissions diff --git a/.opencode/skills/impeccable/reference/craft.md b/.opencode/skills/impeccable/reference/craft.md index bdeee0294..c0cfa7460 100644 --- a/.opencode/skills/impeccable/reference/craft.md +++ b/.opencode/skills/impeccable/reference/craft.md @@ -1,43 +1,41 @@ # Craft Flow -Build a feature with impeccable UX and UI quality through a structured process: shape the design, land the visual direction, build real production code, then inspect and improve in-browser until the result meets a high-end studio bar. +Build a feature with impeccable UX and UI quality: shape the design, land the visual direction, build real production code, inspect and improve in-browser until it meets a high-end studio bar. -## Build Gate +Before writing code, you need: PRODUCT.md loaded, register identified and the matching reference loaded, and a confirmed design direction for this task (either from `shape` or supplied by the user). PRODUCT.md is project context, not a task-specific brief. -Craft cannot build until all of these are true: +Treat any approved visual direction (generated mock or stated reference) as a concrete contract for composition, hierarchy, density, atmosphere, signature motifs, and distinctive visual moves. Don't let mocks replace structure, copy, accessibility, or state design. But if the live result lacks the approved direction's major ingredients, the implementation is wrong. -1. PRODUCT context is valid and current. -2. The shape design brief is explicitly confirmed by the user for this task, unless the user already provided a confirmed brief. -3. Implementation references from the brief are loaded. -4. The shape visual probe decision is recorded: generated, skipped with reason, or already resolved. -5. The north-star mock decision is recorded: generated, skipped with reason, or not applicable. +## Step 0: Project Foundation -PRODUCT.md and `teach` answers do **not** satisfy the shape gate. They are project context only. A compact self-authored brief does not satisfy the shape gate either. `shape=pass` requires a separate user response approving the shape brief or an already-confirmed brief supplied by the user. +Before shape, before code: figure out what kind of project you're working in. -Invalid image-skip reasons include: "the final implementation will be semantic HTML/CSS/SVG", "the diagram should stay editable", "a raster mock would not be used directly", or "the product is fictional." Generated probes and mocks are direction artifacts; they are not implementation assets. +Look at the working directory. Run `ls`. Check for: -## Craft Contract +- An existing framework: `astro.config.mjs/ts`, `next.config.js/ts`, `nuxt.config.ts`, `svelte.config.js`, `vite.config.js/ts`, `package.json` with framework deps, `Cargo.toml` + Leptos/Yew, `Gemfile` + Rails. **If found, use it.** Do not start a parallel build, do not introduce a second framework, do not write to `dist/` or `build/` directly. Whatever pipeline the project has, respect it. +- An existing component library or design system: `src/components/`, `app/components/`, a `tokens.css` / `theme.ts`, an `astro.config` `integrations`. Read what's there before adding to it. +- An existing icon set: `lucide-react`, `@phosphor-icons/react`, `@iconify/*`, hand-rolled SVG sprites in `assets/icons/`. **Use what's already in the project**; don't introduce a second set. -Craft is not a first pass. It is a loop with these required artifacts: +If the directory is empty (greenfield), don't pick a framework silently. Ask the user via the AskUserQuestion tool, with sensible defaults framed by the brief: -1. Confirmed design brief from `shape`. -2. Approved visual direction, from generated probes / mocks when image generation is available. -3. Mock fidelity inventory: the visible ingredients from the approved direction that must survive into code. -4. Semantic, functional implementation using the project's real stack and conventions. -5. Browser evidence across relevant viewports. -6. At least one critique-and-fix pass after the first browser inspection, unless the first pass has no material defects. +```text +What should this be built on? + - Astro (default for content-led brand sites, landing pages, marketing surfaces) + - SvelteKit / Next.js / Nuxt (when the brief implies an app surface or significant interactivity) + - Single index.html (one-shot demo, prototype, or a deliberately framework-free experiment) +``` -Do not let generated mockups replace interface structure, copy, accessibility, responsive behavior, or state design. But do treat the approved mock as a concrete visual contract for composition, hierarchy, density, atmosphere, signature motifs, image needs, and distinctive visual moves. "North star" means "preserve the important visible ingredients in semantic code," not "use it as loose mood." +Default: Astro for brand briefs, the project's existing framework for product briefs. Ask once; don't re-ask mid-task. ## Step 1: Shape the Design -Run /impeccable shape, passing along whatever feature description the user provided. +Run /impeccable shape, passing along whatever feature description the user provided. Shape is **required** for craft; it is what produces a confirmed direction. -Wait for the design brief to be fully confirmed by the user before proceeding. The brief is your blueprint, and every implementation decision should trace back to it. +Present the shape output and stop. Wait for the user to confirm, override, or course-correct before writing code. -If this craft run resumed after `teach` created PRODUCT.md, run shape now. Do not treat the teach interview, PRODUCT.md, or a summary of project context as a substitute for shape. Shape is task-specific and must cover scope, content/states, visual direction, constraints, anti-goals, probes when applicable, and explicit brief confirmation. +If the user already supplied a confirmed brief or ran shape separately, use it and skip this step. -If the user has already run /impeccable shape and has a confirmed design brief, skip this step and use the existing brief. +When the original prompt + PRODUCT.md already answer scope, content, and visual direction with no real ambiguity, the shape output can be **compact** (3-5 bullets stating what you're building and the visual lane, ending with one or two specific questions or "confirm or override"). The full 10-section structured brief is reserved for genuinely ambiguous, multi-screen, or stakeholder-heavy tasks. Don't pad a clear brief into a long one to look thorough; equally, don't skip the pause to look efficient. ## Step 2: Load References @@ -55,79 +53,60 @@ Then add references based on the brief's needs: ## Step 3: Land the Visual Direction (Capability-Gated) -Before implementation, generate high-fidelity visual comps when all of these are true: +Generate high-fidelity visual comps before implementation when all three are true: -- The work is **net-new** or visually open-ended enough that composition exploration will improve the build. -- The brief's scope is **mid-fi, high-fi, or production-ready**. -- The current harness has **built-in image generation capability** (for example, Codex with a native image tool). Do **not** ask the user to set up external APIs, shell scripts, or one-off tooling just to do this. +- The work is net-new or visually open-ended enough that composition exploration will improve the build. +- The brief's scope is mid-fi, high-fi, or production-ready. +- The harness gives you native image generation (Codex's `image_gen`, an equivalent MCP tool). Don't ask the user to set up external APIs. -When those conditions are met, this step is mandatory for **both brand and product work** in Codex and any harness with built-in image generation. Use native image generation; in Codex, use the built-in `image_gen` tool via the imagegen skill. If image generation is unavailable, do not ask the user to install APIs or tooling. State in one line that the image step is skipped because the harness lacks native image generation, then proceed. - -Do not skip this step because the eventual UI should be semantic, editable, code-native, responsive, or accessible. Those are implementation requirements, not reasons to avoid visual exploration. - -### Purpose - -Use the mock step to find a stronger visual lane than code-first generation would reliably discover on its own. The brief remains authoritative on user, purpose, content, constraints, states, and anti-goals. The mock clarifies composition, hierarchy, density, typography, and visual tone. +When met, this step is mandatory for both brand and product work. If image generation isn't available, skip silently. "The eventual UI is semantic/code-native/accessible" is not a reason to skip; those are implementation requirements, not exploration ones. ### What to generate -Generate **1 to 3** high-fidelity north-star comps based on the confirmed brief. If shape already produced direction probes, use those results as input and generate a more resolved mock from the winning lane, not another unrelated exploration. +Generate **1 to 3** high-fidelity north-star comps from the confirmed brief. If shape already produced direction probes, resolve the winning lane further, not an unrelated exploration. Comps must differ in primary visual direction, not just color. -- For brand work, push visual identity, composition, and mood aggressively. -- For product work, still push hierarchy, topology, density, and tone, but keep the comps grounded in realistic product structure and states. -- For landing pages and long-form brand surfaces, show enough of the next section or second fold to establish the system beyond the hero. - -The comps must be genuinely different in primary visual direction, not just color variants. +- Brand work: push visual identity, composition, and mood aggressively. +- Product work: push hierarchy, topology, density, tone, grounded in realistic product structure. +- Landing pages and long-form brand surfaces: show enough of the second fold to establish the system beyond the hero. ### Approval loop -Show the comps and ask what should carry forward. If the user asks for changes or the best direction is still weak, generate a focused revision before implementation. Continue until one direction is approved, or until the user explicitly delegates the choice. +Show the comps and ask what carries forward. Iterate until one direction is approved or the user delegates. If the user delegates, pick the strongest direction and explain it from the brief, not personal taste. -If the user delegates, pick the strongest direction and explain the decision using the brief, not personal taste. - -Before moving to implementation, summarize: - -- What to carry into code -- What **not** to literalize from the mock - -This summary is required before Step 4. It is the handoff between visual exploration and semantic implementation. +Before Step 4, summarize what to carry into code and what **not** to literalize from the mock. This is the handoff between visual exploration and semantic implementation. ### Mock fidelity inventory -Before building, inventory the approved mock's major visible ingredients: +Inventory the approved mock's major visible ingredients: -- Hero silhouette and dominant composition. -- Signature motifs: planets, devices, portraits, charts, route lines, insets, badges, or other memorable objects. -- Nav and primary CTA treatment. -- Section sequence visible in the mock, especially the second fold. -- Image-native content the concept depends on. -- Typography, density, color/material treatment, and motion cues. +- Hero silhouette and dominant composition +- Signature motifs (planets, devices, portraits, charts, route lines, insets, badges, etc.) +- Nav and primary CTA treatment +- Section sequence, especially the second fold +- Image-native content the concept depends on +- Typography, density, color/material treatment, motion cues -For each ingredient, decide how it will be implemented: semantic HTML/CSS/SVG, generated asset, sourced project asset, icon library, canvas/WebGL, or an explicitly accepted omission. Do not substitute a different hero composition or new visual driver after approval unless the user approves the change. +For each, decide implementation: semantic HTML/CSS/SVG, generated asset, sourced asset, icon library, canvas/WebGL, or accepted omission. Don't substitute a different hero composition or visual driver post-approval without user sign-off. -Treat the mock as a **north star**, not a screenshot to trace. Do **not** rasterize core UI text or let the mock override the confirmed brief. But if the live result lacks the mock's major visible ingredients, the implementation is wrong. +If a photographic, architectural, product, or place-led mock becomes generic CSS scenery / decorative diagrams / bullets / copy, stop and fix it. That's a broken implementation, not a harmless interpretation. + +Treat the mock as a north star, not a screenshot to trace. Don't rasterize core UI text. But if the live result lacks the mock's major ingredients, the implementation is wrong. ## Step 4: Asset Extraction (Need-Gated) -If the chosen direction includes image-native visual ingredients that would materially improve the implementation, generate them as separate assets before building. +If the approved direction needs raster assets, create them before building. Do not replace required imagery with generic cards, bullets, emoji, fake metrics, decorative CSS panels, or filler copy. -Good candidates: +Use the native asset producer (`impeccable_asset_producer` in Codex, `impeccable-asset-producer` in Claude Code) to create clean assets from the hi-fi mock and crops. If you do not have explicit permission to use agents, stop and ask: -- stickers -- badges -- seals -- tickets -- graphic labels -- textures -- abstract objects -- decorative marks -- non-semantic scene elements +```text +Asset production will work better as a scoped subagent job. Should I spawn the Impeccable asset producer subagent for this step? +``` -For travel, editorial, portfolio, venue, product showcase, entertainment, education, or any other image-led brand surface, visual assets are usually core content, not decoration. Do not ship abstract CSS panels where the approved mock or subject matter calls for real imagery, generated plates, illustrations, maps, product/object renders, or destination scenes. +Do not skip asset production or silently do it inline. Inline asset production is allowed only if the user declines subagents, the harness cannot spawn the authorized agent, or the user explicitly asks for single-thread mode. -Do **not** export assets for core UI text, navigation, body copy, or any structure that should stay semantic and editable in code. +Pass the approved mock, crop/contact-sheet paths, output directory, dimensions/formats, transparency needs, constraints, and avoid list to the asset producer. Attach image generation capability to the spawned agent when the harness supports it; do not load image-generation reference material into the parent thread first. -Usually **1 to 5** extracted assets is enough. If the design can be built cleanly in HTML/CSS/SVG, prefer that over raster assets. If the mock contains major visual content that cannot be built credibly in code, asset extraction is not optional. +Prefer HTML/CSS/SVG/canvas when they can credibly reproduce an ingredient; use real/generated/stock imagery when the mock or subject matter calls for actual visual content. ## Step 5: Build to Production Quality @@ -135,50 +114,35 @@ Implement the feature following the design brief. Build in passes so structure, ### Production bar -- Use real or realistic content. Remove placeholder copy, placeholder images, dead links, fake controls, and unused scaffold before presenting. -- Preserve the approved mock's major ingredients. Missing hero objects, missing world/product imagery, different section structure, downgraded CTA/nav treatment, or generic replacements for distinctive motifs are blocking defects unless the user accepted the change. -- Build semantically first: real headings, landmarks, labels, form associations, button/link semantics, accessible names, and state announcements where needed. -- Calibrate spacing, alignment, grid placement, and vertical rhythm deliberately. Do not accept default gaps, arbitrary margins, unbalanced whitespace, or accidental optical misalignment. -- Make typography intentional: chosen font loading strategy, clear hierarchy, readable measure, stable line breaks, tuned wrapping, and no overflow at mobile or large desktop sizes. -- Design realistic state coverage: default, hover where supported, focus-visible, active, disabled, loading, error, success, empty, overflow, long text, short text, and first-run states where relevant. -- Make interaction quality feel finished: keyboard paths, touch targets, feedback timing, scroll behavior, transitions between states, and no hover-only functionality. -- Use icons from the project's established icon set when available. If no set exists, choose a coherent library or use accessible text controls; do not mix unrelated icon styles. -- Optimize imagery and media: correct dimensions, useful alt text, lazy loading below the fold, modern formats when practical, responsive `srcset` / `picture` for raster assets, and no project-referenced asset left outside the workspace. -- Make motion feel premium: use atmospheric blur, filter, mask, shadow, or reveal effects when they improve the experience; avoid casual layout-property animation, bound expensive effects, verify smoothness in-browser, respect reduced motion, and avoid choreography that blocks task completion. -- Preserve maintainability: reusable local patterns, clear component boundaries, project conventions, no rasterized UI text, and no hard-coded one-off hacks when a better local pattern exists. -- Fit the technical context: production build passes, no obvious console errors, no avoidable layout shift, no needless dependency, and no broken asset path. -- If you discover a design question that materially changes the brief or approved direction, stop and ask rather than guessing. +- **Real content.** No placeholder copy, placeholder images, dead links, fake controls, or unused scaffold at presentation time. +- **Preserve the approved mock's major ingredients.** Missing hero objects, world/product imagery, section structure, CTA/nav treatment, or distinctive motifs are blocking defects unless the user accepted the change. +- **Semantic first.** Real headings, landmarks, labels, form associations, button/link semantics, accessible names, state announcements where needed. +- **Deliberate spacing and alignment.** No default gaps, arbitrary margins, unbalanced whitespace, or accidental optical misalignment. +- **Intentional typography.** Chosen loading strategy, clear hierarchy, readable measure, stable line breaks, no overflow at any width. +- **Realistic state coverage.** Default, hover, focus-visible, active, disabled, loading, error, success, empty, overflow, long/short text, first-run. +- **Finished interaction quality.** Keyboard paths, touch targets, feedback timing, scroll behavior, state transitions, no hover-only functionality. +- **Coherent icon set.** Use the project's established set; otherwise pick one library or use accessible text. Don't mix. +- **Respect the build pipeline.** Edit source files and run the project's build (`npm run build` or equivalent). Don't write to `build/` / `dist/` / `.next/` with `cat`, heredoc, or Bash redirects; that skips asset hashing, image optimization, code splitting, and CSS extraction, and produces output the dev server won't serve. +- **Verify image URLs before referencing them.** Use image-search MCP or web-fetch when available; guessed photo IDs ship as broken-image placeholders. Without verification, prefer fewer images you're confident about. +- **Optimized imagery and media.** Correct dimensions, useful alt text, lazy loading below the fold, modern formats when practical, responsive `srcset`/`picture` for raster, no project-referenced asset left outside the workspace. +- **Premium motion.** Use atmospheric blur, filter, mask, shadow, reveal when they improve the experience. Avoid casual layout-property animation, bound expensive effects, verify smoothness in-browser, respect reduced motion, and avoid choreography that blocks task completion. +- **Maintainable.** Reusable local patterns, clear component boundaries, project conventions. No rasterized UI text or one-off hacks when a local pattern exists. +- **Technically clean.** Production build passes, no console errors, no avoidable layout shift, no needless dependencies, no broken asset paths. +- **Ask when uncertain.** If a discovery materially changes the brief or approved direction, stop and ask. Don't guess. -## Step 6: Browser-Based Iteration +## Step 6: Iterate Visually -**This step is critical.** Do not stop after the first implementation pass. +Look at what you built like a designer would. Your eyes are whatever the harness gives you: a connected browser, a screenshotting tool, Playwright, or asking the user. Use them for responsive testing (mobile, tablet, desktop minimum) and general visual validation. -Open the result in a browser. In Codex, use browser-use or equivalent browser automation when available; otherwise use Playwright or ask the user for screenshots. Inspect screenshots, not just DOM or terminal output. +If your tool returns a file path, read the PNG back into the conversation. A screenshot you didn't read doesn't count. -### Required viewport pass +For long-form brand surfaces, inspect major sections individually. Thumbnails hide spacing, clipping, and cascade defects. -Check the experience at the viewports that matter for the brief. Default minimum: +After the first pass, write an honest critique against the brief, the approved mock's major ingredients (hero silhouette, motifs, imagery, nav/CTA, density), and impeccable's DON'Ts. Patch material defects and re-inspect. **Don't invent defects to demonstrate iteration.** A confident "first pass clean, shipping" beats a fake fix. -- Mobile narrow -- Tablet or small laptop -- Desktop wide +Actively check: responsive behavior (composes, not shrinks), every state (empty / error / loading / edge), craft details (spacing, alignment, hierarchy, contrast, motion timing, focus), performance basics. The exit bar: defensible in a high-end studio review. -For each viewport, capture or inspect the rendered state and look for visual defects: overlap, clipping, weak hierarchy, off-grid alignment, awkward whitespace, cramped controls, unreadable type, broken imagery, hover-only functionality, layout shift, and text overflow. - -### Critique and fix loop - -After the first browser pass, write a short critique for yourself and patch the implementation. Repeat browser inspection after fixes. Continue until no material issues remain against this checklist: - -1. **Does it match the brief?** Compare the live result against every section of the design brief. Fix discrepancies. -2. **Does it match the approved mock?** Compare screenshots against the mock fidelity inventory: hero silhouette, major motifs, imagery, nav/CTA, section sequence, density, color/materials, and second-fold substance. Missing major ingredients are P0 defects. -3. **Does it pass the AI slop test?** If someone saw this and said "AI made this," would they believe it immediately? If yes, it needs more design intention. -4. **Check against impeccable's DON'T guidelines.** Fix any anti-pattern violations. -5. **Check every state.** Navigate through empty, error, loading, and edge case states. Each one should feel intentional, not like an afterthought. -6. **Check responsive behavior.** The design should adapt compositionally, not merely shrink. -7. **Check craft details.** Spacing consistency, optical alignment, type hierarchy, color contrast, image quality, icon coherence, interactive feedback, motion timing, and focus treatment. -8. **Check performance basics.** No obviously oversized images, avoidable layout thrash, blocking animations, or heavy assets without a reason. - -The exit bar is not "it works." It is: the rendered result looks intentional at all checked viewports, all expected states are handled, no placeholders remain unless explicitly accepted, and the implementation quality would be defensible in a high-end studio review. +Detector or QA output is defect evidence only; never proof the work is finished. ## Step 7: Present @@ -189,5 +153,3 @@ Present the result to the user: - Explain design decisions that connect back to the design brief and, when used, the chosen north-star mock. Include any accepted deviations from the mock; do not hide unimplemented mock ingredients. - Note any remaining limitations or follow-up risks honestly - Ask: "What's working? What isn't?" - -Iterate based on feedback. Good design is rarely right on the first pass. diff --git a/.opencode/skills/impeccable/reference/critique.md b/.opencode/skills/impeccable/reference/critique.md index c3f404442..3a8d39c41 100644 --- a/.opencode/skills/impeccable/reference/critique.md +++ b/.opencode/skills/impeccable/reference/critique.md @@ -43,7 +43,7 @@ Run the bundled deterministic detector, which flags 27 specific patterns (AI slo **CLI scan**: ```bash -npx impeccable --json [--fast] [target] +npx impeccable detect --json [--fast] [target] ``` - Pass HTML/JSX/TSX/Vue/Svelte files or directories as `[target]` (anything with markup). Do not pass CSS-only files. diff --git a/.opencode/skills/impeccable/reference/polish.md b/.opencode/skills/impeccable/reference/polish.md index a2a409e48..eed3dbd27 100644 --- a/.opencode/skills/impeccable/reference/polish.md +++ b/.opencode/skills/impeccable/reference/polish.md @@ -2,6 +2,8 @@ Perform a meticulous final pass to catch all the small details that separate good work from great work. The difference between shipped and polished. +Detector and automated QA output are defect evidence only. A clean script result is never proof that the design is strong; gather browser evidence and inspect the real interaction path. + ## Design System Discovery Aligning the feature to the design system is **not optional**. Polish without alignment is decoration on top of drift, and it makes the next person's job harder. Discovery comes before any other polish work. @@ -216,11 +218,12 @@ Sweat the details. Zoom in until the alignment is right and the spacing reads as Before marking as done: -- **Use it yourself**: Actually interact with the feature -- **Test on real devices**: Not just browser DevTools -- **Ask someone else to review**: Fresh eyes catch things -- **Compare to design**: Match intended design -- **Check all states**: Don't just test happy path +- **Use it yourself**: Actually interact with the feature. +- **Test on real devices**: Not just browser DevTools. +- **Ask someone else to review**: Fresh eyes catch things. +- **Compare to design**: Match intended design. +- **Check all states**: Don't just test happy path. +- **Treat automation carefully**: Run detector or QA commands when they are available and relevant, fix their defects, but never cite a clean result as proof that the work is polished. ## Clean Up @@ -230,4 +233,3 @@ After polishing, ensure code quality: - **Remove orphaned code**: Delete unused styles, components, or files made obsolete by polish. - **Consolidate tokens**: If you introduced new values, check whether they should be tokens. - **Verify DRYness**: Look for duplication introduced during polishing and consolidate. - diff --git a/.opencode/skills/impeccable/reference/shape.md b/.opencode/skills/impeccable/reference/shape.md index 9fee0a100..0b1ec2fa5 100644 --- a/.opencode/skills/impeccable/reference/shape.md +++ b/.opencode/skills/impeccable/reference/shape.md @@ -16,14 +16,16 @@ This is a required interaction, not optional guidance. Ask these questions in co ### Interview cadence -Discovery must include at least one user-answer round unless PRODUCT.md, DESIGN.md, or an already-confirmed brief directly answers the needed design inputs. With a sparse prompt, do **not** synthesize a complete brief for confirmation on the first response. +Discovery includes at least one user-answer round unless PRODUCT.md, DESIGN.md, or an already-confirmed brief directly answers the needed inputs. With a sparse prompt, do **not** synthesize a complete brief for confirmation on the first response. - Use the harness's structured question tool when one exists. Otherwise, ask directly in chat and stop. - Ask **2-3 questions per round**, then wait for answers. - Treat PRODUCT.md and DESIGN.md as anchors; they reduce repeated questions but do **not** replace shape for craft. Shape is task-specific. -- Round 1 should clarify purpose, audience/context, and success or emotional outcome. -- Round 2 should clarify content/data/states and scope/fidelity. -- Round 3 should clarify visual direction, constraints, and anti-goals when still unresolved. +- One round is the default. Add a second only if the first answers leave material gaps. Don't run a second round just to feel thorough. +- Round 1 should clarify purpose, audience/context, content/scope, and (for brand) visual direction. +- Round 2, when needed, fills in whatever's still genuinely missing. + +**Assert-then-confirm, not menu-with-escape.** When PRODUCT.md and the user's prompt make one option obvious, name it and ask the user to confirm or override. Don't enumerate "Restrained / Committed / Or something else?" as a real choice; "This reads as Restrained, confirm?" beats a four-option menu when the answer is already clear. ### Purpose & Context - What is this feature for? What problem does it solve? @@ -36,6 +38,7 @@ Discovery must include at least one user-answer round unless PRODUCT.md, DESIGN. - What are the realistic ranges? (Minimum, typical, maximum, e.g., 0 items, 5 items, 500 items) - What are the edge cases? (Empty state, error state, first-time use, power user) - Is any content dynamic? What changes and how often? +- What visual assets are real content here? Note required images, product shots, illustrations, maps, textures, diagrams, generated objects, or existing project assets. ### Design Direction @@ -72,9 +75,9 @@ After the discovery interview, generate a small set of visual direction probes * - The work is **net-new** or directionally ambiguous enough that visual exploration will clarify the brief. - The requested fidelity is **mid-fi, high-fi, or production-ready**. Skip for sketch-only planning. -- The current harness has **built-in image generation capability** (for example, Codex with a native image tool). Do **not** ask the user to set up external APIs, shell scripts, or one-off tooling just to do this. +- The current harness gives you native image generation (Codex's `image_gen`, an equivalent MCP tool, or similar). Don't ask the user to install APIs or tooling. -When those conditions are met, this step is mandatory for Codex and any harness with built-in image generation. Use native image generation; in Codex, use the built-in `image_gen` tool via the imagegen skill. If image generation is unavailable, do not ask the user to install APIs or tooling. State in one line that the image step is skipped because the harness lacks native image generation, then proceed. +When those conditions are met, this step is mandatory. If image generation isn't natively available, skip silently and proceed; don't announce the skip. Use probes to explore visual lanes, not to replace the brief. @@ -104,11 +107,20 @@ The probes should differ in primary visual direction (hierarchy, topology, densi - Do **not** treat generated imagery as final UX specification, final copy, or final accessibility behavior. - Do **not** use this step for minor refinements of existing work. It's for shaping a new surface or clarifying a big directional choice. -If image generation is unavailable, or the task doesn't benefit from it, skip this phase only with a one-line reason and proceed directly to the design brief. +If image generation isn't natively available, skip this phase silently and proceed. ## Phase 2: Design Brief -After the interview and any required probes, synthesize everything into a structured design brief. Present it to the user for explicit confirmation before considering this command complete. Stop after asking for confirmation; do not proceed to craft or implementation in the same response unless the user has already approved the brief. +After the interview and any required probes, present a brief and **end your response**. The user must confirm before any implementation runs. Do not present a brief and then continue to code in the same response, even if the brief feels obvious to you. The user's confirmation is the gate. + +**Choose the brief shape based on how clear the answers are:** + +- **Compact form (3-5 bullets)** when discovery was crisp and the original prompt + PRODUCT.md already pinned scope, content, and direction. State what you're building, the visual lane, and end with one or two specific questions or a clear "confirm or override?" prompt. This is the default for typical craft requests with a clear prompt. +- **Full structured form (sections below)** when the task is genuinely ambiguous, multi-screen, or when the user asked for shape as a standalone step. Use this when the discipline of structure earns its weight. + +Don't pad a clear brief into a long one to look thorough. A 70-line brief restating answers the user just gave is noise, not rigor. Equally, don't skip the confirmation pause to look efficient: the pause is the point. + +If the user already said "approved" or "go" during discovery for the *exact direction you'd present*, that counts as confirmation; you may proceed without asking again. But if your brief adds anything the user hasn't seen and approved, you must stop and confirm. ### Brief Structure @@ -136,16 +148,18 @@ List every state the feature needs: default, empty, loading, error, success, edg How users interact with this feature. What happens on click, hover, scroll? What feedback do they get? What's the flow from entry to completion? **8. Content Requirements** -What copy, labels, empty state messages, error messages, and microcopy are needed. Note any dynamic content and its realistic ranges. +What copy, labels, empty state messages, error messages, and microcopy are needed. Note any dynamic content and its realistic ranges. For image-led surfaces, also list the required image/media roles and their likely source (project asset, generated raster, semantic SVG/CSS, canvas/WebGL, icon library, or accepted omission). **9. Recommended References** Based on the brief, list which impeccable reference files would be most valuable during implementation (e.g., spatial-design.md for complex layouts, motion-design.md for animated features, interaction-design.md for form-heavy features). **10. Open Questions** -Anything unresolved that the implementer should resolve during build. +Anything genuinely unresolved. Don't list "open questions" you've already recommended a default for; assert the default and move on. If you'd write `Recommend: X` next to a question, just decide X. --- -STOP and call the `question` tool to clarify. Ask for explicit confirmation of the brief before finishing. If the user disagrees with any part, revisit the relevant discovery questions. A shape run is incomplete until the brief is confirmed. +STOP and call the `question` tool to clarify. + +If the user disagrees with any part, revisit the relevant discovery questions. A shape run is incomplete until the user confirms direction (or the user already gave a clear go during discovery, which counts). Once confirmed, the brief is complete. The user can now hand it to /impeccable, or use it to guide any other implementation approach. (If the user wants the full discovery-then-build flow in one step, they should use /impeccable craft instead, which runs this command internally.) diff --git a/.pi/skills/impeccable/SKILL.md b/.pi/skills/impeccable/SKILL.md index bb9125629..bdf333388 100644 --- a/.pi/skills/impeccable/SKILL.md +++ b/.pi/skills/impeccable/SKILL.md @@ -9,28 +9,15 @@ allowed-tools: Designs and iterates production-grade frontend interfaces. Real working code, committed design choices, exceptional craft. -## Setup (non-optional) +## Setup -Before any design work or file edits, pass these gates. Skipping them produces generic output that ignores the project. +Before any design work or file edits: -| Gate | Required check | If fail | -|---|---|---| -| Context | The PRODUCT.md / DESIGN.md loader result is known from `node .pi/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. | +1. Load context (PRODUCT.md / DESIGN.md) via the loader script. +2. Identify the register and load the matching register reference (brand.md or product.md). +3. **If the user invoked a sub-command (e.g. `craft`, `shape`, `audit`), load its reference file too.** This is non-negotiable: `craft` without `craft.md` loaded means you'll skip the shape-and-confirm step the user expects. -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: 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. +Skipping these produces generic output that ignores the project. ### 1. Context gathering diff --git a/.pi/skills/impeccable/reference/brand.md b/.pi/skills/impeccable/reference/brand.md index b069f2553..3d83a1cdc 100644 --- a/.pi/skills/impeccable/reference/brand.md +++ b/.pi/skills/impeccable/reference/brand.md @@ -12,6 +12,8 @@ Brand isn't a neutral register. AI-generated landing pages have flooded the inte **The second slop test: aesthetic lane.** Before committing to moves, name the reference. A Klim-style specimen page is one lane; Stripe-minimal is another; Liquid-Death-acid-maximalism is another. Don't drift into editorial-magazine aesthetics on a brief that isn't editorial. A hiking brand with Cormorant italic drop caps has the wrong register within the register. +Then the inverse test: in one sentence, describe what you're about to build the way a competitor would describe theirs. If that sentence fits the modal landing page in the category, restart. + ## Typography ### Font selection procedure @@ -66,6 +68,7 @@ Brand surfaces have permission for Committed, Full palette, and Drenched strateg - Palette IS voice. A calm brand and a restless brand should not share palette mechanics. - When the strategy is Committed or Drenched, color carries the brand. Don't hedge with neutrals around the edges. Commit. - Don't converge across projects. If the last brand surface was restrained-on-cream, this one is not. +- When a cultural-symbol palette is the obvious pull, reach past it. Let the cultural reading come from typography, imagery, and copy, not the palette. ## Layout @@ -79,14 +82,14 @@ Brand surfaces have permission for Committed, Full palette, and Drenched strateg Brand surfaces lean on imagery. A restaurant, hotel, magazine, or product landing page without any imagery reads as incomplete, not as restrained. A solid-color rectangle where a hero image should go is worse than a representative stock photo. -**When the brief implies imagery (restaurants, hotels, magazines, photography, hobbyist communities, food, travel, fashion, product), you must ship imagery.** Zero images is a bug, not a design choice. "Restraint" is not an excuse. +**When the brief implies imagery (restaurants, hotels, magazines, photography, hobbyist communities, food, travel, fashion, product), you must ship imagery.** Zero images is a bug, not a design choice. "Restraint" is not an excuse. If the approved comp or brief is image-led, ship real project assets, generated raster assets, or a credible canvas/SVG/WebGL scene. Do not replace photographic, architectural, product, or place imagery with generic CSS panels, decorative diagrams, cards, bullets, or copy. -- **For greenfield work without local assets, use stock imagery.** Unsplash is the default. The URL shape is `https://images.unsplash.com/photo-{id}?auto=format&fit=crop&w=1600&q=80`. Pick real Unsplash photo IDs you're confident exist (`photo-1559339352-11d035aa65de`, `photo-1590490360182-c33d57733427`, etc.); if unsure, pick fewer photos but don't substitute colored `
` placeholders. +- **For greenfield work without local assets, use stock imagery.** Unsplash is the default. The URL shape is `https://images.unsplash.com/photo-{id}?auto=format&fit=crop&w=1600&q=80`. **Verify the URLs before referencing them.** If you have an image-search MCP, web-fetch tool, or browser access, use it to find real photo IDs and confirm they resolve. Guessed IDs (even ones that look real) often 404 and ship as broken-image placeholders. Without a verification path, pick fewer photos you're confident exist over more that you guessed; never substitute colored `
` placeholders. - **Search for the brand's physical object**, not the generic category: "handmade pasta on a scratched wooden table" beats "Italian food"; "cypress trees above a limestone hotel facade at dusk" beats "luxury hotel". - **One decisive photo beats five mediocre ones.** Hero imagery should commit to a mood; padding with more stock doesn't rescue an indecisive one. - **Alt text is part of the voice.** "Coastal fettuccine, hand-cut, served on the terrace" beats "pasta dish". -Tech / dev-tool brands are the exception where zero imagery can be correct; a developer landing page often carries its voice through typography, code samples, diagrams. Know which kind of brand you're working on. +"Imagery" here is broader than stock photography: product screenshots, custom data visualizations, generated SVG, and canvas/WebGL scenes are all imagery. Text-only pages where typography alone carries the entire visual weight are the failure mode. ## Motion @@ -102,6 +105,7 @@ Tech / dev-tool brands are the exception where zero imagery can be correct; a de - Timid palettes and average layouts. Safe = invisible. - Zero imagery on a brief that implies imagery (restaurant, hotel, food, travel, fashion, photography, hobbyist). Colored blocks where a hero photo belongs. - Defaulting to editorial-magazine aesthetics (display serif + italic + drop caps + broadsheet grid) on briefs that aren't magazine-shaped. Editorial is ONE aesthetic lane, not the default brand aesthetic. +- Repeated tiny uppercase tracked labels above every section heading. A single strong kicker can be voice; repeating it as section grammar is AI scaffolding unless it's a deliberate, named brand system. ## Brand permissions diff --git a/.pi/skills/impeccable/reference/craft.md b/.pi/skills/impeccable/reference/craft.md index bdeee0294..c0cfa7460 100644 --- a/.pi/skills/impeccable/reference/craft.md +++ b/.pi/skills/impeccable/reference/craft.md @@ -1,43 +1,41 @@ # Craft Flow -Build a feature with impeccable UX and UI quality through a structured process: shape the design, land the visual direction, build real production code, then inspect and improve in-browser until the result meets a high-end studio bar. +Build a feature with impeccable UX and UI quality: shape the design, land the visual direction, build real production code, inspect and improve in-browser until it meets a high-end studio bar. -## Build Gate +Before writing code, you need: PRODUCT.md loaded, register identified and the matching reference loaded, and a confirmed design direction for this task (either from `shape` or supplied by the user). PRODUCT.md is project context, not a task-specific brief. -Craft cannot build until all of these are true: +Treat any approved visual direction (generated mock or stated reference) as a concrete contract for composition, hierarchy, density, atmosphere, signature motifs, and distinctive visual moves. Don't let mocks replace structure, copy, accessibility, or state design. But if the live result lacks the approved direction's major ingredients, the implementation is wrong. -1. PRODUCT context is valid and current. -2. The shape design brief is explicitly confirmed by the user for this task, unless the user already provided a confirmed brief. -3. Implementation references from the brief are loaded. -4. The shape visual probe decision is recorded: generated, skipped with reason, or already resolved. -5. The north-star mock decision is recorded: generated, skipped with reason, or not applicable. +## Step 0: Project Foundation -PRODUCT.md and `teach` answers do **not** satisfy the shape gate. They are project context only. A compact self-authored brief does not satisfy the shape gate either. `shape=pass` requires a separate user response approving the shape brief or an already-confirmed brief supplied by the user. +Before shape, before code: figure out what kind of project you're working in. -Invalid image-skip reasons include: "the final implementation will be semantic HTML/CSS/SVG", "the diagram should stay editable", "a raster mock would not be used directly", or "the product is fictional." Generated probes and mocks are direction artifacts; they are not implementation assets. +Look at the working directory. Run `ls`. Check for: -## Craft Contract +- An existing framework: `astro.config.mjs/ts`, `next.config.js/ts`, `nuxt.config.ts`, `svelte.config.js`, `vite.config.js/ts`, `package.json` with framework deps, `Cargo.toml` + Leptos/Yew, `Gemfile` + Rails. **If found, use it.** Do not start a parallel build, do not introduce a second framework, do not write to `dist/` or `build/` directly. Whatever pipeline the project has, respect it. +- An existing component library or design system: `src/components/`, `app/components/`, a `tokens.css` / `theme.ts`, an `astro.config` `integrations`. Read what's there before adding to it. +- An existing icon set: `lucide-react`, `@phosphor-icons/react`, `@iconify/*`, hand-rolled SVG sprites in `assets/icons/`. **Use what's already in the project**; don't introduce a second set. -Craft is not a first pass. It is a loop with these required artifacts: +If the directory is empty (greenfield), don't pick a framework silently. Ask the user via the AskUserQuestion tool, with sensible defaults framed by the brief: -1. Confirmed design brief from `shape`. -2. Approved visual direction, from generated probes / mocks when image generation is available. -3. Mock fidelity inventory: the visible ingredients from the approved direction that must survive into code. -4. Semantic, functional implementation using the project's real stack and conventions. -5. Browser evidence across relevant viewports. -6. At least one critique-and-fix pass after the first browser inspection, unless the first pass has no material defects. +```text +What should this be built on? + - Astro (default for content-led brand sites, landing pages, marketing surfaces) + - SvelteKit / Next.js / Nuxt (when the brief implies an app surface or significant interactivity) + - Single index.html (one-shot demo, prototype, or a deliberately framework-free experiment) +``` -Do not let generated mockups replace interface structure, copy, accessibility, responsive behavior, or state design. But do treat the approved mock as a concrete visual contract for composition, hierarchy, density, atmosphere, signature motifs, image needs, and distinctive visual moves. "North star" means "preserve the important visible ingredients in semantic code," not "use it as loose mood." +Default: Astro for brand briefs, the project's existing framework for product briefs. Ask once; don't re-ask mid-task. ## Step 1: Shape the Design -Run /impeccable shape, passing along whatever feature description the user provided. +Run /impeccable shape, passing along whatever feature description the user provided. Shape is **required** for craft; it is what produces a confirmed direction. -Wait for the design brief to be fully confirmed by the user before proceeding. The brief is your blueprint, and every implementation decision should trace back to it. +Present the shape output and stop. Wait for the user to confirm, override, or course-correct before writing code. -If this craft run resumed after `teach` created PRODUCT.md, run shape now. Do not treat the teach interview, PRODUCT.md, or a summary of project context as a substitute for shape. Shape is task-specific and must cover scope, content/states, visual direction, constraints, anti-goals, probes when applicable, and explicit brief confirmation. +If the user already supplied a confirmed brief or ran shape separately, use it and skip this step. -If the user has already run /impeccable shape and has a confirmed design brief, skip this step and use the existing brief. +When the original prompt + PRODUCT.md already answer scope, content, and visual direction with no real ambiguity, the shape output can be **compact** (3-5 bullets stating what you're building and the visual lane, ending with one or two specific questions or "confirm or override"). The full 10-section structured brief is reserved for genuinely ambiguous, multi-screen, or stakeholder-heavy tasks. Don't pad a clear brief into a long one to look thorough; equally, don't skip the pause to look efficient. ## Step 2: Load References @@ -55,79 +53,60 @@ Then add references based on the brief's needs: ## Step 3: Land the Visual Direction (Capability-Gated) -Before implementation, generate high-fidelity visual comps when all of these are true: +Generate high-fidelity visual comps before implementation when all three are true: -- The work is **net-new** or visually open-ended enough that composition exploration will improve the build. -- The brief's scope is **mid-fi, high-fi, or production-ready**. -- The current harness has **built-in image generation capability** (for example, Codex with a native image tool). Do **not** ask the user to set up external APIs, shell scripts, or one-off tooling just to do this. +- The work is net-new or visually open-ended enough that composition exploration will improve the build. +- The brief's scope is mid-fi, high-fi, or production-ready. +- The harness gives you native image generation (Codex's `image_gen`, an equivalent MCP tool). Don't ask the user to set up external APIs. -When those conditions are met, this step is mandatory for **both brand and product work** in Codex and any harness with built-in image generation. Use native image generation; in Codex, use the built-in `image_gen` tool via the imagegen skill. If image generation is unavailable, do not ask the user to install APIs or tooling. State in one line that the image step is skipped because the harness lacks native image generation, then proceed. - -Do not skip this step because the eventual UI should be semantic, editable, code-native, responsive, or accessible. Those are implementation requirements, not reasons to avoid visual exploration. - -### Purpose - -Use the mock step to find a stronger visual lane than code-first generation would reliably discover on its own. The brief remains authoritative on user, purpose, content, constraints, states, and anti-goals. The mock clarifies composition, hierarchy, density, typography, and visual tone. +When met, this step is mandatory for both brand and product work. If image generation isn't available, skip silently. "The eventual UI is semantic/code-native/accessible" is not a reason to skip; those are implementation requirements, not exploration ones. ### What to generate -Generate **1 to 3** high-fidelity north-star comps based on the confirmed brief. If shape already produced direction probes, use those results as input and generate a more resolved mock from the winning lane, not another unrelated exploration. +Generate **1 to 3** high-fidelity north-star comps from the confirmed brief. If shape already produced direction probes, resolve the winning lane further, not an unrelated exploration. Comps must differ in primary visual direction, not just color. -- For brand work, push visual identity, composition, and mood aggressively. -- For product work, still push hierarchy, topology, density, and tone, but keep the comps grounded in realistic product structure and states. -- For landing pages and long-form brand surfaces, show enough of the next section or second fold to establish the system beyond the hero. - -The comps must be genuinely different in primary visual direction, not just color variants. +- Brand work: push visual identity, composition, and mood aggressively. +- Product work: push hierarchy, topology, density, tone, grounded in realistic product structure. +- Landing pages and long-form brand surfaces: show enough of the second fold to establish the system beyond the hero. ### Approval loop -Show the comps and ask what should carry forward. If the user asks for changes or the best direction is still weak, generate a focused revision before implementation. Continue until one direction is approved, or until the user explicitly delegates the choice. +Show the comps and ask what carries forward. Iterate until one direction is approved or the user delegates. If the user delegates, pick the strongest direction and explain it from the brief, not personal taste. -If the user delegates, pick the strongest direction and explain the decision using the brief, not personal taste. - -Before moving to implementation, summarize: - -- What to carry into code -- What **not** to literalize from the mock - -This summary is required before Step 4. It is the handoff between visual exploration and semantic implementation. +Before Step 4, summarize what to carry into code and what **not** to literalize from the mock. This is the handoff between visual exploration and semantic implementation. ### Mock fidelity inventory -Before building, inventory the approved mock's major visible ingredients: +Inventory the approved mock's major visible ingredients: -- Hero silhouette and dominant composition. -- Signature motifs: planets, devices, portraits, charts, route lines, insets, badges, or other memorable objects. -- Nav and primary CTA treatment. -- Section sequence visible in the mock, especially the second fold. -- Image-native content the concept depends on. -- Typography, density, color/material treatment, and motion cues. +- Hero silhouette and dominant composition +- Signature motifs (planets, devices, portraits, charts, route lines, insets, badges, etc.) +- Nav and primary CTA treatment +- Section sequence, especially the second fold +- Image-native content the concept depends on +- Typography, density, color/material treatment, motion cues -For each ingredient, decide how it will be implemented: semantic HTML/CSS/SVG, generated asset, sourced project asset, icon library, canvas/WebGL, or an explicitly accepted omission. Do not substitute a different hero composition or new visual driver after approval unless the user approves the change. +For each, decide implementation: semantic HTML/CSS/SVG, generated asset, sourced asset, icon library, canvas/WebGL, or accepted omission. Don't substitute a different hero composition or visual driver post-approval without user sign-off. -Treat the mock as a **north star**, not a screenshot to trace. Do **not** rasterize core UI text or let the mock override the confirmed brief. But if the live result lacks the mock's major visible ingredients, the implementation is wrong. +If a photographic, architectural, product, or place-led mock becomes generic CSS scenery / decorative diagrams / bullets / copy, stop and fix it. That's a broken implementation, not a harmless interpretation. + +Treat the mock as a north star, not a screenshot to trace. Don't rasterize core UI text. But if the live result lacks the mock's major ingredients, the implementation is wrong. ## Step 4: Asset Extraction (Need-Gated) -If the chosen direction includes image-native visual ingredients that would materially improve the implementation, generate them as separate assets before building. +If the approved direction needs raster assets, create them before building. Do not replace required imagery with generic cards, bullets, emoji, fake metrics, decorative CSS panels, or filler copy. -Good candidates: +Use the native asset producer (`impeccable_asset_producer` in Codex, `impeccable-asset-producer` in Claude Code) to create clean assets from the hi-fi mock and crops. If you do not have explicit permission to use agents, stop and ask: -- stickers -- badges -- seals -- tickets -- graphic labels -- textures -- abstract objects -- decorative marks -- non-semantic scene elements +```text +Asset production will work better as a scoped subagent job. Should I spawn the Impeccable asset producer subagent for this step? +``` -For travel, editorial, portfolio, venue, product showcase, entertainment, education, or any other image-led brand surface, visual assets are usually core content, not decoration. Do not ship abstract CSS panels where the approved mock or subject matter calls for real imagery, generated plates, illustrations, maps, product/object renders, or destination scenes. +Do not skip asset production or silently do it inline. Inline asset production is allowed only if the user declines subagents, the harness cannot spawn the authorized agent, or the user explicitly asks for single-thread mode. -Do **not** export assets for core UI text, navigation, body copy, or any structure that should stay semantic and editable in code. +Pass the approved mock, crop/contact-sheet paths, output directory, dimensions/formats, transparency needs, constraints, and avoid list to the asset producer. Attach image generation capability to the spawned agent when the harness supports it; do not load image-generation reference material into the parent thread first. -Usually **1 to 5** extracted assets is enough. If the design can be built cleanly in HTML/CSS/SVG, prefer that over raster assets. If the mock contains major visual content that cannot be built credibly in code, asset extraction is not optional. +Prefer HTML/CSS/SVG/canvas when they can credibly reproduce an ingredient; use real/generated/stock imagery when the mock or subject matter calls for actual visual content. ## Step 5: Build to Production Quality @@ -135,50 +114,35 @@ Implement the feature following the design brief. Build in passes so structure, ### Production bar -- Use real or realistic content. Remove placeholder copy, placeholder images, dead links, fake controls, and unused scaffold before presenting. -- Preserve the approved mock's major ingredients. Missing hero objects, missing world/product imagery, different section structure, downgraded CTA/nav treatment, or generic replacements for distinctive motifs are blocking defects unless the user accepted the change. -- Build semantically first: real headings, landmarks, labels, form associations, button/link semantics, accessible names, and state announcements where needed. -- Calibrate spacing, alignment, grid placement, and vertical rhythm deliberately. Do not accept default gaps, arbitrary margins, unbalanced whitespace, or accidental optical misalignment. -- Make typography intentional: chosen font loading strategy, clear hierarchy, readable measure, stable line breaks, tuned wrapping, and no overflow at mobile or large desktop sizes. -- Design realistic state coverage: default, hover where supported, focus-visible, active, disabled, loading, error, success, empty, overflow, long text, short text, and first-run states where relevant. -- Make interaction quality feel finished: keyboard paths, touch targets, feedback timing, scroll behavior, transitions between states, and no hover-only functionality. -- Use icons from the project's established icon set when available. If no set exists, choose a coherent library or use accessible text controls; do not mix unrelated icon styles. -- Optimize imagery and media: correct dimensions, useful alt text, lazy loading below the fold, modern formats when practical, responsive `srcset` / `picture` for raster assets, and no project-referenced asset left outside the workspace. -- Make motion feel premium: use atmospheric blur, filter, mask, shadow, or reveal effects when they improve the experience; avoid casual layout-property animation, bound expensive effects, verify smoothness in-browser, respect reduced motion, and avoid choreography that blocks task completion. -- Preserve maintainability: reusable local patterns, clear component boundaries, project conventions, no rasterized UI text, and no hard-coded one-off hacks when a better local pattern exists. -- Fit the technical context: production build passes, no obvious console errors, no avoidable layout shift, no needless dependency, and no broken asset path. -- If you discover a design question that materially changes the brief or approved direction, stop and ask rather than guessing. +- **Real content.** No placeholder copy, placeholder images, dead links, fake controls, or unused scaffold at presentation time. +- **Preserve the approved mock's major ingredients.** Missing hero objects, world/product imagery, section structure, CTA/nav treatment, or distinctive motifs are blocking defects unless the user accepted the change. +- **Semantic first.** Real headings, landmarks, labels, form associations, button/link semantics, accessible names, state announcements where needed. +- **Deliberate spacing and alignment.** No default gaps, arbitrary margins, unbalanced whitespace, or accidental optical misalignment. +- **Intentional typography.** Chosen loading strategy, clear hierarchy, readable measure, stable line breaks, no overflow at any width. +- **Realistic state coverage.** Default, hover, focus-visible, active, disabled, loading, error, success, empty, overflow, long/short text, first-run. +- **Finished interaction quality.** Keyboard paths, touch targets, feedback timing, scroll behavior, state transitions, no hover-only functionality. +- **Coherent icon set.** Use the project's established set; otherwise pick one library or use accessible text. Don't mix. +- **Respect the build pipeline.** Edit source files and run the project's build (`npm run build` or equivalent). Don't write to `build/` / `dist/` / `.next/` with `cat`, heredoc, or Bash redirects; that skips asset hashing, image optimization, code splitting, and CSS extraction, and produces output the dev server won't serve. +- **Verify image URLs before referencing them.** Use image-search MCP or web-fetch when available; guessed photo IDs ship as broken-image placeholders. Without verification, prefer fewer images you're confident about. +- **Optimized imagery and media.** Correct dimensions, useful alt text, lazy loading below the fold, modern formats when practical, responsive `srcset`/`picture` for raster, no project-referenced asset left outside the workspace. +- **Premium motion.** Use atmospheric blur, filter, mask, shadow, reveal when they improve the experience. Avoid casual layout-property animation, bound expensive effects, verify smoothness in-browser, respect reduced motion, and avoid choreography that blocks task completion. +- **Maintainable.** Reusable local patterns, clear component boundaries, project conventions. No rasterized UI text or one-off hacks when a local pattern exists. +- **Technically clean.** Production build passes, no console errors, no avoidable layout shift, no needless dependencies, no broken asset paths. +- **Ask when uncertain.** If a discovery materially changes the brief or approved direction, stop and ask. Don't guess. -## Step 6: Browser-Based Iteration +## Step 6: Iterate Visually -**This step is critical.** Do not stop after the first implementation pass. +Look at what you built like a designer would. Your eyes are whatever the harness gives you: a connected browser, a screenshotting tool, Playwright, or asking the user. Use them for responsive testing (mobile, tablet, desktop minimum) and general visual validation. -Open the result in a browser. In Codex, use browser-use or equivalent browser automation when available; otherwise use Playwright or ask the user for screenshots. Inspect screenshots, not just DOM or terminal output. +If your tool returns a file path, read the PNG back into the conversation. A screenshot you didn't read doesn't count. -### Required viewport pass +For long-form brand surfaces, inspect major sections individually. Thumbnails hide spacing, clipping, and cascade defects. -Check the experience at the viewports that matter for the brief. Default minimum: +After the first pass, write an honest critique against the brief, the approved mock's major ingredients (hero silhouette, motifs, imagery, nav/CTA, density), and impeccable's DON'Ts. Patch material defects and re-inspect. **Don't invent defects to demonstrate iteration.** A confident "first pass clean, shipping" beats a fake fix. -- Mobile narrow -- Tablet or small laptop -- Desktop wide +Actively check: responsive behavior (composes, not shrinks), every state (empty / error / loading / edge), craft details (spacing, alignment, hierarchy, contrast, motion timing, focus), performance basics. The exit bar: defensible in a high-end studio review. -For each viewport, capture or inspect the rendered state and look for visual defects: overlap, clipping, weak hierarchy, off-grid alignment, awkward whitespace, cramped controls, unreadable type, broken imagery, hover-only functionality, layout shift, and text overflow. - -### Critique and fix loop - -After the first browser pass, write a short critique for yourself and patch the implementation. Repeat browser inspection after fixes. Continue until no material issues remain against this checklist: - -1. **Does it match the brief?** Compare the live result against every section of the design brief. Fix discrepancies. -2. **Does it match the approved mock?** Compare screenshots against the mock fidelity inventory: hero silhouette, major motifs, imagery, nav/CTA, section sequence, density, color/materials, and second-fold substance. Missing major ingredients are P0 defects. -3. **Does it pass the AI slop test?** If someone saw this and said "AI made this," would they believe it immediately? If yes, it needs more design intention. -4. **Check against impeccable's DON'T guidelines.** Fix any anti-pattern violations. -5. **Check every state.** Navigate through empty, error, loading, and edge case states. Each one should feel intentional, not like an afterthought. -6. **Check responsive behavior.** The design should adapt compositionally, not merely shrink. -7. **Check craft details.** Spacing consistency, optical alignment, type hierarchy, color contrast, image quality, icon coherence, interactive feedback, motion timing, and focus treatment. -8. **Check performance basics.** No obviously oversized images, avoidable layout thrash, blocking animations, or heavy assets without a reason. - -The exit bar is not "it works." It is: the rendered result looks intentional at all checked viewports, all expected states are handled, no placeholders remain unless explicitly accepted, and the implementation quality would be defensible in a high-end studio review. +Detector or QA output is defect evidence only; never proof the work is finished. ## Step 7: Present @@ -189,5 +153,3 @@ Present the result to the user: - Explain design decisions that connect back to the design brief and, when used, the chosen north-star mock. Include any accepted deviations from the mock; do not hide unimplemented mock ingredients. - Note any remaining limitations or follow-up risks honestly - Ask: "What's working? What isn't?" - -Iterate based on feedback. Good design is rarely right on the first pass. diff --git a/.pi/skills/impeccable/reference/critique.md b/.pi/skills/impeccable/reference/critique.md index 1c8485b81..d5563b0d3 100644 --- a/.pi/skills/impeccable/reference/critique.md +++ b/.pi/skills/impeccable/reference/critique.md @@ -43,7 +43,7 @@ Run the bundled deterministic detector, which flags 27 specific patterns (AI slo **CLI scan**: ```bash -npx impeccable --json [--fast] [target] +npx impeccable detect --json [--fast] [target] ``` - Pass HTML/JSX/TSX/Vue/Svelte files or directories as `[target]` (anything with markup). Do not pass CSS-only files. diff --git a/.pi/skills/impeccable/reference/polish.md b/.pi/skills/impeccable/reference/polish.md index a2a409e48..eed3dbd27 100644 --- a/.pi/skills/impeccable/reference/polish.md +++ b/.pi/skills/impeccable/reference/polish.md @@ -2,6 +2,8 @@ Perform a meticulous final pass to catch all the small details that separate good work from great work. The difference between shipped and polished. +Detector and automated QA output are defect evidence only. A clean script result is never proof that the design is strong; gather browser evidence and inspect the real interaction path. + ## Design System Discovery Aligning the feature to the design system is **not optional**. Polish without alignment is decoration on top of drift, and it makes the next person's job harder. Discovery comes before any other polish work. @@ -216,11 +218,12 @@ Sweat the details. Zoom in until the alignment is right and the spacing reads as Before marking as done: -- **Use it yourself**: Actually interact with the feature -- **Test on real devices**: Not just browser DevTools -- **Ask someone else to review**: Fresh eyes catch things -- **Compare to design**: Match intended design -- **Check all states**: Don't just test happy path +- **Use it yourself**: Actually interact with the feature. +- **Test on real devices**: Not just browser DevTools. +- **Ask someone else to review**: Fresh eyes catch things. +- **Compare to design**: Match intended design. +- **Check all states**: Don't just test happy path. +- **Treat automation carefully**: Run detector or QA commands when they are available and relevant, fix their defects, but never cite a clean result as proof that the work is polished. ## Clean Up @@ -230,4 +233,3 @@ After polishing, ensure code quality: - **Remove orphaned code**: Delete unused styles, components, or files made obsolete by polish. - **Consolidate tokens**: If you introduced new values, check whether they should be tokens. - **Verify DRYness**: Look for duplication introduced during polishing and consolidate. - diff --git a/.pi/skills/impeccable/reference/shape.md b/.pi/skills/impeccable/reference/shape.md index 0785187ef..d1c983ff4 100644 --- a/.pi/skills/impeccable/reference/shape.md +++ b/.pi/skills/impeccable/reference/shape.md @@ -16,14 +16,16 @@ This is a required interaction, not optional guidance. Ask these questions in co ### Interview cadence -Discovery must include at least one user-answer round unless PRODUCT.md, DESIGN.md, or an already-confirmed brief directly answers the needed design inputs. With a sparse prompt, do **not** synthesize a complete brief for confirmation on the first response. +Discovery includes at least one user-answer round unless PRODUCT.md, DESIGN.md, or an already-confirmed brief directly answers the needed inputs. With a sparse prompt, do **not** synthesize a complete brief for confirmation on the first response. - Use the harness's structured question tool when one exists. Otherwise, ask directly in chat and stop. - Ask **2-3 questions per round**, then wait for answers. - Treat PRODUCT.md and DESIGN.md as anchors; they reduce repeated questions but do **not** replace shape for craft. Shape is task-specific. -- Round 1 should clarify purpose, audience/context, and success or emotional outcome. -- Round 2 should clarify content/data/states and scope/fidelity. -- Round 3 should clarify visual direction, constraints, and anti-goals when still unresolved. +- One round is the default. Add a second only if the first answers leave material gaps. Don't run a second round just to feel thorough. +- Round 1 should clarify purpose, audience/context, content/scope, and (for brand) visual direction. +- Round 2, when needed, fills in whatever's still genuinely missing. + +**Assert-then-confirm, not menu-with-escape.** When PRODUCT.md and the user's prompt make one option obvious, name it and ask the user to confirm or override. Don't enumerate "Restrained / Committed / Or something else?" as a real choice; "This reads as Restrained, confirm?" beats a four-option menu when the answer is already clear. ### Purpose & Context - What is this feature for? What problem does it solve? @@ -36,6 +38,7 @@ Discovery must include at least one user-answer round unless PRODUCT.md, DESIGN. - What are the realistic ranges? (Minimum, typical, maximum, e.g., 0 items, 5 items, 500 items) - What are the edge cases? (Empty state, error state, first-time use, power user) - Is any content dynamic? What changes and how often? +- What visual assets are real content here? Note required images, product shots, illustrations, maps, textures, diagrams, generated objects, or existing project assets. ### Design Direction @@ -72,9 +75,9 @@ After the discovery interview, generate a small set of visual direction probes * - The work is **net-new** or directionally ambiguous enough that visual exploration will clarify the brief. - The requested fidelity is **mid-fi, high-fi, or production-ready**. Skip for sketch-only planning. -- The current harness has **built-in image generation capability** (for example, Codex with a native image tool). Do **not** ask the user to set up external APIs, shell scripts, or one-off tooling just to do this. +- The current harness gives you native image generation (Codex's `image_gen`, an equivalent MCP tool, or similar). Don't ask the user to install APIs or tooling. -When those conditions are met, this step is mandatory for Codex and any harness with built-in image generation. Use native image generation; in Codex, use the built-in `image_gen` tool via the imagegen skill. If image generation is unavailable, do not ask the user to install APIs or tooling. State in one line that the image step is skipped because the harness lacks native image generation, then proceed. +When those conditions are met, this step is mandatory. If image generation isn't natively available, skip silently and proceed; don't announce the skip. Use probes to explore visual lanes, not to replace the brief. @@ -104,11 +107,20 @@ The probes should differ in primary visual direction (hierarchy, topology, densi - Do **not** treat generated imagery as final UX specification, final copy, or final accessibility behavior. - Do **not** use this step for minor refinements of existing work. It's for shaping a new surface or clarifying a big directional choice. -If image generation is unavailable, or the task doesn't benefit from it, skip this phase only with a one-line reason and proceed directly to the design brief. +If image generation isn't natively available, skip this phase silently and proceed. ## Phase 2: Design Brief -After the interview and any required probes, synthesize everything into a structured design brief. Present it to the user for explicit confirmation before considering this command complete. Stop after asking for confirmation; do not proceed to craft or implementation in the same response unless the user has already approved the brief. +After the interview and any required probes, present a brief and **end your response**. The user must confirm before any implementation runs. Do not present a brief and then continue to code in the same response, even if the brief feels obvious to you. The user's confirmation is the gate. + +**Choose the brief shape based on how clear the answers are:** + +- **Compact form (3-5 bullets)** when discovery was crisp and the original prompt + PRODUCT.md already pinned scope, content, and direction. State what you're building, the visual lane, and end with one or two specific questions or a clear "confirm or override?" prompt. This is the default for typical craft requests with a clear prompt. +- **Full structured form (sections below)** when the task is genuinely ambiguous, multi-screen, or when the user asked for shape as a standalone step. Use this when the discipline of structure earns its weight. + +Don't pad a clear brief into a long one to look thorough. A 70-line brief restating answers the user just gave is noise, not rigor. Equally, don't skip the confirmation pause to look efficient: the pause is the point. + +If the user already said "approved" or "go" during discovery for the *exact direction you'd present*, that counts as confirmation; you may proceed without asking again. But if your brief adds anything the user hasn't seen and approved, you must stop and confirm. ### Brief Structure @@ -136,16 +148,18 @@ List every state the feature needs: default, empty, loading, error, success, edg How users interact with this feature. What happens on click, hover, scroll? What feedback do they get? What's the flow from entry to completion? **8. Content Requirements** -What copy, labels, empty state messages, error messages, and microcopy are needed. Note any dynamic content and its realistic ranges. +What copy, labels, empty state messages, error messages, and microcopy are needed. Note any dynamic content and its realistic ranges. For image-led surfaces, also list the required image/media roles and their likely source (project asset, generated raster, semantic SVG/CSS, canvas/WebGL, icon library, or accepted omission). **9. Recommended References** Based on the brief, list which impeccable reference files would be most valuable during implementation (e.g., spatial-design.md for complex layouts, motion-design.md for animated features, interaction-design.md for form-heavy features). **10. Open Questions** -Anything unresolved that the implementer should resolve during build. +Anything genuinely unresolved. Don't list "open questions" you've already recommended a default for; assert the default and move on. If you'd write `Recommend: X` next to a question, just decide X. --- -ask the user directly to clarify what you cannot infer. Ask for explicit confirmation of the brief before finishing. If the user disagrees with any part, revisit the relevant discovery questions. A shape run is incomplete until the brief is confirmed. +ask the user directly to clarify what you cannot infer. + +If the user disagrees with any part, revisit the relevant discovery questions. A shape run is incomplete until the user confirms direction (or the user already gave a clear go during discovery, which counts). Once confirmed, the brief is complete. The user can now hand it to /impeccable, or use it to guide any other implementation approach. (If the user wants the full discovery-then-build flow in one step, they should use /impeccable craft instead, which runs this command internally.) diff --git a/.qoder/skills/impeccable/SKILL.md b/.qoder/skills/impeccable/SKILL.md index 951a0dfb4..58bf42f8e 100644 --- a/.qoder/skills/impeccable/SKILL.md +++ b/.qoder/skills/impeccable/SKILL.md @@ -11,28 +11,15 @@ allowed-tools: Designs and iterates production-grade frontend interfaces. Real working code, committed design choices, exceptional craft. -## Setup (non-optional) +## Setup -Before any design work or file edits, pass these gates. Skipping them produces generic output that ignores the project. +Before any design work or file edits: -| Gate | Required check | If fail | -|---|---|---| -| Context | The PRODUCT.md / DESIGN.md loader result is known from `node .qoder/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. | +1. Load context (PRODUCT.md / DESIGN.md) via the loader script. +2. Identify the register and load the matching register reference (brand.md or product.md). +3. **If the user invoked a sub-command (e.g. `craft`, `shape`, `audit`), load its reference file too.** This is non-negotiable: `craft` without `craft.md` loaded means you'll skip the shape-and-confirm step the user expects. -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: 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. +Skipping these produces generic output that ignores the project. ### 1. Context gathering diff --git a/.qoder/skills/impeccable/reference/brand.md b/.qoder/skills/impeccable/reference/brand.md index b069f2553..3d83a1cdc 100644 --- a/.qoder/skills/impeccable/reference/brand.md +++ b/.qoder/skills/impeccable/reference/brand.md @@ -12,6 +12,8 @@ Brand isn't a neutral register. AI-generated landing pages have flooded the inte **The second slop test: aesthetic lane.** Before committing to moves, name the reference. A Klim-style specimen page is one lane; Stripe-minimal is another; Liquid-Death-acid-maximalism is another. Don't drift into editorial-magazine aesthetics on a brief that isn't editorial. A hiking brand with Cormorant italic drop caps has the wrong register within the register. +Then the inverse test: in one sentence, describe what you're about to build the way a competitor would describe theirs. If that sentence fits the modal landing page in the category, restart. + ## Typography ### Font selection procedure @@ -66,6 +68,7 @@ Brand surfaces have permission for Committed, Full palette, and Drenched strateg - Palette IS voice. A calm brand and a restless brand should not share palette mechanics. - When the strategy is Committed or Drenched, color carries the brand. Don't hedge with neutrals around the edges. Commit. - Don't converge across projects. If the last brand surface was restrained-on-cream, this one is not. +- When a cultural-symbol palette is the obvious pull, reach past it. Let the cultural reading come from typography, imagery, and copy, not the palette. ## Layout @@ -79,14 +82,14 @@ Brand surfaces have permission for Committed, Full palette, and Drenched strateg Brand surfaces lean on imagery. A restaurant, hotel, magazine, or product landing page without any imagery reads as incomplete, not as restrained. A solid-color rectangle where a hero image should go is worse than a representative stock photo. -**When the brief implies imagery (restaurants, hotels, magazines, photography, hobbyist communities, food, travel, fashion, product), you must ship imagery.** Zero images is a bug, not a design choice. "Restraint" is not an excuse. +**When the brief implies imagery (restaurants, hotels, magazines, photography, hobbyist communities, food, travel, fashion, product), you must ship imagery.** Zero images is a bug, not a design choice. "Restraint" is not an excuse. If the approved comp or brief is image-led, ship real project assets, generated raster assets, or a credible canvas/SVG/WebGL scene. Do not replace photographic, architectural, product, or place imagery with generic CSS panels, decorative diagrams, cards, bullets, or copy. -- **For greenfield work without local assets, use stock imagery.** Unsplash is the default. The URL shape is `https://images.unsplash.com/photo-{id}?auto=format&fit=crop&w=1600&q=80`. Pick real Unsplash photo IDs you're confident exist (`photo-1559339352-11d035aa65de`, `photo-1590490360182-c33d57733427`, etc.); if unsure, pick fewer photos but don't substitute colored `
` placeholders. +- **For greenfield work without local assets, use stock imagery.** Unsplash is the default. The URL shape is `https://images.unsplash.com/photo-{id}?auto=format&fit=crop&w=1600&q=80`. **Verify the URLs before referencing them.** If you have an image-search MCP, web-fetch tool, or browser access, use it to find real photo IDs and confirm they resolve. Guessed IDs (even ones that look real) often 404 and ship as broken-image placeholders. Without a verification path, pick fewer photos you're confident exist over more that you guessed; never substitute colored `
` placeholders. - **Search for the brand's physical object**, not the generic category: "handmade pasta on a scratched wooden table" beats "Italian food"; "cypress trees above a limestone hotel facade at dusk" beats "luxury hotel". - **One decisive photo beats five mediocre ones.** Hero imagery should commit to a mood; padding with more stock doesn't rescue an indecisive one. - **Alt text is part of the voice.** "Coastal fettuccine, hand-cut, served on the terrace" beats "pasta dish". -Tech / dev-tool brands are the exception where zero imagery can be correct; a developer landing page often carries its voice through typography, code samples, diagrams. Know which kind of brand you're working on. +"Imagery" here is broader than stock photography: product screenshots, custom data visualizations, generated SVG, and canvas/WebGL scenes are all imagery. Text-only pages where typography alone carries the entire visual weight are the failure mode. ## Motion @@ -102,6 +105,7 @@ Tech / dev-tool brands are the exception where zero imagery can be correct; a de - Timid palettes and average layouts. Safe = invisible. - Zero imagery on a brief that implies imagery (restaurant, hotel, food, travel, fashion, photography, hobbyist). Colored blocks where a hero photo belongs. - Defaulting to editorial-magazine aesthetics (display serif + italic + drop caps + broadsheet grid) on briefs that aren't magazine-shaped. Editorial is ONE aesthetic lane, not the default brand aesthetic. +- Repeated tiny uppercase tracked labels above every section heading. A single strong kicker can be voice; repeating it as section grammar is AI scaffolding unless it's a deliberate, named brand system. ## Brand permissions diff --git a/.qoder/skills/impeccable/reference/craft.md b/.qoder/skills/impeccable/reference/craft.md index bdeee0294..c0cfa7460 100644 --- a/.qoder/skills/impeccable/reference/craft.md +++ b/.qoder/skills/impeccable/reference/craft.md @@ -1,43 +1,41 @@ # Craft Flow -Build a feature with impeccable UX and UI quality through a structured process: shape the design, land the visual direction, build real production code, then inspect and improve in-browser until the result meets a high-end studio bar. +Build a feature with impeccable UX and UI quality: shape the design, land the visual direction, build real production code, inspect and improve in-browser until it meets a high-end studio bar. -## Build Gate +Before writing code, you need: PRODUCT.md loaded, register identified and the matching reference loaded, and a confirmed design direction for this task (either from `shape` or supplied by the user). PRODUCT.md is project context, not a task-specific brief. -Craft cannot build until all of these are true: +Treat any approved visual direction (generated mock or stated reference) as a concrete contract for composition, hierarchy, density, atmosphere, signature motifs, and distinctive visual moves. Don't let mocks replace structure, copy, accessibility, or state design. But if the live result lacks the approved direction's major ingredients, the implementation is wrong. -1. PRODUCT context is valid and current. -2. The shape design brief is explicitly confirmed by the user for this task, unless the user already provided a confirmed brief. -3. Implementation references from the brief are loaded. -4. The shape visual probe decision is recorded: generated, skipped with reason, or already resolved. -5. The north-star mock decision is recorded: generated, skipped with reason, or not applicable. +## Step 0: Project Foundation -PRODUCT.md and `teach` answers do **not** satisfy the shape gate. They are project context only. A compact self-authored brief does not satisfy the shape gate either. `shape=pass` requires a separate user response approving the shape brief or an already-confirmed brief supplied by the user. +Before shape, before code: figure out what kind of project you're working in. -Invalid image-skip reasons include: "the final implementation will be semantic HTML/CSS/SVG", "the diagram should stay editable", "a raster mock would not be used directly", or "the product is fictional." Generated probes and mocks are direction artifacts; they are not implementation assets. +Look at the working directory. Run `ls`. Check for: -## Craft Contract +- An existing framework: `astro.config.mjs/ts`, `next.config.js/ts`, `nuxt.config.ts`, `svelte.config.js`, `vite.config.js/ts`, `package.json` with framework deps, `Cargo.toml` + Leptos/Yew, `Gemfile` + Rails. **If found, use it.** Do not start a parallel build, do not introduce a second framework, do not write to `dist/` or `build/` directly. Whatever pipeline the project has, respect it. +- An existing component library or design system: `src/components/`, `app/components/`, a `tokens.css` / `theme.ts`, an `astro.config` `integrations`. Read what's there before adding to it. +- An existing icon set: `lucide-react`, `@phosphor-icons/react`, `@iconify/*`, hand-rolled SVG sprites in `assets/icons/`. **Use what's already in the project**; don't introduce a second set. -Craft is not a first pass. It is a loop with these required artifacts: +If the directory is empty (greenfield), don't pick a framework silently. Ask the user via the AskUserQuestion tool, with sensible defaults framed by the brief: -1. Confirmed design brief from `shape`. -2. Approved visual direction, from generated probes / mocks when image generation is available. -3. Mock fidelity inventory: the visible ingredients from the approved direction that must survive into code. -4. Semantic, functional implementation using the project's real stack and conventions. -5. Browser evidence across relevant viewports. -6. At least one critique-and-fix pass after the first browser inspection, unless the first pass has no material defects. +```text +What should this be built on? + - Astro (default for content-led brand sites, landing pages, marketing surfaces) + - SvelteKit / Next.js / Nuxt (when the brief implies an app surface or significant interactivity) + - Single index.html (one-shot demo, prototype, or a deliberately framework-free experiment) +``` -Do not let generated mockups replace interface structure, copy, accessibility, responsive behavior, or state design. But do treat the approved mock as a concrete visual contract for composition, hierarchy, density, atmosphere, signature motifs, image needs, and distinctive visual moves. "North star" means "preserve the important visible ingredients in semantic code," not "use it as loose mood." +Default: Astro for brand briefs, the project's existing framework for product briefs. Ask once; don't re-ask mid-task. ## Step 1: Shape the Design -Run /impeccable shape, passing along whatever feature description the user provided. +Run /impeccable shape, passing along whatever feature description the user provided. Shape is **required** for craft; it is what produces a confirmed direction. -Wait for the design brief to be fully confirmed by the user before proceeding. The brief is your blueprint, and every implementation decision should trace back to it. +Present the shape output and stop. Wait for the user to confirm, override, or course-correct before writing code. -If this craft run resumed after `teach` created PRODUCT.md, run shape now. Do not treat the teach interview, PRODUCT.md, or a summary of project context as a substitute for shape. Shape is task-specific and must cover scope, content/states, visual direction, constraints, anti-goals, probes when applicable, and explicit brief confirmation. +If the user already supplied a confirmed brief or ran shape separately, use it and skip this step. -If the user has already run /impeccable shape and has a confirmed design brief, skip this step and use the existing brief. +When the original prompt + PRODUCT.md already answer scope, content, and visual direction with no real ambiguity, the shape output can be **compact** (3-5 bullets stating what you're building and the visual lane, ending with one or two specific questions or "confirm or override"). The full 10-section structured brief is reserved for genuinely ambiguous, multi-screen, or stakeholder-heavy tasks. Don't pad a clear brief into a long one to look thorough; equally, don't skip the pause to look efficient. ## Step 2: Load References @@ -55,79 +53,60 @@ Then add references based on the brief's needs: ## Step 3: Land the Visual Direction (Capability-Gated) -Before implementation, generate high-fidelity visual comps when all of these are true: +Generate high-fidelity visual comps before implementation when all three are true: -- The work is **net-new** or visually open-ended enough that composition exploration will improve the build. -- The brief's scope is **mid-fi, high-fi, or production-ready**. -- The current harness has **built-in image generation capability** (for example, Codex with a native image tool). Do **not** ask the user to set up external APIs, shell scripts, or one-off tooling just to do this. +- The work is net-new or visually open-ended enough that composition exploration will improve the build. +- The brief's scope is mid-fi, high-fi, or production-ready. +- The harness gives you native image generation (Codex's `image_gen`, an equivalent MCP tool). Don't ask the user to set up external APIs. -When those conditions are met, this step is mandatory for **both brand and product work** in Codex and any harness with built-in image generation. Use native image generation; in Codex, use the built-in `image_gen` tool via the imagegen skill. If image generation is unavailable, do not ask the user to install APIs or tooling. State in one line that the image step is skipped because the harness lacks native image generation, then proceed. - -Do not skip this step because the eventual UI should be semantic, editable, code-native, responsive, or accessible. Those are implementation requirements, not reasons to avoid visual exploration. - -### Purpose - -Use the mock step to find a stronger visual lane than code-first generation would reliably discover on its own. The brief remains authoritative on user, purpose, content, constraints, states, and anti-goals. The mock clarifies composition, hierarchy, density, typography, and visual tone. +When met, this step is mandatory for both brand and product work. If image generation isn't available, skip silently. "The eventual UI is semantic/code-native/accessible" is not a reason to skip; those are implementation requirements, not exploration ones. ### What to generate -Generate **1 to 3** high-fidelity north-star comps based on the confirmed brief. If shape already produced direction probes, use those results as input and generate a more resolved mock from the winning lane, not another unrelated exploration. +Generate **1 to 3** high-fidelity north-star comps from the confirmed brief. If shape already produced direction probes, resolve the winning lane further, not an unrelated exploration. Comps must differ in primary visual direction, not just color. -- For brand work, push visual identity, composition, and mood aggressively. -- For product work, still push hierarchy, topology, density, and tone, but keep the comps grounded in realistic product structure and states. -- For landing pages and long-form brand surfaces, show enough of the next section or second fold to establish the system beyond the hero. - -The comps must be genuinely different in primary visual direction, not just color variants. +- Brand work: push visual identity, composition, and mood aggressively. +- Product work: push hierarchy, topology, density, tone, grounded in realistic product structure. +- Landing pages and long-form brand surfaces: show enough of the second fold to establish the system beyond the hero. ### Approval loop -Show the comps and ask what should carry forward. If the user asks for changes or the best direction is still weak, generate a focused revision before implementation. Continue until one direction is approved, or until the user explicitly delegates the choice. +Show the comps and ask what carries forward. Iterate until one direction is approved or the user delegates. If the user delegates, pick the strongest direction and explain it from the brief, not personal taste. -If the user delegates, pick the strongest direction and explain the decision using the brief, not personal taste. - -Before moving to implementation, summarize: - -- What to carry into code -- What **not** to literalize from the mock - -This summary is required before Step 4. It is the handoff between visual exploration and semantic implementation. +Before Step 4, summarize what to carry into code and what **not** to literalize from the mock. This is the handoff between visual exploration and semantic implementation. ### Mock fidelity inventory -Before building, inventory the approved mock's major visible ingredients: +Inventory the approved mock's major visible ingredients: -- Hero silhouette and dominant composition. -- Signature motifs: planets, devices, portraits, charts, route lines, insets, badges, or other memorable objects. -- Nav and primary CTA treatment. -- Section sequence visible in the mock, especially the second fold. -- Image-native content the concept depends on. -- Typography, density, color/material treatment, and motion cues. +- Hero silhouette and dominant composition +- Signature motifs (planets, devices, portraits, charts, route lines, insets, badges, etc.) +- Nav and primary CTA treatment +- Section sequence, especially the second fold +- Image-native content the concept depends on +- Typography, density, color/material treatment, motion cues -For each ingredient, decide how it will be implemented: semantic HTML/CSS/SVG, generated asset, sourced project asset, icon library, canvas/WebGL, or an explicitly accepted omission. Do not substitute a different hero composition or new visual driver after approval unless the user approves the change. +For each, decide implementation: semantic HTML/CSS/SVG, generated asset, sourced asset, icon library, canvas/WebGL, or accepted omission. Don't substitute a different hero composition or visual driver post-approval without user sign-off. -Treat the mock as a **north star**, not a screenshot to trace. Do **not** rasterize core UI text or let the mock override the confirmed brief. But if the live result lacks the mock's major visible ingredients, the implementation is wrong. +If a photographic, architectural, product, or place-led mock becomes generic CSS scenery / decorative diagrams / bullets / copy, stop and fix it. That's a broken implementation, not a harmless interpretation. + +Treat the mock as a north star, not a screenshot to trace. Don't rasterize core UI text. But if the live result lacks the mock's major ingredients, the implementation is wrong. ## Step 4: Asset Extraction (Need-Gated) -If the chosen direction includes image-native visual ingredients that would materially improve the implementation, generate them as separate assets before building. +If the approved direction needs raster assets, create them before building. Do not replace required imagery with generic cards, bullets, emoji, fake metrics, decorative CSS panels, or filler copy. -Good candidates: +Use the native asset producer (`impeccable_asset_producer` in Codex, `impeccable-asset-producer` in Claude Code) to create clean assets from the hi-fi mock and crops. If you do not have explicit permission to use agents, stop and ask: -- stickers -- badges -- seals -- tickets -- graphic labels -- textures -- abstract objects -- decorative marks -- non-semantic scene elements +```text +Asset production will work better as a scoped subagent job. Should I spawn the Impeccable asset producer subagent for this step? +``` -For travel, editorial, portfolio, venue, product showcase, entertainment, education, or any other image-led brand surface, visual assets are usually core content, not decoration. Do not ship abstract CSS panels where the approved mock or subject matter calls for real imagery, generated plates, illustrations, maps, product/object renders, or destination scenes. +Do not skip asset production or silently do it inline. Inline asset production is allowed only if the user declines subagents, the harness cannot spawn the authorized agent, or the user explicitly asks for single-thread mode. -Do **not** export assets for core UI text, navigation, body copy, or any structure that should stay semantic and editable in code. +Pass the approved mock, crop/contact-sheet paths, output directory, dimensions/formats, transparency needs, constraints, and avoid list to the asset producer. Attach image generation capability to the spawned agent when the harness supports it; do not load image-generation reference material into the parent thread first. -Usually **1 to 5** extracted assets is enough. If the design can be built cleanly in HTML/CSS/SVG, prefer that over raster assets. If the mock contains major visual content that cannot be built credibly in code, asset extraction is not optional. +Prefer HTML/CSS/SVG/canvas when they can credibly reproduce an ingredient; use real/generated/stock imagery when the mock or subject matter calls for actual visual content. ## Step 5: Build to Production Quality @@ -135,50 +114,35 @@ Implement the feature following the design brief. Build in passes so structure, ### Production bar -- Use real or realistic content. Remove placeholder copy, placeholder images, dead links, fake controls, and unused scaffold before presenting. -- Preserve the approved mock's major ingredients. Missing hero objects, missing world/product imagery, different section structure, downgraded CTA/nav treatment, or generic replacements for distinctive motifs are blocking defects unless the user accepted the change. -- Build semantically first: real headings, landmarks, labels, form associations, button/link semantics, accessible names, and state announcements where needed. -- Calibrate spacing, alignment, grid placement, and vertical rhythm deliberately. Do not accept default gaps, arbitrary margins, unbalanced whitespace, or accidental optical misalignment. -- Make typography intentional: chosen font loading strategy, clear hierarchy, readable measure, stable line breaks, tuned wrapping, and no overflow at mobile or large desktop sizes. -- Design realistic state coverage: default, hover where supported, focus-visible, active, disabled, loading, error, success, empty, overflow, long text, short text, and first-run states where relevant. -- Make interaction quality feel finished: keyboard paths, touch targets, feedback timing, scroll behavior, transitions between states, and no hover-only functionality. -- Use icons from the project's established icon set when available. If no set exists, choose a coherent library or use accessible text controls; do not mix unrelated icon styles. -- Optimize imagery and media: correct dimensions, useful alt text, lazy loading below the fold, modern formats when practical, responsive `srcset` / `picture` for raster assets, and no project-referenced asset left outside the workspace. -- Make motion feel premium: use atmospheric blur, filter, mask, shadow, or reveal effects when they improve the experience; avoid casual layout-property animation, bound expensive effects, verify smoothness in-browser, respect reduced motion, and avoid choreography that blocks task completion. -- Preserve maintainability: reusable local patterns, clear component boundaries, project conventions, no rasterized UI text, and no hard-coded one-off hacks when a better local pattern exists. -- Fit the technical context: production build passes, no obvious console errors, no avoidable layout shift, no needless dependency, and no broken asset path. -- If you discover a design question that materially changes the brief or approved direction, stop and ask rather than guessing. +- **Real content.** No placeholder copy, placeholder images, dead links, fake controls, or unused scaffold at presentation time. +- **Preserve the approved mock's major ingredients.** Missing hero objects, world/product imagery, section structure, CTA/nav treatment, or distinctive motifs are blocking defects unless the user accepted the change. +- **Semantic first.** Real headings, landmarks, labels, form associations, button/link semantics, accessible names, state announcements where needed. +- **Deliberate spacing and alignment.** No default gaps, arbitrary margins, unbalanced whitespace, or accidental optical misalignment. +- **Intentional typography.** Chosen loading strategy, clear hierarchy, readable measure, stable line breaks, no overflow at any width. +- **Realistic state coverage.** Default, hover, focus-visible, active, disabled, loading, error, success, empty, overflow, long/short text, first-run. +- **Finished interaction quality.** Keyboard paths, touch targets, feedback timing, scroll behavior, state transitions, no hover-only functionality. +- **Coherent icon set.** Use the project's established set; otherwise pick one library or use accessible text. Don't mix. +- **Respect the build pipeline.** Edit source files and run the project's build (`npm run build` or equivalent). Don't write to `build/` / `dist/` / `.next/` with `cat`, heredoc, or Bash redirects; that skips asset hashing, image optimization, code splitting, and CSS extraction, and produces output the dev server won't serve. +- **Verify image URLs before referencing them.** Use image-search MCP or web-fetch when available; guessed photo IDs ship as broken-image placeholders. Without verification, prefer fewer images you're confident about. +- **Optimized imagery and media.** Correct dimensions, useful alt text, lazy loading below the fold, modern formats when practical, responsive `srcset`/`picture` for raster, no project-referenced asset left outside the workspace. +- **Premium motion.** Use atmospheric blur, filter, mask, shadow, reveal when they improve the experience. Avoid casual layout-property animation, bound expensive effects, verify smoothness in-browser, respect reduced motion, and avoid choreography that blocks task completion. +- **Maintainable.** Reusable local patterns, clear component boundaries, project conventions. No rasterized UI text or one-off hacks when a local pattern exists. +- **Technically clean.** Production build passes, no console errors, no avoidable layout shift, no needless dependencies, no broken asset paths. +- **Ask when uncertain.** If a discovery materially changes the brief or approved direction, stop and ask. Don't guess. -## Step 6: Browser-Based Iteration +## Step 6: Iterate Visually -**This step is critical.** Do not stop after the first implementation pass. +Look at what you built like a designer would. Your eyes are whatever the harness gives you: a connected browser, a screenshotting tool, Playwright, or asking the user. Use them for responsive testing (mobile, tablet, desktop minimum) and general visual validation. -Open the result in a browser. In Codex, use browser-use or equivalent browser automation when available; otherwise use Playwright or ask the user for screenshots. Inspect screenshots, not just DOM or terminal output. +If your tool returns a file path, read the PNG back into the conversation. A screenshot you didn't read doesn't count. -### Required viewport pass +For long-form brand surfaces, inspect major sections individually. Thumbnails hide spacing, clipping, and cascade defects. -Check the experience at the viewports that matter for the brief. Default minimum: +After the first pass, write an honest critique against the brief, the approved mock's major ingredients (hero silhouette, motifs, imagery, nav/CTA, density), and impeccable's DON'Ts. Patch material defects and re-inspect. **Don't invent defects to demonstrate iteration.** A confident "first pass clean, shipping" beats a fake fix. -- Mobile narrow -- Tablet or small laptop -- Desktop wide +Actively check: responsive behavior (composes, not shrinks), every state (empty / error / loading / edge), craft details (spacing, alignment, hierarchy, contrast, motion timing, focus), performance basics. The exit bar: defensible in a high-end studio review. -For each viewport, capture or inspect the rendered state and look for visual defects: overlap, clipping, weak hierarchy, off-grid alignment, awkward whitespace, cramped controls, unreadable type, broken imagery, hover-only functionality, layout shift, and text overflow. - -### Critique and fix loop - -After the first browser pass, write a short critique for yourself and patch the implementation. Repeat browser inspection after fixes. Continue until no material issues remain against this checklist: - -1. **Does it match the brief?** Compare the live result against every section of the design brief. Fix discrepancies. -2. **Does it match the approved mock?** Compare screenshots against the mock fidelity inventory: hero silhouette, major motifs, imagery, nav/CTA, section sequence, density, color/materials, and second-fold substance. Missing major ingredients are P0 defects. -3. **Does it pass the AI slop test?** If someone saw this and said "AI made this," would they believe it immediately? If yes, it needs more design intention. -4. **Check against impeccable's DON'T guidelines.** Fix any anti-pattern violations. -5. **Check every state.** Navigate through empty, error, loading, and edge case states. Each one should feel intentional, not like an afterthought. -6. **Check responsive behavior.** The design should adapt compositionally, not merely shrink. -7. **Check craft details.** Spacing consistency, optical alignment, type hierarchy, color contrast, image quality, icon coherence, interactive feedback, motion timing, and focus treatment. -8. **Check performance basics.** No obviously oversized images, avoidable layout thrash, blocking animations, or heavy assets without a reason. - -The exit bar is not "it works." It is: the rendered result looks intentional at all checked viewports, all expected states are handled, no placeholders remain unless explicitly accepted, and the implementation quality would be defensible in a high-end studio review. +Detector or QA output is defect evidence only; never proof the work is finished. ## Step 7: Present @@ -189,5 +153,3 @@ Present the result to the user: - Explain design decisions that connect back to the design brief and, when used, the chosen north-star mock. Include any accepted deviations from the mock; do not hide unimplemented mock ingredients. - Note any remaining limitations or follow-up risks honestly - Ask: "What's working? What isn't?" - -Iterate based on feedback. Good design is rarely right on the first pass. diff --git a/.qoder/skills/impeccable/reference/critique.md b/.qoder/skills/impeccable/reference/critique.md index 1c8485b81..d5563b0d3 100644 --- a/.qoder/skills/impeccable/reference/critique.md +++ b/.qoder/skills/impeccable/reference/critique.md @@ -43,7 +43,7 @@ Run the bundled deterministic detector, which flags 27 specific patterns (AI slo **CLI scan**: ```bash -npx impeccable --json [--fast] [target] +npx impeccable detect --json [--fast] [target] ``` - Pass HTML/JSX/TSX/Vue/Svelte files or directories as `[target]` (anything with markup). Do not pass CSS-only files. diff --git a/.qoder/skills/impeccable/reference/polish.md b/.qoder/skills/impeccable/reference/polish.md index a2a409e48..eed3dbd27 100644 --- a/.qoder/skills/impeccable/reference/polish.md +++ b/.qoder/skills/impeccable/reference/polish.md @@ -2,6 +2,8 @@ Perform a meticulous final pass to catch all the small details that separate good work from great work. The difference between shipped and polished. +Detector and automated QA output are defect evidence only. A clean script result is never proof that the design is strong; gather browser evidence and inspect the real interaction path. + ## Design System Discovery Aligning the feature to the design system is **not optional**. Polish without alignment is decoration on top of drift, and it makes the next person's job harder. Discovery comes before any other polish work. @@ -216,11 +218,12 @@ Sweat the details. Zoom in until the alignment is right and the spacing reads as Before marking as done: -- **Use it yourself**: Actually interact with the feature -- **Test on real devices**: Not just browser DevTools -- **Ask someone else to review**: Fresh eyes catch things -- **Compare to design**: Match intended design -- **Check all states**: Don't just test happy path +- **Use it yourself**: Actually interact with the feature. +- **Test on real devices**: Not just browser DevTools. +- **Ask someone else to review**: Fresh eyes catch things. +- **Compare to design**: Match intended design. +- **Check all states**: Don't just test happy path. +- **Treat automation carefully**: Run detector or QA commands when they are available and relevant, fix their defects, but never cite a clean result as proof that the work is polished. ## Clean Up @@ -230,4 +233,3 @@ After polishing, ensure code quality: - **Remove orphaned code**: Delete unused styles, components, or files made obsolete by polish. - **Consolidate tokens**: If you introduced new values, check whether they should be tokens. - **Verify DRYness**: Look for duplication introduced during polishing and consolidate. - diff --git a/.qoder/skills/impeccable/reference/shape.md b/.qoder/skills/impeccable/reference/shape.md index 0785187ef..d1c983ff4 100644 --- a/.qoder/skills/impeccable/reference/shape.md +++ b/.qoder/skills/impeccable/reference/shape.md @@ -16,14 +16,16 @@ This is a required interaction, not optional guidance. Ask these questions in co ### Interview cadence -Discovery must include at least one user-answer round unless PRODUCT.md, DESIGN.md, or an already-confirmed brief directly answers the needed design inputs. With a sparse prompt, do **not** synthesize a complete brief for confirmation on the first response. +Discovery includes at least one user-answer round unless PRODUCT.md, DESIGN.md, or an already-confirmed brief directly answers the needed inputs. With a sparse prompt, do **not** synthesize a complete brief for confirmation on the first response. - Use the harness's structured question tool when one exists. Otherwise, ask directly in chat and stop. - Ask **2-3 questions per round**, then wait for answers. - Treat PRODUCT.md and DESIGN.md as anchors; they reduce repeated questions but do **not** replace shape for craft. Shape is task-specific. -- Round 1 should clarify purpose, audience/context, and success or emotional outcome. -- Round 2 should clarify content/data/states and scope/fidelity. -- Round 3 should clarify visual direction, constraints, and anti-goals when still unresolved. +- One round is the default. Add a second only if the first answers leave material gaps. Don't run a second round just to feel thorough. +- Round 1 should clarify purpose, audience/context, content/scope, and (for brand) visual direction. +- Round 2, when needed, fills in whatever's still genuinely missing. + +**Assert-then-confirm, not menu-with-escape.** When PRODUCT.md and the user's prompt make one option obvious, name it and ask the user to confirm or override. Don't enumerate "Restrained / Committed / Or something else?" as a real choice; "This reads as Restrained, confirm?" beats a four-option menu when the answer is already clear. ### Purpose & Context - What is this feature for? What problem does it solve? @@ -36,6 +38,7 @@ Discovery must include at least one user-answer round unless PRODUCT.md, DESIGN. - What are the realistic ranges? (Minimum, typical, maximum, e.g., 0 items, 5 items, 500 items) - What are the edge cases? (Empty state, error state, first-time use, power user) - Is any content dynamic? What changes and how often? +- What visual assets are real content here? Note required images, product shots, illustrations, maps, textures, diagrams, generated objects, or existing project assets. ### Design Direction @@ -72,9 +75,9 @@ After the discovery interview, generate a small set of visual direction probes * - The work is **net-new** or directionally ambiguous enough that visual exploration will clarify the brief. - The requested fidelity is **mid-fi, high-fi, or production-ready**. Skip for sketch-only planning. -- The current harness has **built-in image generation capability** (for example, Codex with a native image tool). Do **not** ask the user to set up external APIs, shell scripts, or one-off tooling just to do this. +- The current harness gives you native image generation (Codex's `image_gen`, an equivalent MCP tool, or similar). Don't ask the user to install APIs or tooling. -When those conditions are met, this step is mandatory for Codex and any harness with built-in image generation. Use native image generation; in Codex, use the built-in `image_gen` tool via the imagegen skill. If image generation is unavailable, do not ask the user to install APIs or tooling. State in one line that the image step is skipped because the harness lacks native image generation, then proceed. +When those conditions are met, this step is mandatory. If image generation isn't natively available, skip silently and proceed; don't announce the skip. Use probes to explore visual lanes, not to replace the brief. @@ -104,11 +107,20 @@ The probes should differ in primary visual direction (hierarchy, topology, densi - Do **not** treat generated imagery as final UX specification, final copy, or final accessibility behavior. - Do **not** use this step for minor refinements of existing work. It's for shaping a new surface or clarifying a big directional choice. -If image generation is unavailable, or the task doesn't benefit from it, skip this phase only with a one-line reason and proceed directly to the design brief. +If image generation isn't natively available, skip this phase silently and proceed. ## Phase 2: Design Brief -After the interview and any required probes, synthesize everything into a structured design brief. Present it to the user for explicit confirmation before considering this command complete. Stop after asking for confirmation; do not proceed to craft or implementation in the same response unless the user has already approved the brief. +After the interview and any required probes, present a brief and **end your response**. The user must confirm before any implementation runs. Do not present a brief and then continue to code in the same response, even if the brief feels obvious to you. The user's confirmation is the gate. + +**Choose the brief shape based on how clear the answers are:** + +- **Compact form (3-5 bullets)** when discovery was crisp and the original prompt + PRODUCT.md already pinned scope, content, and direction. State what you're building, the visual lane, and end with one or two specific questions or a clear "confirm or override?" prompt. This is the default for typical craft requests with a clear prompt. +- **Full structured form (sections below)** when the task is genuinely ambiguous, multi-screen, or when the user asked for shape as a standalone step. Use this when the discipline of structure earns its weight. + +Don't pad a clear brief into a long one to look thorough. A 70-line brief restating answers the user just gave is noise, not rigor. Equally, don't skip the confirmation pause to look efficient: the pause is the point. + +If the user already said "approved" or "go" during discovery for the *exact direction you'd present*, that counts as confirmation; you may proceed without asking again. But if your brief adds anything the user hasn't seen and approved, you must stop and confirm. ### Brief Structure @@ -136,16 +148,18 @@ List every state the feature needs: default, empty, loading, error, success, edg How users interact with this feature. What happens on click, hover, scroll? What feedback do they get? What's the flow from entry to completion? **8. Content Requirements** -What copy, labels, empty state messages, error messages, and microcopy are needed. Note any dynamic content and its realistic ranges. +What copy, labels, empty state messages, error messages, and microcopy are needed. Note any dynamic content and its realistic ranges. For image-led surfaces, also list the required image/media roles and their likely source (project asset, generated raster, semantic SVG/CSS, canvas/WebGL, icon library, or accepted omission). **9. Recommended References** Based on the brief, list which impeccable reference files would be most valuable during implementation (e.g., spatial-design.md for complex layouts, motion-design.md for animated features, interaction-design.md for form-heavy features). **10. Open Questions** -Anything unresolved that the implementer should resolve during build. +Anything genuinely unresolved. Don't list "open questions" you've already recommended a default for; assert the default and move on. If you'd write `Recommend: X` next to a question, just decide X. --- -ask the user directly to clarify what you cannot infer. Ask for explicit confirmation of the brief before finishing. If the user disagrees with any part, revisit the relevant discovery questions. A shape run is incomplete until the brief is confirmed. +ask the user directly to clarify what you cannot infer. + +If the user disagrees with any part, revisit the relevant discovery questions. A shape run is incomplete until the user confirms direction (or the user already gave a clear go during discovery, which counts). Once confirmed, the brief is complete. The user can now hand it to /impeccable, or use it to guide any other implementation approach. (If the user wants the full discovery-then-build flow in one step, they should use /impeccable craft instead, which runs this command internally.) diff --git a/.rovodev/skills/impeccable/SKILL.md b/.rovodev/skills/impeccable/SKILL.md index 24ded37d7..125b66ec4 100644 --- a/.rovodev/skills/impeccable/SKILL.md +++ b/.rovodev/skills/impeccable/SKILL.md @@ -11,28 +11,15 @@ allowed-tools: Designs and iterates production-grade frontend interfaces. Real working code, committed design choices, exceptional craft. -## Setup (non-optional) +## Setup -Before any design work or file edits, pass these gates. Skipping them produces generic output that ignores the project. +Before any design work or file edits: -| Gate | Required check | If fail | -|---|---|---| -| Context | The PRODUCT.md / DESIGN.md loader result is known from `node .rovodev/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. | +1. Load context (PRODUCT.md / DESIGN.md) via the loader script. +2. Identify the register and load the matching register reference (brand.md or product.md). +3. **If the user invoked a sub-command (e.g. `craft`, `shape`, `audit`), load its reference file too.** This is non-negotiable: `craft` without `craft.md` loaded means you'll skip the shape-and-confirm step the user expects. -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: 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. +Skipping these produces generic output that ignores the project. ### 1. Context gathering diff --git a/.rovodev/skills/impeccable/reference/brand.md b/.rovodev/skills/impeccable/reference/brand.md index b069f2553..3d83a1cdc 100644 --- a/.rovodev/skills/impeccable/reference/brand.md +++ b/.rovodev/skills/impeccable/reference/brand.md @@ -12,6 +12,8 @@ Brand isn't a neutral register. AI-generated landing pages have flooded the inte **The second slop test: aesthetic lane.** Before committing to moves, name the reference. A Klim-style specimen page is one lane; Stripe-minimal is another; Liquid-Death-acid-maximalism is another. Don't drift into editorial-magazine aesthetics on a brief that isn't editorial. A hiking brand with Cormorant italic drop caps has the wrong register within the register. +Then the inverse test: in one sentence, describe what you're about to build the way a competitor would describe theirs. If that sentence fits the modal landing page in the category, restart. + ## Typography ### Font selection procedure @@ -66,6 +68,7 @@ Brand surfaces have permission for Committed, Full palette, and Drenched strateg - Palette IS voice. A calm brand and a restless brand should not share palette mechanics. - When the strategy is Committed or Drenched, color carries the brand. Don't hedge with neutrals around the edges. Commit. - Don't converge across projects. If the last brand surface was restrained-on-cream, this one is not. +- When a cultural-symbol palette is the obvious pull, reach past it. Let the cultural reading come from typography, imagery, and copy, not the palette. ## Layout @@ -79,14 +82,14 @@ Brand surfaces have permission for Committed, Full palette, and Drenched strateg Brand surfaces lean on imagery. A restaurant, hotel, magazine, or product landing page without any imagery reads as incomplete, not as restrained. A solid-color rectangle where a hero image should go is worse than a representative stock photo. -**When the brief implies imagery (restaurants, hotels, magazines, photography, hobbyist communities, food, travel, fashion, product), you must ship imagery.** Zero images is a bug, not a design choice. "Restraint" is not an excuse. +**When the brief implies imagery (restaurants, hotels, magazines, photography, hobbyist communities, food, travel, fashion, product), you must ship imagery.** Zero images is a bug, not a design choice. "Restraint" is not an excuse. If the approved comp or brief is image-led, ship real project assets, generated raster assets, or a credible canvas/SVG/WebGL scene. Do not replace photographic, architectural, product, or place imagery with generic CSS panels, decorative diagrams, cards, bullets, or copy. -- **For greenfield work without local assets, use stock imagery.** Unsplash is the default. The URL shape is `https://images.unsplash.com/photo-{id}?auto=format&fit=crop&w=1600&q=80`. Pick real Unsplash photo IDs you're confident exist (`photo-1559339352-11d035aa65de`, `photo-1590490360182-c33d57733427`, etc.); if unsure, pick fewer photos but don't substitute colored `
` placeholders. +- **For greenfield work without local assets, use stock imagery.** Unsplash is the default. The URL shape is `https://images.unsplash.com/photo-{id}?auto=format&fit=crop&w=1600&q=80`. **Verify the URLs before referencing them.** If you have an image-search MCP, web-fetch tool, or browser access, use it to find real photo IDs and confirm they resolve. Guessed IDs (even ones that look real) often 404 and ship as broken-image placeholders. Without a verification path, pick fewer photos you're confident exist over more that you guessed; never substitute colored `
` placeholders. - **Search for the brand's physical object**, not the generic category: "handmade pasta on a scratched wooden table" beats "Italian food"; "cypress trees above a limestone hotel facade at dusk" beats "luxury hotel". - **One decisive photo beats five mediocre ones.** Hero imagery should commit to a mood; padding with more stock doesn't rescue an indecisive one. - **Alt text is part of the voice.** "Coastal fettuccine, hand-cut, served on the terrace" beats "pasta dish". -Tech / dev-tool brands are the exception where zero imagery can be correct; a developer landing page often carries its voice through typography, code samples, diagrams. Know which kind of brand you're working on. +"Imagery" here is broader than stock photography: product screenshots, custom data visualizations, generated SVG, and canvas/WebGL scenes are all imagery. Text-only pages where typography alone carries the entire visual weight are the failure mode. ## Motion @@ -102,6 +105,7 @@ Tech / dev-tool brands are the exception where zero imagery can be correct; a de - Timid palettes and average layouts. Safe = invisible. - Zero imagery on a brief that implies imagery (restaurant, hotel, food, travel, fashion, photography, hobbyist). Colored blocks where a hero photo belongs. - Defaulting to editorial-magazine aesthetics (display serif + italic + drop caps + broadsheet grid) on briefs that aren't magazine-shaped. Editorial is ONE aesthetic lane, not the default brand aesthetic. +- Repeated tiny uppercase tracked labels above every section heading. A single strong kicker can be voice; repeating it as section grammar is AI scaffolding unless it's a deliberate, named brand system. ## Brand permissions diff --git a/.rovodev/skills/impeccable/reference/craft.md b/.rovodev/skills/impeccable/reference/craft.md index bdeee0294..c0cfa7460 100644 --- a/.rovodev/skills/impeccable/reference/craft.md +++ b/.rovodev/skills/impeccable/reference/craft.md @@ -1,43 +1,41 @@ # Craft Flow -Build a feature with impeccable UX and UI quality through a structured process: shape the design, land the visual direction, build real production code, then inspect and improve in-browser until the result meets a high-end studio bar. +Build a feature with impeccable UX and UI quality: shape the design, land the visual direction, build real production code, inspect and improve in-browser until it meets a high-end studio bar. -## Build Gate +Before writing code, you need: PRODUCT.md loaded, register identified and the matching reference loaded, and a confirmed design direction for this task (either from `shape` or supplied by the user). PRODUCT.md is project context, not a task-specific brief. -Craft cannot build until all of these are true: +Treat any approved visual direction (generated mock or stated reference) as a concrete contract for composition, hierarchy, density, atmosphere, signature motifs, and distinctive visual moves. Don't let mocks replace structure, copy, accessibility, or state design. But if the live result lacks the approved direction's major ingredients, the implementation is wrong. -1. PRODUCT context is valid and current. -2. The shape design brief is explicitly confirmed by the user for this task, unless the user already provided a confirmed brief. -3. Implementation references from the brief are loaded. -4. The shape visual probe decision is recorded: generated, skipped with reason, or already resolved. -5. The north-star mock decision is recorded: generated, skipped with reason, or not applicable. +## Step 0: Project Foundation -PRODUCT.md and `teach` answers do **not** satisfy the shape gate. They are project context only. A compact self-authored brief does not satisfy the shape gate either. `shape=pass` requires a separate user response approving the shape brief or an already-confirmed brief supplied by the user. +Before shape, before code: figure out what kind of project you're working in. -Invalid image-skip reasons include: "the final implementation will be semantic HTML/CSS/SVG", "the diagram should stay editable", "a raster mock would not be used directly", or "the product is fictional." Generated probes and mocks are direction artifacts; they are not implementation assets. +Look at the working directory. Run `ls`. Check for: -## Craft Contract +- An existing framework: `astro.config.mjs/ts`, `next.config.js/ts`, `nuxt.config.ts`, `svelte.config.js`, `vite.config.js/ts`, `package.json` with framework deps, `Cargo.toml` + Leptos/Yew, `Gemfile` + Rails. **If found, use it.** Do not start a parallel build, do not introduce a second framework, do not write to `dist/` or `build/` directly. Whatever pipeline the project has, respect it. +- An existing component library or design system: `src/components/`, `app/components/`, a `tokens.css` / `theme.ts`, an `astro.config` `integrations`. Read what's there before adding to it. +- An existing icon set: `lucide-react`, `@phosphor-icons/react`, `@iconify/*`, hand-rolled SVG sprites in `assets/icons/`. **Use what's already in the project**; don't introduce a second set. -Craft is not a first pass. It is a loop with these required artifacts: +If the directory is empty (greenfield), don't pick a framework silently. Ask the user via the AskUserQuestion tool, with sensible defaults framed by the brief: -1. Confirmed design brief from `shape`. -2. Approved visual direction, from generated probes / mocks when image generation is available. -3. Mock fidelity inventory: the visible ingredients from the approved direction that must survive into code. -4. Semantic, functional implementation using the project's real stack and conventions. -5. Browser evidence across relevant viewports. -6. At least one critique-and-fix pass after the first browser inspection, unless the first pass has no material defects. +```text +What should this be built on? + - Astro (default for content-led brand sites, landing pages, marketing surfaces) + - SvelteKit / Next.js / Nuxt (when the brief implies an app surface or significant interactivity) + - Single index.html (one-shot demo, prototype, or a deliberately framework-free experiment) +``` -Do not let generated mockups replace interface structure, copy, accessibility, responsive behavior, or state design. But do treat the approved mock as a concrete visual contract for composition, hierarchy, density, atmosphere, signature motifs, image needs, and distinctive visual moves. "North star" means "preserve the important visible ingredients in semantic code," not "use it as loose mood." +Default: Astro for brand briefs, the project's existing framework for product briefs. Ask once; don't re-ask mid-task. ## Step 1: Shape the Design -Run /impeccable shape, passing along whatever feature description the user provided. +Run /impeccable shape, passing along whatever feature description the user provided. Shape is **required** for craft; it is what produces a confirmed direction. -Wait for the design brief to be fully confirmed by the user before proceeding. The brief is your blueprint, and every implementation decision should trace back to it. +Present the shape output and stop. Wait for the user to confirm, override, or course-correct before writing code. -If this craft run resumed after `teach` created PRODUCT.md, run shape now. Do not treat the teach interview, PRODUCT.md, or a summary of project context as a substitute for shape. Shape is task-specific and must cover scope, content/states, visual direction, constraints, anti-goals, probes when applicable, and explicit brief confirmation. +If the user already supplied a confirmed brief or ran shape separately, use it and skip this step. -If the user has already run /impeccable shape and has a confirmed design brief, skip this step and use the existing brief. +When the original prompt + PRODUCT.md already answer scope, content, and visual direction with no real ambiguity, the shape output can be **compact** (3-5 bullets stating what you're building and the visual lane, ending with one or two specific questions or "confirm or override"). The full 10-section structured brief is reserved for genuinely ambiguous, multi-screen, or stakeholder-heavy tasks. Don't pad a clear brief into a long one to look thorough; equally, don't skip the pause to look efficient. ## Step 2: Load References @@ -55,79 +53,60 @@ Then add references based on the brief's needs: ## Step 3: Land the Visual Direction (Capability-Gated) -Before implementation, generate high-fidelity visual comps when all of these are true: +Generate high-fidelity visual comps before implementation when all three are true: -- The work is **net-new** or visually open-ended enough that composition exploration will improve the build. -- The brief's scope is **mid-fi, high-fi, or production-ready**. -- The current harness has **built-in image generation capability** (for example, Codex with a native image tool). Do **not** ask the user to set up external APIs, shell scripts, or one-off tooling just to do this. +- The work is net-new or visually open-ended enough that composition exploration will improve the build. +- The brief's scope is mid-fi, high-fi, or production-ready. +- The harness gives you native image generation (Codex's `image_gen`, an equivalent MCP tool). Don't ask the user to set up external APIs. -When those conditions are met, this step is mandatory for **both brand and product work** in Codex and any harness with built-in image generation. Use native image generation; in Codex, use the built-in `image_gen` tool via the imagegen skill. If image generation is unavailable, do not ask the user to install APIs or tooling. State in one line that the image step is skipped because the harness lacks native image generation, then proceed. - -Do not skip this step because the eventual UI should be semantic, editable, code-native, responsive, or accessible. Those are implementation requirements, not reasons to avoid visual exploration. - -### Purpose - -Use the mock step to find a stronger visual lane than code-first generation would reliably discover on its own. The brief remains authoritative on user, purpose, content, constraints, states, and anti-goals. The mock clarifies composition, hierarchy, density, typography, and visual tone. +When met, this step is mandatory for both brand and product work. If image generation isn't available, skip silently. "The eventual UI is semantic/code-native/accessible" is not a reason to skip; those are implementation requirements, not exploration ones. ### What to generate -Generate **1 to 3** high-fidelity north-star comps based on the confirmed brief. If shape already produced direction probes, use those results as input and generate a more resolved mock from the winning lane, not another unrelated exploration. +Generate **1 to 3** high-fidelity north-star comps from the confirmed brief. If shape already produced direction probes, resolve the winning lane further, not an unrelated exploration. Comps must differ in primary visual direction, not just color. -- For brand work, push visual identity, composition, and mood aggressively. -- For product work, still push hierarchy, topology, density, and tone, but keep the comps grounded in realistic product structure and states. -- For landing pages and long-form brand surfaces, show enough of the next section or second fold to establish the system beyond the hero. - -The comps must be genuinely different in primary visual direction, not just color variants. +- Brand work: push visual identity, composition, and mood aggressively. +- Product work: push hierarchy, topology, density, tone, grounded in realistic product structure. +- Landing pages and long-form brand surfaces: show enough of the second fold to establish the system beyond the hero. ### Approval loop -Show the comps and ask what should carry forward. If the user asks for changes or the best direction is still weak, generate a focused revision before implementation. Continue until one direction is approved, or until the user explicitly delegates the choice. +Show the comps and ask what carries forward. Iterate until one direction is approved or the user delegates. If the user delegates, pick the strongest direction and explain it from the brief, not personal taste. -If the user delegates, pick the strongest direction and explain the decision using the brief, not personal taste. - -Before moving to implementation, summarize: - -- What to carry into code -- What **not** to literalize from the mock - -This summary is required before Step 4. It is the handoff between visual exploration and semantic implementation. +Before Step 4, summarize what to carry into code and what **not** to literalize from the mock. This is the handoff between visual exploration and semantic implementation. ### Mock fidelity inventory -Before building, inventory the approved mock's major visible ingredients: +Inventory the approved mock's major visible ingredients: -- Hero silhouette and dominant composition. -- Signature motifs: planets, devices, portraits, charts, route lines, insets, badges, or other memorable objects. -- Nav and primary CTA treatment. -- Section sequence visible in the mock, especially the second fold. -- Image-native content the concept depends on. -- Typography, density, color/material treatment, and motion cues. +- Hero silhouette and dominant composition +- Signature motifs (planets, devices, portraits, charts, route lines, insets, badges, etc.) +- Nav and primary CTA treatment +- Section sequence, especially the second fold +- Image-native content the concept depends on +- Typography, density, color/material treatment, motion cues -For each ingredient, decide how it will be implemented: semantic HTML/CSS/SVG, generated asset, sourced project asset, icon library, canvas/WebGL, or an explicitly accepted omission. Do not substitute a different hero composition or new visual driver after approval unless the user approves the change. +For each, decide implementation: semantic HTML/CSS/SVG, generated asset, sourced asset, icon library, canvas/WebGL, or accepted omission. Don't substitute a different hero composition or visual driver post-approval without user sign-off. -Treat the mock as a **north star**, not a screenshot to trace. Do **not** rasterize core UI text or let the mock override the confirmed brief. But if the live result lacks the mock's major visible ingredients, the implementation is wrong. +If a photographic, architectural, product, or place-led mock becomes generic CSS scenery / decorative diagrams / bullets / copy, stop and fix it. That's a broken implementation, not a harmless interpretation. + +Treat the mock as a north star, not a screenshot to trace. Don't rasterize core UI text. But if the live result lacks the mock's major ingredients, the implementation is wrong. ## Step 4: Asset Extraction (Need-Gated) -If the chosen direction includes image-native visual ingredients that would materially improve the implementation, generate them as separate assets before building. +If the approved direction needs raster assets, create them before building. Do not replace required imagery with generic cards, bullets, emoji, fake metrics, decorative CSS panels, or filler copy. -Good candidates: +Use the native asset producer (`impeccable_asset_producer` in Codex, `impeccable-asset-producer` in Claude Code) to create clean assets from the hi-fi mock and crops. If you do not have explicit permission to use agents, stop and ask: -- stickers -- badges -- seals -- tickets -- graphic labels -- textures -- abstract objects -- decorative marks -- non-semantic scene elements +```text +Asset production will work better as a scoped subagent job. Should I spawn the Impeccable asset producer subagent for this step? +``` -For travel, editorial, portfolio, venue, product showcase, entertainment, education, or any other image-led brand surface, visual assets are usually core content, not decoration. Do not ship abstract CSS panels where the approved mock or subject matter calls for real imagery, generated plates, illustrations, maps, product/object renders, or destination scenes. +Do not skip asset production or silently do it inline. Inline asset production is allowed only if the user declines subagents, the harness cannot spawn the authorized agent, or the user explicitly asks for single-thread mode. -Do **not** export assets for core UI text, navigation, body copy, or any structure that should stay semantic and editable in code. +Pass the approved mock, crop/contact-sheet paths, output directory, dimensions/formats, transparency needs, constraints, and avoid list to the asset producer. Attach image generation capability to the spawned agent when the harness supports it; do not load image-generation reference material into the parent thread first. -Usually **1 to 5** extracted assets is enough. If the design can be built cleanly in HTML/CSS/SVG, prefer that over raster assets. If the mock contains major visual content that cannot be built credibly in code, asset extraction is not optional. +Prefer HTML/CSS/SVG/canvas when they can credibly reproduce an ingredient; use real/generated/stock imagery when the mock or subject matter calls for actual visual content. ## Step 5: Build to Production Quality @@ -135,50 +114,35 @@ Implement the feature following the design brief. Build in passes so structure, ### Production bar -- Use real or realistic content. Remove placeholder copy, placeholder images, dead links, fake controls, and unused scaffold before presenting. -- Preserve the approved mock's major ingredients. Missing hero objects, missing world/product imagery, different section structure, downgraded CTA/nav treatment, or generic replacements for distinctive motifs are blocking defects unless the user accepted the change. -- Build semantically first: real headings, landmarks, labels, form associations, button/link semantics, accessible names, and state announcements where needed. -- Calibrate spacing, alignment, grid placement, and vertical rhythm deliberately. Do not accept default gaps, arbitrary margins, unbalanced whitespace, or accidental optical misalignment. -- Make typography intentional: chosen font loading strategy, clear hierarchy, readable measure, stable line breaks, tuned wrapping, and no overflow at mobile or large desktop sizes. -- Design realistic state coverage: default, hover where supported, focus-visible, active, disabled, loading, error, success, empty, overflow, long text, short text, and first-run states where relevant. -- Make interaction quality feel finished: keyboard paths, touch targets, feedback timing, scroll behavior, transitions between states, and no hover-only functionality. -- Use icons from the project's established icon set when available. If no set exists, choose a coherent library or use accessible text controls; do not mix unrelated icon styles. -- Optimize imagery and media: correct dimensions, useful alt text, lazy loading below the fold, modern formats when practical, responsive `srcset` / `picture` for raster assets, and no project-referenced asset left outside the workspace. -- Make motion feel premium: use atmospheric blur, filter, mask, shadow, or reveal effects when they improve the experience; avoid casual layout-property animation, bound expensive effects, verify smoothness in-browser, respect reduced motion, and avoid choreography that blocks task completion. -- Preserve maintainability: reusable local patterns, clear component boundaries, project conventions, no rasterized UI text, and no hard-coded one-off hacks when a better local pattern exists. -- Fit the technical context: production build passes, no obvious console errors, no avoidable layout shift, no needless dependency, and no broken asset path. -- If you discover a design question that materially changes the brief or approved direction, stop and ask rather than guessing. +- **Real content.** No placeholder copy, placeholder images, dead links, fake controls, or unused scaffold at presentation time. +- **Preserve the approved mock's major ingredients.** Missing hero objects, world/product imagery, section structure, CTA/nav treatment, or distinctive motifs are blocking defects unless the user accepted the change. +- **Semantic first.** Real headings, landmarks, labels, form associations, button/link semantics, accessible names, state announcements where needed. +- **Deliberate spacing and alignment.** No default gaps, arbitrary margins, unbalanced whitespace, or accidental optical misalignment. +- **Intentional typography.** Chosen loading strategy, clear hierarchy, readable measure, stable line breaks, no overflow at any width. +- **Realistic state coverage.** Default, hover, focus-visible, active, disabled, loading, error, success, empty, overflow, long/short text, first-run. +- **Finished interaction quality.** Keyboard paths, touch targets, feedback timing, scroll behavior, state transitions, no hover-only functionality. +- **Coherent icon set.** Use the project's established set; otherwise pick one library or use accessible text. Don't mix. +- **Respect the build pipeline.** Edit source files and run the project's build (`npm run build` or equivalent). Don't write to `build/` / `dist/` / `.next/` with `cat`, heredoc, or Bash redirects; that skips asset hashing, image optimization, code splitting, and CSS extraction, and produces output the dev server won't serve. +- **Verify image URLs before referencing them.** Use image-search MCP or web-fetch when available; guessed photo IDs ship as broken-image placeholders. Without verification, prefer fewer images you're confident about. +- **Optimized imagery and media.** Correct dimensions, useful alt text, lazy loading below the fold, modern formats when practical, responsive `srcset`/`picture` for raster, no project-referenced asset left outside the workspace. +- **Premium motion.** Use atmospheric blur, filter, mask, shadow, reveal when they improve the experience. Avoid casual layout-property animation, bound expensive effects, verify smoothness in-browser, respect reduced motion, and avoid choreography that blocks task completion. +- **Maintainable.** Reusable local patterns, clear component boundaries, project conventions. No rasterized UI text or one-off hacks when a local pattern exists. +- **Technically clean.** Production build passes, no console errors, no avoidable layout shift, no needless dependencies, no broken asset paths. +- **Ask when uncertain.** If a discovery materially changes the brief or approved direction, stop and ask. Don't guess. -## Step 6: Browser-Based Iteration +## Step 6: Iterate Visually -**This step is critical.** Do not stop after the first implementation pass. +Look at what you built like a designer would. Your eyes are whatever the harness gives you: a connected browser, a screenshotting tool, Playwright, or asking the user. Use them for responsive testing (mobile, tablet, desktop minimum) and general visual validation. -Open the result in a browser. In Codex, use browser-use or equivalent browser automation when available; otherwise use Playwright or ask the user for screenshots. Inspect screenshots, not just DOM or terminal output. +If your tool returns a file path, read the PNG back into the conversation. A screenshot you didn't read doesn't count. -### Required viewport pass +For long-form brand surfaces, inspect major sections individually. Thumbnails hide spacing, clipping, and cascade defects. -Check the experience at the viewports that matter for the brief. Default minimum: +After the first pass, write an honest critique against the brief, the approved mock's major ingredients (hero silhouette, motifs, imagery, nav/CTA, density), and impeccable's DON'Ts. Patch material defects and re-inspect. **Don't invent defects to demonstrate iteration.** A confident "first pass clean, shipping" beats a fake fix. -- Mobile narrow -- Tablet or small laptop -- Desktop wide +Actively check: responsive behavior (composes, not shrinks), every state (empty / error / loading / edge), craft details (spacing, alignment, hierarchy, contrast, motion timing, focus), performance basics. The exit bar: defensible in a high-end studio review. -For each viewport, capture or inspect the rendered state and look for visual defects: overlap, clipping, weak hierarchy, off-grid alignment, awkward whitespace, cramped controls, unreadable type, broken imagery, hover-only functionality, layout shift, and text overflow. - -### Critique and fix loop - -After the first browser pass, write a short critique for yourself and patch the implementation. Repeat browser inspection after fixes. Continue until no material issues remain against this checklist: - -1. **Does it match the brief?** Compare the live result against every section of the design brief. Fix discrepancies. -2. **Does it match the approved mock?** Compare screenshots against the mock fidelity inventory: hero silhouette, major motifs, imagery, nav/CTA, section sequence, density, color/materials, and second-fold substance. Missing major ingredients are P0 defects. -3. **Does it pass the AI slop test?** If someone saw this and said "AI made this," would they believe it immediately? If yes, it needs more design intention. -4. **Check against impeccable's DON'T guidelines.** Fix any anti-pattern violations. -5. **Check every state.** Navigate through empty, error, loading, and edge case states. Each one should feel intentional, not like an afterthought. -6. **Check responsive behavior.** The design should adapt compositionally, not merely shrink. -7. **Check craft details.** Spacing consistency, optical alignment, type hierarchy, color contrast, image quality, icon coherence, interactive feedback, motion timing, and focus treatment. -8. **Check performance basics.** No obviously oversized images, avoidable layout thrash, blocking animations, or heavy assets without a reason. - -The exit bar is not "it works." It is: the rendered result looks intentional at all checked viewports, all expected states are handled, no placeholders remain unless explicitly accepted, and the implementation quality would be defensible in a high-end studio review. +Detector or QA output is defect evidence only; never proof the work is finished. ## Step 7: Present @@ -189,5 +153,3 @@ Present the result to the user: - Explain design decisions that connect back to the design brief and, when used, the chosen north-star mock. Include any accepted deviations from the mock; do not hide unimplemented mock ingredients. - Note any remaining limitations or follow-up risks honestly - Ask: "What's working? What isn't?" - -Iterate based on feedback. Good design is rarely right on the first pass. diff --git a/.rovodev/skills/impeccable/reference/critique.md b/.rovodev/skills/impeccable/reference/critique.md index 1c8485b81..d5563b0d3 100644 --- a/.rovodev/skills/impeccable/reference/critique.md +++ b/.rovodev/skills/impeccable/reference/critique.md @@ -43,7 +43,7 @@ Run the bundled deterministic detector, which flags 27 specific patterns (AI slo **CLI scan**: ```bash -npx impeccable --json [--fast] [target] +npx impeccable detect --json [--fast] [target] ``` - Pass HTML/JSX/TSX/Vue/Svelte files or directories as `[target]` (anything with markup). Do not pass CSS-only files. diff --git a/.rovodev/skills/impeccable/reference/polish.md b/.rovodev/skills/impeccable/reference/polish.md index a2a409e48..eed3dbd27 100644 --- a/.rovodev/skills/impeccable/reference/polish.md +++ b/.rovodev/skills/impeccable/reference/polish.md @@ -2,6 +2,8 @@ Perform a meticulous final pass to catch all the small details that separate good work from great work. The difference between shipped and polished. +Detector and automated QA output are defect evidence only. A clean script result is never proof that the design is strong; gather browser evidence and inspect the real interaction path. + ## Design System Discovery Aligning the feature to the design system is **not optional**. Polish without alignment is decoration on top of drift, and it makes the next person's job harder. Discovery comes before any other polish work. @@ -216,11 +218,12 @@ Sweat the details. Zoom in until the alignment is right and the spacing reads as Before marking as done: -- **Use it yourself**: Actually interact with the feature -- **Test on real devices**: Not just browser DevTools -- **Ask someone else to review**: Fresh eyes catch things -- **Compare to design**: Match intended design -- **Check all states**: Don't just test happy path +- **Use it yourself**: Actually interact with the feature. +- **Test on real devices**: Not just browser DevTools. +- **Ask someone else to review**: Fresh eyes catch things. +- **Compare to design**: Match intended design. +- **Check all states**: Don't just test happy path. +- **Treat automation carefully**: Run detector or QA commands when they are available and relevant, fix their defects, but never cite a clean result as proof that the work is polished. ## Clean Up @@ -230,4 +233,3 @@ After polishing, ensure code quality: - **Remove orphaned code**: Delete unused styles, components, or files made obsolete by polish. - **Consolidate tokens**: If you introduced new values, check whether they should be tokens. - **Verify DRYness**: Look for duplication introduced during polishing and consolidate. - diff --git a/.rovodev/skills/impeccable/reference/shape.md b/.rovodev/skills/impeccable/reference/shape.md index 0785187ef..d1c983ff4 100644 --- a/.rovodev/skills/impeccable/reference/shape.md +++ b/.rovodev/skills/impeccable/reference/shape.md @@ -16,14 +16,16 @@ This is a required interaction, not optional guidance. Ask these questions in co ### Interview cadence -Discovery must include at least one user-answer round unless PRODUCT.md, DESIGN.md, or an already-confirmed brief directly answers the needed design inputs. With a sparse prompt, do **not** synthesize a complete brief for confirmation on the first response. +Discovery includes at least one user-answer round unless PRODUCT.md, DESIGN.md, or an already-confirmed brief directly answers the needed inputs. With a sparse prompt, do **not** synthesize a complete brief for confirmation on the first response. - Use the harness's structured question tool when one exists. Otherwise, ask directly in chat and stop. - Ask **2-3 questions per round**, then wait for answers. - Treat PRODUCT.md and DESIGN.md as anchors; they reduce repeated questions but do **not** replace shape for craft. Shape is task-specific. -- Round 1 should clarify purpose, audience/context, and success or emotional outcome. -- Round 2 should clarify content/data/states and scope/fidelity. -- Round 3 should clarify visual direction, constraints, and anti-goals when still unresolved. +- One round is the default. Add a second only if the first answers leave material gaps. Don't run a second round just to feel thorough. +- Round 1 should clarify purpose, audience/context, content/scope, and (for brand) visual direction. +- Round 2, when needed, fills in whatever's still genuinely missing. + +**Assert-then-confirm, not menu-with-escape.** When PRODUCT.md and the user's prompt make one option obvious, name it and ask the user to confirm or override. Don't enumerate "Restrained / Committed / Or something else?" as a real choice; "This reads as Restrained, confirm?" beats a four-option menu when the answer is already clear. ### Purpose & Context - What is this feature for? What problem does it solve? @@ -36,6 +38,7 @@ Discovery must include at least one user-answer round unless PRODUCT.md, DESIGN. - What are the realistic ranges? (Minimum, typical, maximum, e.g., 0 items, 5 items, 500 items) - What are the edge cases? (Empty state, error state, first-time use, power user) - Is any content dynamic? What changes and how often? +- What visual assets are real content here? Note required images, product shots, illustrations, maps, textures, diagrams, generated objects, or existing project assets. ### Design Direction @@ -72,9 +75,9 @@ After the discovery interview, generate a small set of visual direction probes * - The work is **net-new** or directionally ambiguous enough that visual exploration will clarify the brief. - The requested fidelity is **mid-fi, high-fi, or production-ready**. Skip for sketch-only planning. -- The current harness has **built-in image generation capability** (for example, Codex with a native image tool). Do **not** ask the user to set up external APIs, shell scripts, or one-off tooling just to do this. +- The current harness gives you native image generation (Codex's `image_gen`, an equivalent MCP tool, or similar). Don't ask the user to install APIs or tooling. -When those conditions are met, this step is mandatory for Codex and any harness with built-in image generation. Use native image generation; in Codex, use the built-in `image_gen` tool via the imagegen skill. If image generation is unavailable, do not ask the user to install APIs or tooling. State in one line that the image step is skipped because the harness lacks native image generation, then proceed. +When those conditions are met, this step is mandatory. If image generation isn't natively available, skip silently and proceed; don't announce the skip. Use probes to explore visual lanes, not to replace the brief. @@ -104,11 +107,20 @@ The probes should differ in primary visual direction (hierarchy, topology, densi - Do **not** treat generated imagery as final UX specification, final copy, or final accessibility behavior. - Do **not** use this step for minor refinements of existing work. It's for shaping a new surface or clarifying a big directional choice. -If image generation is unavailable, or the task doesn't benefit from it, skip this phase only with a one-line reason and proceed directly to the design brief. +If image generation isn't natively available, skip this phase silently and proceed. ## Phase 2: Design Brief -After the interview and any required probes, synthesize everything into a structured design brief. Present it to the user for explicit confirmation before considering this command complete. Stop after asking for confirmation; do not proceed to craft or implementation in the same response unless the user has already approved the brief. +After the interview and any required probes, present a brief and **end your response**. The user must confirm before any implementation runs. Do not present a brief and then continue to code in the same response, even if the brief feels obvious to you. The user's confirmation is the gate. + +**Choose the brief shape based on how clear the answers are:** + +- **Compact form (3-5 bullets)** when discovery was crisp and the original prompt + PRODUCT.md already pinned scope, content, and direction. State what you're building, the visual lane, and end with one or two specific questions or a clear "confirm or override?" prompt. This is the default for typical craft requests with a clear prompt. +- **Full structured form (sections below)** when the task is genuinely ambiguous, multi-screen, or when the user asked for shape as a standalone step. Use this when the discipline of structure earns its weight. + +Don't pad a clear brief into a long one to look thorough. A 70-line brief restating answers the user just gave is noise, not rigor. Equally, don't skip the confirmation pause to look efficient: the pause is the point. + +If the user already said "approved" or "go" during discovery for the *exact direction you'd present*, that counts as confirmation; you may proceed without asking again. But if your brief adds anything the user hasn't seen and approved, you must stop and confirm. ### Brief Structure @@ -136,16 +148,18 @@ List every state the feature needs: default, empty, loading, error, success, edg How users interact with this feature. What happens on click, hover, scroll? What feedback do they get? What's the flow from entry to completion? **8. Content Requirements** -What copy, labels, empty state messages, error messages, and microcopy are needed. Note any dynamic content and its realistic ranges. +What copy, labels, empty state messages, error messages, and microcopy are needed. Note any dynamic content and its realistic ranges. For image-led surfaces, also list the required image/media roles and their likely source (project asset, generated raster, semantic SVG/CSS, canvas/WebGL, icon library, or accepted omission). **9. Recommended References** Based on the brief, list which impeccable reference files would be most valuable during implementation (e.g., spatial-design.md for complex layouts, motion-design.md for animated features, interaction-design.md for form-heavy features). **10. Open Questions** -Anything unresolved that the implementer should resolve during build. +Anything genuinely unresolved. Don't list "open questions" you've already recommended a default for; assert the default and move on. If you'd write `Recommend: X` next to a question, just decide X. --- -ask the user directly to clarify what you cannot infer. Ask for explicit confirmation of the brief before finishing. If the user disagrees with any part, revisit the relevant discovery questions. A shape run is incomplete until the brief is confirmed. +ask the user directly to clarify what you cannot infer. + +If the user disagrees with any part, revisit the relevant discovery questions. A shape run is incomplete until the user confirms direction (or the user already gave a clear go during discovery, which counts). Once confirmed, the brief is complete. The user can now hand it to /impeccable, or use it to guide any other implementation approach. (If the user wants the full discovery-then-build flow in one step, they should use /impeccable craft instead, which runs this command internally.) diff --git a/.trae-cn/skills/impeccable/SKILL.md b/.trae-cn/skills/impeccable/SKILL.md index 5ae9750d6..7f906895e 100644 --- a/.trae-cn/skills/impeccable/SKILL.md +++ b/.trae-cn/skills/impeccable/SKILL.md @@ -9,28 +9,15 @@ license: Apache 2.0. Based on Anthropic's frontend-design skill. See NOTICE.md f Designs and iterates production-grade frontend interfaces. Real working code, committed design choices, exceptional craft. -## Setup (non-optional) +## Setup -Before any design work or file edits, pass these gates. Skipping them produces generic output that ignores the project. +Before any design work or file edits: -| Gate | Required check | If fail | -|---|---|---| -| Context | The PRODUCT.md / DESIGN.md loader result is known from `node .trae-cn/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. | +1. Load context (PRODUCT.md / DESIGN.md) via the loader script. +2. Identify the register and load the matching register reference (brand.md or product.md). +3. **If the user invoked a sub-command (e.g. `craft`, `shape`, `audit`), load its reference file too.** This is non-negotiable: `craft` without `craft.md` loaded means you'll skip the shape-and-confirm step the user expects. -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: 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. +Skipping these produces generic output that ignores the project. ### 1. Context gathering diff --git a/.trae-cn/skills/impeccable/reference/brand.md b/.trae-cn/skills/impeccable/reference/brand.md index b069f2553..3d83a1cdc 100644 --- a/.trae-cn/skills/impeccable/reference/brand.md +++ b/.trae-cn/skills/impeccable/reference/brand.md @@ -12,6 +12,8 @@ Brand isn't a neutral register. AI-generated landing pages have flooded the inte **The second slop test: aesthetic lane.** Before committing to moves, name the reference. A Klim-style specimen page is one lane; Stripe-minimal is another; Liquid-Death-acid-maximalism is another. Don't drift into editorial-magazine aesthetics on a brief that isn't editorial. A hiking brand with Cormorant italic drop caps has the wrong register within the register. +Then the inverse test: in one sentence, describe what you're about to build the way a competitor would describe theirs. If that sentence fits the modal landing page in the category, restart. + ## Typography ### Font selection procedure @@ -66,6 +68,7 @@ Brand surfaces have permission for Committed, Full palette, and Drenched strateg - Palette IS voice. A calm brand and a restless brand should not share palette mechanics. - When the strategy is Committed or Drenched, color carries the brand. Don't hedge with neutrals around the edges. Commit. - Don't converge across projects. If the last brand surface was restrained-on-cream, this one is not. +- When a cultural-symbol palette is the obvious pull, reach past it. Let the cultural reading come from typography, imagery, and copy, not the palette. ## Layout @@ -79,14 +82,14 @@ Brand surfaces have permission for Committed, Full palette, and Drenched strateg Brand surfaces lean on imagery. A restaurant, hotel, magazine, or product landing page without any imagery reads as incomplete, not as restrained. A solid-color rectangle where a hero image should go is worse than a representative stock photo. -**When the brief implies imagery (restaurants, hotels, magazines, photography, hobbyist communities, food, travel, fashion, product), you must ship imagery.** Zero images is a bug, not a design choice. "Restraint" is not an excuse. +**When the brief implies imagery (restaurants, hotels, magazines, photography, hobbyist communities, food, travel, fashion, product), you must ship imagery.** Zero images is a bug, not a design choice. "Restraint" is not an excuse. If the approved comp or brief is image-led, ship real project assets, generated raster assets, or a credible canvas/SVG/WebGL scene. Do not replace photographic, architectural, product, or place imagery with generic CSS panels, decorative diagrams, cards, bullets, or copy. -- **For greenfield work without local assets, use stock imagery.** Unsplash is the default. The URL shape is `https://images.unsplash.com/photo-{id}?auto=format&fit=crop&w=1600&q=80`. Pick real Unsplash photo IDs you're confident exist (`photo-1559339352-11d035aa65de`, `photo-1590490360182-c33d57733427`, etc.); if unsure, pick fewer photos but don't substitute colored `
` placeholders. +- **For greenfield work without local assets, use stock imagery.** Unsplash is the default. The URL shape is `https://images.unsplash.com/photo-{id}?auto=format&fit=crop&w=1600&q=80`. **Verify the URLs before referencing them.** If you have an image-search MCP, web-fetch tool, or browser access, use it to find real photo IDs and confirm they resolve. Guessed IDs (even ones that look real) often 404 and ship as broken-image placeholders. Without a verification path, pick fewer photos you're confident exist over more that you guessed; never substitute colored `
` placeholders. - **Search for the brand's physical object**, not the generic category: "handmade pasta on a scratched wooden table" beats "Italian food"; "cypress trees above a limestone hotel facade at dusk" beats "luxury hotel". - **One decisive photo beats five mediocre ones.** Hero imagery should commit to a mood; padding with more stock doesn't rescue an indecisive one. - **Alt text is part of the voice.** "Coastal fettuccine, hand-cut, served on the terrace" beats "pasta dish". -Tech / dev-tool brands are the exception where zero imagery can be correct; a developer landing page often carries its voice through typography, code samples, diagrams. Know which kind of brand you're working on. +"Imagery" here is broader than stock photography: product screenshots, custom data visualizations, generated SVG, and canvas/WebGL scenes are all imagery. Text-only pages where typography alone carries the entire visual weight are the failure mode. ## Motion @@ -102,6 +105,7 @@ Tech / dev-tool brands are the exception where zero imagery can be correct; a de - Timid palettes and average layouts. Safe = invisible. - Zero imagery on a brief that implies imagery (restaurant, hotel, food, travel, fashion, photography, hobbyist). Colored blocks where a hero photo belongs. - Defaulting to editorial-magazine aesthetics (display serif + italic + drop caps + broadsheet grid) on briefs that aren't magazine-shaped. Editorial is ONE aesthetic lane, not the default brand aesthetic. +- Repeated tiny uppercase tracked labels above every section heading. A single strong kicker can be voice; repeating it as section grammar is AI scaffolding unless it's a deliberate, named brand system. ## Brand permissions diff --git a/.trae-cn/skills/impeccable/reference/craft.md b/.trae-cn/skills/impeccable/reference/craft.md index bdeee0294..c0cfa7460 100644 --- a/.trae-cn/skills/impeccable/reference/craft.md +++ b/.trae-cn/skills/impeccable/reference/craft.md @@ -1,43 +1,41 @@ # Craft Flow -Build a feature with impeccable UX and UI quality through a structured process: shape the design, land the visual direction, build real production code, then inspect and improve in-browser until the result meets a high-end studio bar. +Build a feature with impeccable UX and UI quality: shape the design, land the visual direction, build real production code, inspect and improve in-browser until it meets a high-end studio bar. -## Build Gate +Before writing code, you need: PRODUCT.md loaded, register identified and the matching reference loaded, and a confirmed design direction for this task (either from `shape` or supplied by the user). PRODUCT.md is project context, not a task-specific brief. -Craft cannot build until all of these are true: +Treat any approved visual direction (generated mock or stated reference) as a concrete contract for composition, hierarchy, density, atmosphere, signature motifs, and distinctive visual moves. Don't let mocks replace structure, copy, accessibility, or state design. But if the live result lacks the approved direction's major ingredients, the implementation is wrong. -1. PRODUCT context is valid and current. -2. The shape design brief is explicitly confirmed by the user for this task, unless the user already provided a confirmed brief. -3. Implementation references from the brief are loaded. -4. The shape visual probe decision is recorded: generated, skipped with reason, or already resolved. -5. The north-star mock decision is recorded: generated, skipped with reason, or not applicable. +## Step 0: Project Foundation -PRODUCT.md and `teach` answers do **not** satisfy the shape gate. They are project context only. A compact self-authored brief does not satisfy the shape gate either. `shape=pass` requires a separate user response approving the shape brief or an already-confirmed brief supplied by the user. +Before shape, before code: figure out what kind of project you're working in. -Invalid image-skip reasons include: "the final implementation will be semantic HTML/CSS/SVG", "the diagram should stay editable", "a raster mock would not be used directly", or "the product is fictional." Generated probes and mocks are direction artifacts; they are not implementation assets. +Look at the working directory. Run `ls`. Check for: -## Craft Contract +- An existing framework: `astro.config.mjs/ts`, `next.config.js/ts`, `nuxt.config.ts`, `svelte.config.js`, `vite.config.js/ts`, `package.json` with framework deps, `Cargo.toml` + Leptos/Yew, `Gemfile` + Rails. **If found, use it.** Do not start a parallel build, do not introduce a second framework, do not write to `dist/` or `build/` directly. Whatever pipeline the project has, respect it. +- An existing component library or design system: `src/components/`, `app/components/`, a `tokens.css` / `theme.ts`, an `astro.config` `integrations`. Read what's there before adding to it. +- An existing icon set: `lucide-react`, `@phosphor-icons/react`, `@iconify/*`, hand-rolled SVG sprites in `assets/icons/`. **Use what's already in the project**; don't introduce a second set. -Craft is not a first pass. It is a loop with these required artifacts: +If the directory is empty (greenfield), don't pick a framework silently. Ask the user via the AskUserQuestion tool, with sensible defaults framed by the brief: -1. Confirmed design brief from `shape`. -2. Approved visual direction, from generated probes / mocks when image generation is available. -3. Mock fidelity inventory: the visible ingredients from the approved direction that must survive into code. -4. Semantic, functional implementation using the project's real stack and conventions. -5. Browser evidence across relevant viewports. -6. At least one critique-and-fix pass after the first browser inspection, unless the first pass has no material defects. +```text +What should this be built on? + - Astro (default for content-led brand sites, landing pages, marketing surfaces) + - SvelteKit / Next.js / Nuxt (when the brief implies an app surface or significant interactivity) + - Single index.html (one-shot demo, prototype, or a deliberately framework-free experiment) +``` -Do not let generated mockups replace interface structure, copy, accessibility, responsive behavior, or state design. But do treat the approved mock as a concrete visual contract for composition, hierarchy, density, atmosphere, signature motifs, image needs, and distinctive visual moves. "North star" means "preserve the important visible ingredients in semantic code," not "use it as loose mood." +Default: Astro for brand briefs, the project's existing framework for product briefs. Ask once; don't re-ask mid-task. ## Step 1: Shape the Design -Run /impeccable shape, passing along whatever feature description the user provided. +Run /impeccable shape, passing along whatever feature description the user provided. Shape is **required** for craft; it is what produces a confirmed direction. -Wait for the design brief to be fully confirmed by the user before proceeding. The brief is your blueprint, and every implementation decision should trace back to it. +Present the shape output and stop. Wait for the user to confirm, override, or course-correct before writing code. -If this craft run resumed after `teach` created PRODUCT.md, run shape now. Do not treat the teach interview, PRODUCT.md, or a summary of project context as a substitute for shape. Shape is task-specific and must cover scope, content/states, visual direction, constraints, anti-goals, probes when applicable, and explicit brief confirmation. +If the user already supplied a confirmed brief or ran shape separately, use it and skip this step. -If the user has already run /impeccable shape and has a confirmed design brief, skip this step and use the existing brief. +When the original prompt + PRODUCT.md already answer scope, content, and visual direction with no real ambiguity, the shape output can be **compact** (3-5 bullets stating what you're building and the visual lane, ending with one or two specific questions or "confirm or override"). The full 10-section structured brief is reserved for genuinely ambiguous, multi-screen, or stakeholder-heavy tasks. Don't pad a clear brief into a long one to look thorough; equally, don't skip the pause to look efficient. ## Step 2: Load References @@ -55,79 +53,60 @@ Then add references based on the brief's needs: ## Step 3: Land the Visual Direction (Capability-Gated) -Before implementation, generate high-fidelity visual comps when all of these are true: +Generate high-fidelity visual comps before implementation when all three are true: -- The work is **net-new** or visually open-ended enough that composition exploration will improve the build. -- The brief's scope is **mid-fi, high-fi, or production-ready**. -- The current harness has **built-in image generation capability** (for example, Codex with a native image tool). Do **not** ask the user to set up external APIs, shell scripts, or one-off tooling just to do this. +- The work is net-new or visually open-ended enough that composition exploration will improve the build. +- The brief's scope is mid-fi, high-fi, or production-ready. +- The harness gives you native image generation (Codex's `image_gen`, an equivalent MCP tool). Don't ask the user to set up external APIs. -When those conditions are met, this step is mandatory for **both brand and product work** in Codex and any harness with built-in image generation. Use native image generation; in Codex, use the built-in `image_gen` tool via the imagegen skill. If image generation is unavailable, do not ask the user to install APIs or tooling. State in one line that the image step is skipped because the harness lacks native image generation, then proceed. - -Do not skip this step because the eventual UI should be semantic, editable, code-native, responsive, or accessible. Those are implementation requirements, not reasons to avoid visual exploration. - -### Purpose - -Use the mock step to find a stronger visual lane than code-first generation would reliably discover on its own. The brief remains authoritative on user, purpose, content, constraints, states, and anti-goals. The mock clarifies composition, hierarchy, density, typography, and visual tone. +When met, this step is mandatory for both brand and product work. If image generation isn't available, skip silently. "The eventual UI is semantic/code-native/accessible" is not a reason to skip; those are implementation requirements, not exploration ones. ### What to generate -Generate **1 to 3** high-fidelity north-star comps based on the confirmed brief. If shape already produced direction probes, use those results as input and generate a more resolved mock from the winning lane, not another unrelated exploration. +Generate **1 to 3** high-fidelity north-star comps from the confirmed brief. If shape already produced direction probes, resolve the winning lane further, not an unrelated exploration. Comps must differ in primary visual direction, not just color. -- For brand work, push visual identity, composition, and mood aggressively. -- For product work, still push hierarchy, topology, density, and tone, but keep the comps grounded in realistic product structure and states. -- For landing pages and long-form brand surfaces, show enough of the next section or second fold to establish the system beyond the hero. - -The comps must be genuinely different in primary visual direction, not just color variants. +- Brand work: push visual identity, composition, and mood aggressively. +- Product work: push hierarchy, topology, density, tone, grounded in realistic product structure. +- Landing pages and long-form brand surfaces: show enough of the second fold to establish the system beyond the hero. ### Approval loop -Show the comps and ask what should carry forward. If the user asks for changes or the best direction is still weak, generate a focused revision before implementation. Continue until one direction is approved, or until the user explicitly delegates the choice. +Show the comps and ask what carries forward. Iterate until one direction is approved or the user delegates. If the user delegates, pick the strongest direction and explain it from the brief, not personal taste. -If the user delegates, pick the strongest direction and explain the decision using the brief, not personal taste. - -Before moving to implementation, summarize: - -- What to carry into code -- What **not** to literalize from the mock - -This summary is required before Step 4. It is the handoff between visual exploration and semantic implementation. +Before Step 4, summarize what to carry into code and what **not** to literalize from the mock. This is the handoff between visual exploration and semantic implementation. ### Mock fidelity inventory -Before building, inventory the approved mock's major visible ingredients: +Inventory the approved mock's major visible ingredients: -- Hero silhouette and dominant composition. -- Signature motifs: planets, devices, portraits, charts, route lines, insets, badges, or other memorable objects. -- Nav and primary CTA treatment. -- Section sequence visible in the mock, especially the second fold. -- Image-native content the concept depends on. -- Typography, density, color/material treatment, and motion cues. +- Hero silhouette and dominant composition +- Signature motifs (planets, devices, portraits, charts, route lines, insets, badges, etc.) +- Nav and primary CTA treatment +- Section sequence, especially the second fold +- Image-native content the concept depends on +- Typography, density, color/material treatment, motion cues -For each ingredient, decide how it will be implemented: semantic HTML/CSS/SVG, generated asset, sourced project asset, icon library, canvas/WebGL, or an explicitly accepted omission. Do not substitute a different hero composition or new visual driver after approval unless the user approves the change. +For each, decide implementation: semantic HTML/CSS/SVG, generated asset, sourced asset, icon library, canvas/WebGL, or accepted omission. Don't substitute a different hero composition or visual driver post-approval without user sign-off. -Treat the mock as a **north star**, not a screenshot to trace. Do **not** rasterize core UI text or let the mock override the confirmed brief. But if the live result lacks the mock's major visible ingredients, the implementation is wrong. +If a photographic, architectural, product, or place-led mock becomes generic CSS scenery / decorative diagrams / bullets / copy, stop and fix it. That's a broken implementation, not a harmless interpretation. + +Treat the mock as a north star, not a screenshot to trace. Don't rasterize core UI text. But if the live result lacks the mock's major ingredients, the implementation is wrong. ## Step 4: Asset Extraction (Need-Gated) -If the chosen direction includes image-native visual ingredients that would materially improve the implementation, generate them as separate assets before building. +If the approved direction needs raster assets, create them before building. Do not replace required imagery with generic cards, bullets, emoji, fake metrics, decorative CSS panels, or filler copy. -Good candidates: +Use the native asset producer (`impeccable_asset_producer` in Codex, `impeccable-asset-producer` in Claude Code) to create clean assets from the hi-fi mock and crops. If you do not have explicit permission to use agents, stop and ask: -- stickers -- badges -- seals -- tickets -- graphic labels -- textures -- abstract objects -- decorative marks -- non-semantic scene elements +```text +Asset production will work better as a scoped subagent job. Should I spawn the Impeccable asset producer subagent for this step? +``` -For travel, editorial, portfolio, venue, product showcase, entertainment, education, or any other image-led brand surface, visual assets are usually core content, not decoration. Do not ship abstract CSS panels where the approved mock or subject matter calls for real imagery, generated plates, illustrations, maps, product/object renders, or destination scenes. +Do not skip asset production or silently do it inline. Inline asset production is allowed only if the user declines subagents, the harness cannot spawn the authorized agent, or the user explicitly asks for single-thread mode. -Do **not** export assets for core UI text, navigation, body copy, or any structure that should stay semantic and editable in code. +Pass the approved mock, crop/contact-sheet paths, output directory, dimensions/formats, transparency needs, constraints, and avoid list to the asset producer. Attach image generation capability to the spawned agent when the harness supports it; do not load image-generation reference material into the parent thread first. -Usually **1 to 5** extracted assets is enough. If the design can be built cleanly in HTML/CSS/SVG, prefer that over raster assets. If the mock contains major visual content that cannot be built credibly in code, asset extraction is not optional. +Prefer HTML/CSS/SVG/canvas when they can credibly reproduce an ingredient; use real/generated/stock imagery when the mock or subject matter calls for actual visual content. ## Step 5: Build to Production Quality @@ -135,50 +114,35 @@ Implement the feature following the design brief. Build in passes so structure, ### Production bar -- Use real or realistic content. Remove placeholder copy, placeholder images, dead links, fake controls, and unused scaffold before presenting. -- Preserve the approved mock's major ingredients. Missing hero objects, missing world/product imagery, different section structure, downgraded CTA/nav treatment, or generic replacements for distinctive motifs are blocking defects unless the user accepted the change. -- Build semantically first: real headings, landmarks, labels, form associations, button/link semantics, accessible names, and state announcements where needed. -- Calibrate spacing, alignment, grid placement, and vertical rhythm deliberately. Do not accept default gaps, arbitrary margins, unbalanced whitespace, or accidental optical misalignment. -- Make typography intentional: chosen font loading strategy, clear hierarchy, readable measure, stable line breaks, tuned wrapping, and no overflow at mobile or large desktop sizes. -- Design realistic state coverage: default, hover where supported, focus-visible, active, disabled, loading, error, success, empty, overflow, long text, short text, and first-run states where relevant. -- Make interaction quality feel finished: keyboard paths, touch targets, feedback timing, scroll behavior, transitions between states, and no hover-only functionality. -- Use icons from the project's established icon set when available. If no set exists, choose a coherent library or use accessible text controls; do not mix unrelated icon styles. -- Optimize imagery and media: correct dimensions, useful alt text, lazy loading below the fold, modern formats when practical, responsive `srcset` / `picture` for raster assets, and no project-referenced asset left outside the workspace. -- Make motion feel premium: use atmospheric blur, filter, mask, shadow, or reveal effects when they improve the experience; avoid casual layout-property animation, bound expensive effects, verify smoothness in-browser, respect reduced motion, and avoid choreography that blocks task completion. -- Preserve maintainability: reusable local patterns, clear component boundaries, project conventions, no rasterized UI text, and no hard-coded one-off hacks when a better local pattern exists. -- Fit the technical context: production build passes, no obvious console errors, no avoidable layout shift, no needless dependency, and no broken asset path. -- If you discover a design question that materially changes the brief or approved direction, stop and ask rather than guessing. +- **Real content.** No placeholder copy, placeholder images, dead links, fake controls, or unused scaffold at presentation time. +- **Preserve the approved mock's major ingredients.** Missing hero objects, world/product imagery, section structure, CTA/nav treatment, or distinctive motifs are blocking defects unless the user accepted the change. +- **Semantic first.** Real headings, landmarks, labels, form associations, button/link semantics, accessible names, state announcements where needed. +- **Deliberate spacing and alignment.** No default gaps, arbitrary margins, unbalanced whitespace, or accidental optical misalignment. +- **Intentional typography.** Chosen loading strategy, clear hierarchy, readable measure, stable line breaks, no overflow at any width. +- **Realistic state coverage.** Default, hover, focus-visible, active, disabled, loading, error, success, empty, overflow, long/short text, first-run. +- **Finished interaction quality.** Keyboard paths, touch targets, feedback timing, scroll behavior, state transitions, no hover-only functionality. +- **Coherent icon set.** Use the project's established set; otherwise pick one library or use accessible text. Don't mix. +- **Respect the build pipeline.** Edit source files and run the project's build (`npm run build` or equivalent). Don't write to `build/` / `dist/` / `.next/` with `cat`, heredoc, or Bash redirects; that skips asset hashing, image optimization, code splitting, and CSS extraction, and produces output the dev server won't serve. +- **Verify image URLs before referencing them.** Use image-search MCP or web-fetch when available; guessed photo IDs ship as broken-image placeholders. Without verification, prefer fewer images you're confident about. +- **Optimized imagery and media.** Correct dimensions, useful alt text, lazy loading below the fold, modern formats when practical, responsive `srcset`/`picture` for raster, no project-referenced asset left outside the workspace. +- **Premium motion.** Use atmospheric blur, filter, mask, shadow, reveal when they improve the experience. Avoid casual layout-property animation, bound expensive effects, verify smoothness in-browser, respect reduced motion, and avoid choreography that blocks task completion. +- **Maintainable.** Reusable local patterns, clear component boundaries, project conventions. No rasterized UI text or one-off hacks when a local pattern exists. +- **Technically clean.** Production build passes, no console errors, no avoidable layout shift, no needless dependencies, no broken asset paths. +- **Ask when uncertain.** If a discovery materially changes the brief or approved direction, stop and ask. Don't guess. -## Step 6: Browser-Based Iteration +## Step 6: Iterate Visually -**This step is critical.** Do not stop after the first implementation pass. +Look at what you built like a designer would. Your eyes are whatever the harness gives you: a connected browser, a screenshotting tool, Playwright, or asking the user. Use them for responsive testing (mobile, tablet, desktop minimum) and general visual validation. -Open the result in a browser. In Codex, use browser-use or equivalent browser automation when available; otherwise use Playwright or ask the user for screenshots. Inspect screenshots, not just DOM or terminal output. +If your tool returns a file path, read the PNG back into the conversation. A screenshot you didn't read doesn't count. -### Required viewport pass +For long-form brand surfaces, inspect major sections individually. Thumbnails hide spacing, clipping, and cascade defects. -Check the experience at the viewports that matter for the brief. Default minimum: +After the first pass, write an honest critique against the brief, the approved mock's major ingredients (hero silhouette, motifs, imagery, nav/CTA, density), and impeccable's DON'Ts. Patch material defects and re-inspect. **Don't invent defects to demonstrate iteration.** A confident "first pass clean, shipping" beats a fake fix. -- Mobile narrow -- Tablet or small laptop -- Desktop wide +Actively check: responsive behavior (composes, not shrinks), every state (empty / error / loading / edge), craft details (spacing, alignment, hierarchy, contrast, motion timing, focus), performance basics. The exit bar: defensible in a high-end studio review. -For each viewport, capture or inspect the rendered state and look for visual defects: overlap, clipping, weak hierarchy, off-grid alignment, awkward whitespace, cramped controls, unreadable type, broken imagery, hover-only functionality, layout shift, and text overflow. - -### Critique and fix loop - -After the first browser pass, write a short critique for yourself and patch the implementation. Repeat browser inspection after fixes. Continue until no material issues remain against this checklist: - -1. **Does it match the brief?** Compare the live result against every section of the design brief. Fix discrepancies. -2. **Does it match the approved mock?** Compare screenshots against the mock fidelity inventory: hero silhouette, major motifs, imagery, nav/CTA, section sequence, density, color/materials, and second-fold substance. Missing major ingredients are P0 defects. -3. **Does it pass the AI slop test?** If someone saw this and said "AI made this," would they believe it immediately? If yes, it needs more design intention. -4. **Check against impeccable's DON'T guidelines.** Fix any anti-pattern violations. -5. **Check every state.** Navigate through empty, error, loading, and edge case states. Each one should feel intentional, not like an afterthought. -6. **Check responsive behavior.** The design should adapt compositionally, not merely shrink. -7. **Check craft details.** Spacing consistency, optical alignment, type hierarchy, color contrast, image quality, icon coherence, interactive feedback, motion timing, and focus treatment. -8. **Check performance basics.** No obviously oversized images, avoidable layout thrash, blocking animations, or heavy assets without a reason. - -The exit bar is not "it works." It is: the rendered result looks intentional at all checked viewports, all expected states are handled, no placeholders remain unless explicitly accepted, and the implementation quality would be defensible in a high-end studio review. +Detector or QA output is defect evidence only; never proof the work is finished. ## Step 7: Present @@ -189,5 +153,3 @@ Present the result to the user: - Explain design decisions that connect back to the design brief and, when used, the chosen north-star mock. Include any accepted deviations from the mock; do not hide unimplemented mock ingredients. - Note any remaining limitations or follow-up risks honestly - Ask: "What's working? What isn't?" - -Iterate based on feedback. Good design is rarely right on the first pass. diff --git a/.trae-cn/skills/impeccable/reference/critique.md b/.trae-cn/skills/impeccable/reference/critique.md index 1033d9464..6db43b3ec 100644 --- a/.trae-cn/skills/impeccable/reference/critique.md +++ b/.trae-cn/skills/impeccable/reference/critique.md @@ -43,7 +43,7 @@ Run the bundled deterministic detector, which flags 27 specific patterns (AI slo **CLI scan**: ```bash -npx impeccable --json [--fast] [target] +npx impeccable detect --json [--fast] [target] ``` - Pass HTML/JSX/TSX/Vue/Svelte files or directories as `[target]` (anything with markup). Do not pass CSS-only files. diff --git a/.trae-cn/skills/impeccable/reference/polish.md b/.trae-cn/skills/impeccable/reference/polish.md index a2a409e48..eed3dbd27 100644 --- a/.trae-cn/skills/impeccable/reference/polish.md +++ b/.trae-cn/skills/impeccable/reference/polish.md @@ -2,6 +2,8 @@ Perform a meticulous final pass to catch all the small details that separate good work from great work. The difference between shipped and polished. +Detector and automated QA output are defect evidence only. A clean script result is never proof that the design is strong; gather browser evidence and inspect the real interaction path. + ## Design System Discovery Aligning the feature to the design system is **not optional**. Polish without alignment is decoration on top of drift, and it makes the next person's job harder. Discovery comes before any other polish work. @@ -216,11 +218,12 @@ Sweat the details. Zoom in until the alignment is right and the spacing reads as Before marking as done: -- **Use it yourself**: Actually interact with the feature -- **Test on real devices**: Not just browser DevTools -- **Ask someone else to review**: Fresh eyes catch things -- **Compare to design**: Match intended design -- **Check all states**: Don't just test happy path +- **Use it yourself**: Actually interact with the feature. +- **Test on real devices**: Not just browser DevTools. +- **Ask someone else to review**: Fresh eyes catch things. +- **Compare to design**: Match intended design. +- **Check all states**: Don't just test happy path. +- **Treat automation carefully**: Run detector or QA commands when they are available and relevant, fix their defects, but never cite a clean result as proof that the work is polished. ## Clean Up @@ -230,4 +233,3 @@ After polishing, ensure code quality: - **Remove orphaned code**: Delete unused styles, components, or files made obsolete by polish. - **Consolidate tokens**: If you introduced new values, check whether they should be tokens. - **Verify DRYness**: Look for duplication introduced during polishing and consolidate. - diff --git a/.trae-cn/skills/impeccable/reference/shape.md b/.trae-cn/skills/impeccable/reference/shape.md index 0785187ef..d1c983ff4 100644 --- a/.trae-cn/skills/impeccable/reference/shape.md +++ b/.trae-cn/skills/impeccable/reference/shape.md @@ -16,14 +16,16 @@ This is a required interaction, not optional guidance. Ask these questions in co ### Interview cadence -Discovery must include at least one user-answer round unless PRODUCT.md, DESIGN.md, or an already-confirmed brief directly answers the needed design inputs. With a sparse prompt, do **not** synthesize a complete brief for confirmation on the first response. +Discovery includes at least one user-answer round unless PRODUCT.md, DESIGN.md, or an already-confirmed brief directly answers the needed inputs. With a sparse prompt, do **not** synthesize a complete brief for confirmation on the first response. - Use the harness's structured question tool when one exists. Otherwise, ask directly in chat and stop. - Ask **2-3 questions per round**, then wait for answers. - Treat PRODUCT.md and DESIGN.md as anchors; they reduce repeated questions but do **not** replace shape for craft. Shape is task-specific. -- Round 1 should clarify purpose, audience/context, and success or emotional outcome. -- Round 2 should clarify content/data/states and scope/fidelity. -- Round 3 should clarify visual direction, constraints, and anti-goals when still unresolved. +- One round is the default. Add a second only if the first answers leave material gaps. Don't run a second round just to feel thorough. +- Round 1 should clarify purpose, audience/context, content/scope, and (for brand) visual direction. +- Round 2, when needed, fills in whatever's still genuinely missing. + +**Assert-then-confirm, not menu-with-escape.** When PRODUCT.md and the user's prompt make one option obvious, name it and ask the user to confirm or override. Don't enumerate "Restrained / Committed / Or something else?" as a real choice; "This reads as Restrained, confirm?" beats a four-option menu when the answer is already clear. ### Purpose & Context - What is this feature for? What problem does it solve? @@ -36,6 +38,7 @@ Discovery must include at least one user-answer round unless PRODUCT.md, DESIGN. - What are the realistic ranges? (Minimum, typical, maximum, e.g., 0 items, 5 items, 500 items) - What are the edge cases? (Empty state, error state, first-time use, power user) - Is any content dynamic? What changes and how often? +- What visual assets are real content here? Note required images, product shots, illustrations, maps, textures, diagrams, generated objects, or existing project assets. ### Design Direction @@ -72,9 +75,9 @@ After the discovery interview, generate a small set of visual direction probes * - The work is **net-new** or directionally ambiguous enough that visual exploration will clarify the brief. - The requested fidelity is **mid-fi, high-fi, or production-ready**. Skip for sketch-only planning. -- The current harness has **built-in image generation capability** (for example, Codex with a native image tool). Do **not** ask the user to set up external APIs, shell scripts, or one-off tooling just to do this. +- The current harness gives you native image generation (Codex's `image_gen`, an equivalent MCP tool, or similar). Don't ask the user to install APIs or tooling. -When those conditions are met, this step is mandatory for Codex and any harness with built-in image generation. Use native image generation; in Codex, use the built-in `image_gen` tool via the imagegen skill. If image generation is unavailable, do not ask the user to install APIs or tooling. State in one line that the image step is skipped because the harness lacks native image generation, then proceed. +When those conditions are met, this step is mandatory. If image generation isn't natively available, skip silently and proceed; don't announce the skip. Use probes to explore visual lanes, not to replace the brief. @@ -104,11 +107,20 @@ The probes should differ in primary visual direction (hierarchy, topology, densi - Do **not** treat generated imagery as final UX specification, final copy, or final accessibility behavior. - Do **not** use this step for minor refinements of existing work. It's for shaping a new surface or clarifying a big directional choice. -If image generation is unavailable, or the task doesn't benefit from it, skip this phase only with a one-line reason and proceed directly to the design brief. +If image generation isn't natively available, skip this phase silently and proceed. ## Phase 2: Design Brief -After the interview and any required probes, synthesize everything into a structured design brief. Present it to the user for explicit confirmation before considering this command complete. Stop after asking for confirmation; do not proceed to craft or implementation in the same response unless the user has already approved the brief. +After the interview and any required probes, present a brief and **end your response**. The user must confirm before any implementation runs. Do not present a brief and then continue to code in the same response, even if the brief feels obvious to you. The user's confirmation is the gate. + +**Choose the brief shape based on how clear the answers are:** + +- **Compact form (3-5 bullets)** when discovery was crisp and the original prompt + PRODUCT.md already pinned scope, content, and direction. State what you're building, the visual lane, and end with one or two specific questions or a clear "confirm or override?" prompt. This is the default for typical craft requests with a clear prompt. +- **Full structured form (sections below)** when the task is genuinely ambiguous, multi-screen, or when the user asked for shape as a standalone step. Use this when the discipline of structure earns its weight. + +Don't pad a clear brief into a long one to look thorough. A 70-line brief restating answers the user just gave is noise, not rigor. Equally, don't skip the confirmation pause to look efficient: the pause is the point. + +If the user already said "approved" or "go" during discovery for the *exact direction you'd present*, that counts as confirmation; you may proceed without asking again. But if your brief adds anything the user hasn't seen and approved, you must stop and confirm. ### Brief Structure @@ -136,16 +148,18 @@ List every state the feature needs: default, empty, loading, error, success, edg How users interact with this feature. What happens on click, hover, scroll? What feedback do they get? What's the flow from entry to completion? **8. Content Requirements** -What copy, labels, empty state messages, error messages, and microcopy are needed. Note any dynamic content and its realistic ranges. +What copy, labels, empty state messages, error messages, and microcopy are needed. Note any dynamic content and its realistic ranges. For image-led surfaces, also list the required image/media roles and their likely source (project asset, generated raster, semantic SVG/CSS, canvas/WebGL, icon library, or accepted omission). **9. Recommended References** Based on the brief, list which impeccable reference files would be most valuable during implementation (e.g., spatial-design.md for complex layouts, motion-design.md for animated features, interaction-design.md for form-heavy features). **10. Open Questions** -Anything unresolved that the implementer should resolve during build. +Anything genuinely unresolved. Don't list "open questions" you've already recommended a default for; assert the default and move on. If you'd write `Recommend: X` next to a question, just decide X. --- -ask the user directly to clarify what you cannot infer. Ask for explicit confirmation of the brief before finishing. If the user disagrees with any part, revisit the relevant discovery questions. A shape run is incomplete until the brief is confirmed. +ask the user directly to clarify what you cannot infer. + +If the user disagrees with any part, revisit the relevant discovery questions. A shape run is incomplete until the user confirms direction (or the user already gave a clear go during discovery, which counts). Once confirmed, the brief is complete. The user can now hand it to /impeccable, or use it to guide any other implementation approach. (If the user wants the full discovery-then-build flow in one step, they should use /impeccable craft instead, which runs this command internally.) diff --git a/.trae/skills/impeccable/SKILL.md b/.trae/skills/impeccable/SKILL.md index a819ddb38..5099ab5d5 100644 --- a/.trae/skills/impeccable/SKILL.md +++ b/.trae/skills/impeccable/SKILL.md @@ -9,28 +9,15 @@ license: Apache 2.0. Based on Anthropic's frontend-design skill. See NOTICE.md f Designs and iterates production-grade frontend interfaces. Real working code, committed design choices, exceptional craft. -## Setup (non-optional) +## Setup -Before any design work or file edits, pass these gates. Skipping them produces generic output that ignores the project. +Before any design work or file edits: -| Gate | Required check | If fail | -|---|---|---| -| Context | The PRODUCT.md / DESIGN.md loader result is known from `node .trae/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. | +1. Load context (PRODUCT.md / DESIGN.md) via the loader script. +2. Identify the register and load the matching register reference (brand.md or product.md). +3. **If the user invoked a sub-command (e.g. `craft`, `shape`, `audit`), load its reference file too.** This is non-negotiable: `craft` without `craft.md` loaded means you'll skip the shape-and-confirm step the user expects. -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: 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. +Skipping these produces generic output that ignores the project. ### 1. Context gathering diff --git a/.trae/skills/impeccable/reference/brand.md b/.trae/skills/impeccable/reference/brand.md index b069f2553..3d83a1cdc 100644 --- a/.trae/skills/impeccable/reference/brand.md +++ b/.trae/skills/impeccable/reference/brand.md @@ -12,6 +12,8 @@ Brand isn't a neutral register. AI-generated landing pages have flooded the inte **The second slop test: aesthetic lane.** Before committing to moves, name the reference. A Klim-style specimen page is one lane; Stripe-minimal is another; Liquid-Death-acid-maximalism is another. Don't drift into editorial-magazine aesthetics on a brief that isn't editorial. A hiking brand with Cormorant italic drop caps has the wrong register within the register. +Then the inverse test: in one sentence, describe what you're about to build the way a competitor would describe theirs. If that sentence fits the modal landing page in the category, restart. + ## Typography ### Font selection procedure @@ -66,6 +68,7 @@ Brand surfaces have permission for Committed, Full palette, and Drenched strateg - Palette IS voice. A calm brand and a restless brand should not share palette mechanics. - When the strategy is Committed or Drenched, color carries the brand. Don't hedge with neutrals around the edges. Commit. - Don't converge across projects. If the last brand surface was restrained-on-cream, this one is not. +- When a cultural-symbol palette is the obvious pull, reach past it. Let the cultural reading come from typography, imagery, and copy, not the palette. ## Layout @@ -79,14 +82,14 @@ Brand surfaces have permission for Committed, Full palette, and Drenched strateg Brand surfaces lean on imagery. A restaurant, hotel, magazine, or product landing page without any imagery reads as incomplete, not as restrained. A solid-color rectangle where a hero image should go is worse than a representative stock photo. -**When the brief implies imagery (restaurants, hotels, magazines, photography, hobbyist communities, food, travel, fashion, product), you must ship imagery.** Zero images is a bug, not a design choice. "Restraint" is not an excuse. +**When the brief implies imagery (restaurants, hotels, magazines, photography, hobbyist communities, food, travel, fashion, product), you must ship imagery.** Zero images is a bug, not a design choice. "Restraint" is not an excuse. If the approved comp or brief is image-led, ship real project assets, generated raster assets, or a credible canvas/SVG/WebGL scene. Do not replace photographic, architectural, product, or place imagery with generic CSS panels, decorative diagrams, cards, bullets, or copy. -- **For greenfield work without local assets, use stock imagery.** Unsplash is the default. The URL shape is `https://images.unsplash.com/photo-{id}?auto=format&fit=crop&w=1600&q=80`. Pick real Unsplash photo IDs you're confident exist (`photo-1559339352-11d035aa65de`, `photo-1590490360182-c33d57733427`, etc.); if unsure, pick fewer photos but don't substitute colored `
` placeholders. +- **For greenfield work without local assets, use stock imagery.** Unsplash is the default. The URL shape is `https://images.unsplash.com/photo-{id}?auto=format&fit=crop&w=1600&q=80`. **Verify the URLs before referencing them.** If you have an image-search MCP, web-fetch tool, or browser access, use it to find real photo IDs and confirm they resolve. Guessed IDs (even ones that look real) often 404 and ship as broken-image placeholders. Without a verification path, pick fewer photos you're confident exist over more that you guessed; never substitute colored `
` placeholders. - **Search for the brand's physical object**, not the generic category: "handmade pasta on a scratched wooden table" beats "Italian food"; "cypress trees above a limestone hotel facade at dusk" beats "luxury hotel". - **One decisive photo beats five mediocre ones.** Hero imagery should commit to a mood; padding with more stock doesn't rescue an indecisive one. - **Alt text is part of the voice.** "Coastal fettuccine, hand-cut, served on the terrace" beats "pasta dish". -Tech / dev-tool brands are the exception where zero imagery can be correct; a developer landing page often carries its voice through typography, code samples, diagrams. Know which kind of brand you're working on. +"Imagery" here is broader than stock photography: product screenshots, custom data visualizations, generated SVG, and canvas/WebGL scenes are all imagery. Text-only pages where typography alone carries the entire visual weight are the failure mode. ## Motion @@ -102,6 +105,7 @@ Tech / dev-tool brands are the exception where zero imagery can be correct; a de - Timid palettes and average layouts. Safe = invisible. - Zero imagery on a brief that implies imagery (restaurant, hotel, food, travel, fashion, photography, hobbyist). Colored blocks where a hero photo belongs. - Defaulting to editorial-magazine aesthetics (display serif + italic + drop caps + broadsheet grid) on briefs that aren't magazine-shaped. Editorial is ONE aesthetic lane, not the default brand aesthetic. +- Repeated tiny uppercase tracked labels above every section heading. A single strong kicker can be voice; repeating it as section grammar is AI scaffolding unless it's a deliberate, named brand system. ## Brand permissions diff --git a/.trae/skills/impeccable/reference/craft.md b/.trae/skills/impeccable/reference/craft.md index bdeee0294..c0cfa7460 100644 --- a/.trae/skills/impeccable/reference/craft.md +++ b/.trae/skills/impeccable/reference/craft.md @@ -1,43 +1,41 @@ # Craft Flow -Build a feature with impeccable UX and UI quality through a structured process: shape the design, land the visual direction, build real production code, then inspect and improve in-browser until the result meets a high-end studio bar. +Build a feature with impeccable UX and UI quality: shape the design, land the visual direction, build real production code, inspect and improve in-browser until it meets a high-end studio bar. -## Build Gate +Before writing code, you need: PRODUCT.md loaded, register identified and the matching reference loaded, and a confirmed design direction for this task (either from `shape` or supplied by the user). PRODUCT.md is project context, not a task-specific brief. -Craft cannot build until all of these are true: +Treat any approved visual direction (generated mock or stated reference) as a concrete contract for composition, hierarchy, density, atmosphere, signature motifs, and distinctive visual moves. Don't let mocks replace structure, copy, accessibility, or state design. But if the live result lacks the approved direction's major ingredients, the implementation is wrong. -1. PRODUCT context is valid and current. -2. The shape design brief is explicitly confirmed by the user for this task, unless the user already provided a confirmed brief. -3. Implementation references from the brief are loaded. -4. The shape visual probe decision is recorded: generated, skipped with reason, or already resolved. -5. The north-star mock decision is recorded: generated, skipped with reason, or not applicable. +## Step 0: Project Foundation -PRODUCT.md and `teach` answers do **not** satisfy the shape gate. They are project context only. A compact self-authored brief does not satisfy the shape gate either. `shape=pass` requires a separate user response approving the shape brief or an already-confirmed brief supplied by the user. +Before shape, before code: figure out what kind of project you're working in. -Invalid image-skip reasons include: "the final implementation will be semantic HTML/CSS/SVG", "the diagram should stay editable", "a raster mock would not be used directly", or "the product is fictional." Generated probes and mocks are direction artifacts; they are not implementation assets. +Look at the working directory. Run `ls`. Check for: -## Craft Contract +- An existing framework: `astro.config.mjs/ts`, `next.config.js/ts`, `nuxt.config.ts`, `svelte.config.js`, `vite.config.js/ts`, `package.json` with framework deps, `Cargo.toml` + Leptos/Yew, `Gemfile` + Rails. **If found, use it.** Do not start a parallel build, do not introduce a second framework, do not write to `dist/` or `build/` directly. Whatever pipeline the project has, respect it. +- An existing component library or design system: `src/components/`, `app/components/`, a `tokens.css` / `theme.ts`, an `astro.config` `integrations`. Read what's there before adding to it. +- An existing icon set: `lucide-react`, `@phosphor-icons/react`, `@iconify/*`, hand-rolled SVG sprites in `assets/icons/`. **Use what's already in the project**; don't introduce a second set. -Craft is not a first pass. It is a loop with these required artifacts: +If the directory is empty (greenfield), don't pick a framework silently. Ask the user via the AskUserQuestion tool, with sensible defaults framed by the brief: -1. Confirmed design brief from `shape`. -2. Approved visual direction, from generated probes / mocks when image generation is available. -3. Mock fidelity inventory: the visible ingredients from the approved direction that must survive into code. -4. Semantic, functional implementation using the project's real stack and conventions. -5. Browser evidence across relevant viewports. -6. At least one critique-and-fix pass after the first browser inspection, unless the first pass has no material defects. +```text +What should this be built on? + - Astro (default for content-led brand sites, landing pages, marketing surfaces) + - SvelteKit / Next.js / Nuxt (when the brief implies an app surface or significant interactivity) + - Single index.html (one-shot demo, prototype, or a deliberately framework-free experiment) +``` -Do not let generated mockups replace interface structure, copy, accessibility, responsive behavior, or state design. But do treat the approved mock as a concrete visual contract for composition, hierarchy, density, atmosphere, signature motifs, image needs, and distinctive visual moves. "North star" means "preserve the important visible ingredients in semantic code," not "use it as loose mood." +Default: Astro for brand briefs, the project's existing framework for product briefs. Ask once; don't re-ask mid-task. ## Step 1: Shape the Design -Run /impeccable shape, passing along whatever feature description the user provided. +Run /impeccable shape, passing along whatever feature description the user provided. Shape is **required** for craft; it is what produces a confirmed direction. -Wait for the design brief to be fully confirmed by the user before proceeding. The brief is your blueprint, and every implementation decision should trace back to it. +Present the shape output and stop. Wait for the user to confirm, override, or course-correct before writing code. -If this craft run resumed after `teach` created PRODUCT.md, run shape now. Do not treat the teach interview, PRODUCT.md, or a summary of project context as a substitute for shape. Shape is task-specific and must cover scope, content/states, visual direction, constraints, anti-goals, probes when applicable, and explicit brief confirmation. +If the user already supplied a confirmed brief or ran shape separately, use it and skip this step. -If the user has already run /impeccable shape and has a confirmed design brief, skip this step and use the existing brief. +When the original prompt + PRODUCT.md already answer scope, content, and visual direction with no real ambiguity, the shape output can be **compact** (3-5 bullets stating what you're building and the visual lane, ending with one or two specific questions or "confirm or override"). The full 10-section structured brief is reserved for genuinely ambiguous, multi-screen, or stakeholder-heavy tasks. Don't pad a clear brief into a long one to look thorough; equally, don't skip the pause to look efficient. ## Step 2: Load References @@ -55,79 +53,60 @@ Then add references based on the brief's needs: ## Step 3: Land the Visual Direction (Capability-Gated) -Before implementation, generate high-fidelity visual comps when all of these are true: +Generate high-fidelity visual comps before implementation when all three are true: -- The work is **net-new** or visually open-ended enough that composition exploration will improve the build. -- The brief's scope is **mid-fi, high-fi, or production-ready**. -- The current harness has **built-in image generation capability** (for example, Codex with a native image tool). Do **not** ask the user to set up external APIs, shell scripts, or one-off tooling just to do this. +- The work is net-new or visually open-ended enough that composition exploration will improve the build. +- The brief's scope is mid-fi, high-fi, or production-ready. +- The harness gives you native image generation (Codex's `image_gen`, an equivalent MCP tool). Don't ask the user to set up external APIs. -When those conditions are met, this step is mandatory for **both brand and product work** in Codex and any harness with built-in image generation. Use native image generation; in Codex, use the built-in `image_gen` tool via the imagegen skill. If image generation is unavailable, do not ask the user to install APIs or tooling. State in one line that the image step is skipped because the harness lacks native image generation, then proceed. - -Do not skip this step because the eventual UI should be semantic, editable, code-native, responsive, or accessible. Those are implementation requirements, not reasons to avoid visual exploration. - -### Purpose - -Use the mock step to find a stronger visual lane than code-first generation would reliably discover on its own. The brief remains authoritative on user, purpose, content, constraints, states, and anti-goals. The mock clarifies composition, hierarchy, density, typography, and visual tone. +When met, this step is mandatory for both brand and product work. If image generation isn't available, skip silently. "The eventual UI is semantic/code-native/accessible" is not a reason to skip; those are implementation requirements, not exploration ones. ### What to generate -Generate **1 to 3** high-fidelity north-star comps based on the confirmed brief. If shape already produced direction probes, use those results as input and generate a more resolved mock from the winning lane, not another unrelated exploration. +Generate **1 to 3** high-fidelity north-star comps from the confirmed brief. If shape already produced direction probes, resolve the winning lane further, not an unrelated exploration. Comps must differ in primary visual direction, not just color. -- For brand work, push visual identity, composition, and mood aggressively. -- For product work, still push hierarchy, topology, density, and tone, but keep the comps grounded in realistic product structure and states. -- For landing pages and long-form brand surfaces, show enough of the next section or second fold to establish the system beyond the hero. - -The comps must be genuinely different in primary visual direction, not just color variants. +- Brand work: push visual identity, composition, and mood aggressively. +- Product work: push hierarchy, topology, density, tone, grounded in realistic product structure. +- Landing pages and long-form brand surfaces: show enough of the second fold to establish the system beyond the hero. ### Approval loop -Show the comps and ask what should carry forward. If the user asks for changes or the best direction is still weak, generate a focused revision before implementation. Continue until one direction is approved, or until the user explicitly delegates the choice. +Show the comps and ask what carries forward. Iterate until one direction is approved or the user delegates. If the user delegates, pick the strongest direction and explain it from the brief, not personal taste. -If the user delegates, pick the strongest direction and explain the decision using the brief, not personal taste. - -Before moving to implementation, summarize: - -- What to carry into code -- What **not** to literalize from the mock - -This summary is required before Step 4. It is the handoff between visual exploration and semantic implementation. +Before Step 4, summarize what to carry into code and what **not** to literalize from the mock. This is the handoff between visual exploration and semantic implementation. ### Mock fidelity inventory -Before building, inventory the approved mock's major visible ingredients: +Inventory the approved mock's major visible ingredients: -- Hero silhouette and dominant composition. -- Signature motifs: planets, devices, portraits, charts, route lines, insets, badges, or other memorable objects. -- Nav and primary CTA treatment. -- Section sequence visible in the mock, especially the second fold. -- Image-native content the concept depends on. -- Typography, density, color/material treatment, and motion cues. +- Hero silhouette and dominant composition +- Signature motifs (planets, devices, portraits, charts, route lines, insets, badges, etc.) +- Nav and primary CTA treatment +- Section sequence, especially the second fold +- Image-native content the concept depends on +- Typography, density, color/material treatment, motion cues -For each ingredient, decide how it will be implemented: semantic HTML/CSS/SVG, generated asset, sourced project asset, icon library, canvas/WebGL, or an explicitly accepted omission. Do not substitute a different hero composition or new visual driver after approval unless the user approves the change. +For each, decide implementation: semantic HTML/CSS/SVG, generated asset, sourced asset, icon library, canvas/WebGL, or accepted omission. Don't substitute a different hero composition or visual driver post-approval without user sign-off. -Treat the mock as a **north star**, not a screenshot to trace. Do **not** rasterize core UI text or let the mock override the confirmed brief. But if the live result lacks the mock's major visible ingredients, the implementation is wrong. +If a photographic, architectural, product, or place-led mock becomes generic CSS scenery / decorative diagrams / bullets / copy, stop and fix it. That's a broken implementation, not a harmless interpretation. + +Treat the mock as a north star, not a screenshot to trace. Don't rasterize core UI text. But if the live result lacks the mock's major ingredients, the implementation is wrong. ## Step 4: Asset Extraction (Need-Gated) -If the chosen direction includes image-native visual ingredients that would materially improve the implementation, generate them as separate assets before building. +If the approved direction needs raster assets, create them before building. Do not replace required imagery with generic cards, bullets, emoji, fake metrics, decorative CSS panels, or filler copy. -Good candidates: +Use the native asset producer (`impeccable_asset_producer` in Codex, `impeccable-asset-producer` in Claude Code) to create clean assets from the hi-fi mock and crops. If you do not have explicit permission to use agents, stop and ask: -- stickers -- badges -- seals -- tickets -- graphic labels -- textures -- abstract objects -- decorative marks -- non-semantic scene elements +```text +Asset production will work better as a scoped subagent job. Should I spawn the Impeccable asset producer subagent for this step? +``` -For travel, editorial, portfolio, venue, product showcase, entertainment, education, or any other image-led brand surface, visual assets are usually core content, not decoration. Do not ship abstract CSS panels where the approved mock or subject matter calls for real imagery, generated plates, illustrations, maps, product/object renders, or destination scenes. +Do not skip asset production or silently do it inline. Inline asset production is allowed only if the user declines subagents, the harness cannot spawn the authorized agent, or the user explicitly asks for single-thread mode. -Do **not** export assets for core UI text, navigation, body copy, or any structure that should stay semantic and editable in code. +Pass the approved mock, crop/contact-sheet paths, output directory, dimensions/formats, transparency needs, constraints, and avoid list to the asset producer. Attach image generation capability to the spawned agent when the harness supports it; do not load image-generation reference material into the parent thread first. -Usually **1 to 5** extracted assets is enough. If the design can be built cleanly in HTML/CSS/SVG, prefer that over raster assets. If the mock contains major visual content that cannot be built credibly in code, asset extraction is not optional. +Prefer HTML/CSS/SVG/canvas when they can credibly reproduce an ingredient; use real/generated/stock imagery when the mock or subject matter calls for actual visual content. ## Step 5: Build to Production Quality @@ -135,50 +114,35 @@ Implement the feature following the design brief. Build in passes so structure, ### Production bar -- Use real or realistic content. Remove placeholder copy, placeholder images, dead links, fake controls, and unused scaffold before presenting. -- Preserve the approved mock's major ingredients. Missing hero objects, missing world/product imagery, different section structure, downgraded CTA/nav treatment, or generic replacements for distinctive motifs are blocking defects unless the user accepted the change. -- Build semantically first: real headings, landmarks, labels, form associations, button/link semantics, accessible names, and state announcements where needed. -- Calibrate spacing, alignment, grid placement, and vertical rhythm deliberately. Do not accept default gaps, arbitrary margins, unbalanced whitespace, or accidental optical misalignment. -- Make typography intentional: chosen font loading strategy, clear hierarchy, readable measure, stable line breaks, tuned wrapping, and no overflow at mobile or large desktop sizes. -- Design realistic state coverage: default, hover where supported, focus-visible, active, disabled, loading, error, success, empty, overflow, long text, short text, and first-run states where relevant. -- Make interaction quality feel finished: keyboard paths, touch targets, feedback timing, scroll behavior, transitions between states, and no hover-only functionality. -- Use icons from the project's established icon set when available. If no set exists, choose a coherent library or use accessible text controls; do not mix unrelated icon styles. -- Optimize imagery and media: correct dimensions, useful alt text, lazy loading below the fold, modern formats when practical, responsive `srcset` / `picture` for raster assets, and no project-referenced asset left outside the workspace. -- Make motion feel premium: use atmospheric blur, filter, mask, shadow, or reveal effects when they improve the experience; avoid casual layout-property animation, bound expensive effects, verify smoothness in-browser, respect reduced motion, and avoid choreography that blocks task completion. -- Preserve maintainability: reusable local patterns, clear component boundaries, project conventions, no rasterized UI text, and no hard-coded one-off hacks when a better local pattern exists. -- Fit the technical context: production build passes, no obvious console errors, no avoidable layout shift, no needless dependency, and no broken asset path. -- If you discover a design question that materially changes the brief or approved direction, stop and ask rather than guessing. +- **Real content.** No placeholder copy, placeholder images, dead links, fake controls, or unused scaffold at presentation time. +- **Preserve the approved mock's major ingredients.** Missing hero objects, world/product imagery, section structure, CTA/nav treatment, or distinctive motifs are blocking defects unless the user accepted the change. +- **Semantic first.** Real headings, landmarks, labels, form associations, button/link semantics, accessible names, state announcements where needed. +- **Deliberate spacing and alignment.** No default gaps, arbitrary margins, unbalanced whitespace, or accidental optical misalignment. +- **Intentional typography.** Chosen loading strategy, clear hierarchy, readable measure, stable line breaks, no overflow at any width. +- **Realistic state coverage.** Default, hover, focus-visible, active, disabled, loading, error, success, empty, overflow, long/short text, first-run. +- **Finished interaction quality.** Keyboard paths, touch targets, feedback timing, scroll behavior, state transitions, no hover-only functionality. +- **Coherent icon set.** Use the project's established set; otherwise pick one library or use accessible text. Don't mix. +- **Respect the build pipeline.** Edit source files and run the project's build (`npm run build` or equivalent). Don't write to `build/` / `dist/` / `.next/` with `cat`, heredoc, or Bash redirects; that skips asset hashing, image optimization, code splitting, and CSS extraction, and produces output the dev server won't serve. +- **Verify image URLs before referencing them.** Use image-search MCP or web-fetch when available; guessed photo IDs ship as broken-image placeholders. Without verification, prefer fewer images you're confident about. +- **Optimized imagery and media.** Correct dimensions, useful alt text, lazy loading below the fold, modern formats when practical, responsive `srcset`/`picture` for raster, no project-referenced asset left outside the workspace. +- **Premium motion.** Use atmospheric blur, filter, mask, shadow, reveal when they improve the experience. Avoid casual layout-property animation, bound expensive effects, verify smoothness in-browser, respect reduced motion, and avoid choreography that blocks task completion. +- **Maintainable.** Reusable local patterns, clear component boundaries, project conventions. No rasterized UI text or one-off hacks when a local pattern exists. +- **Technically clean.** Production build passes, no console errors, no avoidable layout shift, no needless dependencies, no broken asset paths. +- **Ask when uncertain.** If a discovery materially changes the brief or approved direction, stop and ask. Don't guess. -## Step 6: Browser-Based Iteration +## Step 6: Iterate Visually -**This step is critical.** Do not stop after the first implementation pass. +Look at what you built like a designer would. Your eyes are whatever the harness gives you: a connected browser, a screenshotting tool, Playwright, or asking the user. Use them for responsive testing (mobile, tablet, desktop minimum) and general visual validation. -Open the result in a browser. In Codex, use browser-use or equivalent browser automation when available; otherwise use Playwright or ask the user for screenshots. Inspect screenshots, not just DOM or terminal output. +If your tool returns a file path, read the PNG back into the conversation. A screenshot you didn't read doesn't count. -### Required viewport pass +For long-form brand surfaces, inspect major sections individually. Thumbnails hide spacing, clipping, and cascade defects. -Check the experience at the viewports that matter for the brief. Default minimum: +After the first pass, write an honest critique against the brief, the approved mock's major ingredients (hero silhouette, motifs, imagery, nav/CTA, density), and impeccable's DON'Ts. Patch material defects and re-inspect. **Don't invent defects to demonstrate iteration.** A confident "first pass clean, shipping" beats a fake fix. -- Mobile narrow -- Tablet or small laptop -- Desktop wide +Actively check: responsive behavior (composes, not shrinks), every state (empty / error / loading / edge), craft details (spacing, alignment, hierarchy, contrast, motion timing, focus), performance basics. The exit bar: defensible in a high-end studio review. -For each viewport, capture or inspect the rendered state and look for visual defects: overlap, clipping, weak hierarchy, off-grid alignment, awkward whitespace, cramped controls, unreadable type, broken imagery, hover-only functionality, layout shift, and text overflow. - -### Critique and fix loop - -After the first browser pass, write a short critique for yourself and patch the implementation. Repeat browser inspection after fixes. Continue until no material issues remain against this checklist: - -1. **Does it match the brief?** Compare the live result against every section of the design brief. Fix discrepancies. -2. **Does it match the approved mock?** Compare screenshots against the mock fidelity inventory: hero silhouette, major motifs, imagery, nav/CTA, section sequence, density, color/materials, and second-fold substance. Missing major ingredients are P0 defects. -3. **Does it pass the AI slop test?** If someone saw this and said "AI made this," would they believe it immediately? If yes, it needs more design intention. -4. **Check against impeccable's DON'T guidelines.** Fix any anti-pattern violations. -5. **Check every state.** Navigate through empty, error, loading, and edge case states. Each one should feel intentional, not like an afterthought. -6. **Check responsive behavior.** The design should adapt compositionally, not merely shrink. -7. **Check craft details.** Spacing consistency, optical alignment, type hierarchy, color contrast, image quality, icon coherence, interactive feedback, motion timing, and focus treatment. -8. **Check performance basics.** No obviously oversized images, avoidable layout thrash, blocking animations, or heavy assets without a reason. - -The exit bar is not "it works." It is: the rendered result looks intentional at all checked viewports, all expected states are handled, no placeholders remain unless explicitly accepted, and the implementation quality would be defensible in a high-end studio review. +Detector or QA output is defect evidence only; never proof the work is finished. ## Step 7: Present @@ -189,5 +153,3 @@ Present the result to the user: - Explain design decisions that connect back to the design brief and, when used, the chosen north-star mock. Include any accepted deviations from the mock; do not hide unimplemented mock ingredients. - Note any remaining limitations or follow-up risks honestly - Ask: "What's working? What isn't?" - -Iterate based on feedback. Good design is rarely right on the first pass. diff --git a/.trae/skills/impeccable/reference/critique.md b/.trae/skills/impeccable/reference/critique.md index 1033d9464..6db43b3ec 100644 --- a/.trae/skills/impeccable/reference/critique.md +++ b/.trae/skills/impeccable/reference/critique.md @@ -43,7 +43,7 @@ Run the bundled deterministic detector, which flags 27 specific patterns (AI slo **CLI scan**: ```bash -npx impeccable --json [--fast] [target] +npx impeccable detect --json [--fast] [target] ``` - Pass HTML/JSX/TSX/Vue/Svelte files or directories as `[target]` (anything with markup). Do not pass CSS-only files. diff --git a/.trae/skills/impeccable/reference/polish.md b/.trae/skills/impeccable/reference/polish.md index a2a409e48..eed3dbd27 100644 --- a/.trae/skills/impeccable/reference/polish.md +++ b/.trae/skills/impeccable/reference/polish.md @@ -2,6 +2,8 @@ Perform a meticulous final pass to catch all the small details that separate good work from great work. The difference between shipped and polished. +Detector and automated QA output are defect evidence only. A clean script result is never proof that the design is strong; gather browser evidence and inspect the real interaction path. + ## Design System Discovery Aligning the feature to the design system is **not optional**. Polish without alignment is decoration on top of drift, and it makes the next person's job harder. Discovery comes before any other polish work. @@ -216,11 +218,12 @@ Sweat the details. Zoom in until the alignment is right and the spacing reads as Before marking as done: -- **Use it yourself**: Actually interact with the feature -- **Test on real devices**: Not just browser DevTools -- **Ask someone else to review**: Fresh eyes catch things -- **Compare to design**: Match intended design -- **Check all states**: Don't just test happy path +- **Use it yourself**: Actually interact with the feature. +- **Test on real devices**: Not just browser DevTools. +- **Ask someone else to review**: Fresh eyes catch things. +- **Compare to design**: Match intended design. +- **Check all states**: Don't just test happy path. +- **Treat automation carefully**: Run detector or QA commands when they are available and relevant, fix their defects, but never cite a clean result as proof that the work is polished. ## Clean Up @@ -230,4 +233,3 @@ After polishing, ensure code quality: - **Remove orphaned code**: Delete unused styles, components, or files made obsolete by polish. - **Consolidate tokens**: If you introduced new values, check whether they should be tokens. - **Verify DRYness**: Look for duplication introduced during polishing and consolidate. - diff --git a/.trae/skills/impeccable/reference/shape.md b/.trae/skills/impeccable/reference/shape.md index 0785187ef..d1c983ff4 100644 --- a/.trae/skills/impeccable/reference/shape.md +++ b/.trae/skills/impeccable/reference/shape.md @@ -16,14 +16,16 @@ This is a required interaction, not optional guidance. Ask these questions in co ### Interview cadence -Discovery must include at least one user-answer round unless PRODUCT.md, DESIGN.md, or an already-confirmed brief directly answers the needed design inputs. With a sparse prompt, do **not** synthesize a complete brief for confirmation on the first response. +Discovery includes at least one user-answer round unless PRODUCT.md, DESIGN.md, or an already-confirmed brief directly answers the needed inputs. With a sparse prompt, do **not** synthesize a complete brief for confirmation on the first response. - Use the harness's structured question tool when one exists. Otherwise, ask directly in chat and stop. - Ask **2-3 questions per round**, then wait for answers. - Treat PRODUCT.md and DESIGN.md as anchors; they reduce repeated questions but do **not** replace shape for craft. Shape is task-specific. -- Round 1 should clarify purpose, audience/context, and success or emotional outcome. -- Round 2 should clarify content/data/states and scope/fidelity. -- Round 3 should clarify visual direction, constraints, and anti-goals when still unresolved. +- One round is the default. Add a second only if the first answers leave material gaps. Don't run a second round just to feel thorough. +- Round 1 should clarify purpose, audience/context, content/scope, and (for brand) visual direction. +- Round 2, when needed, fills in whatever's still genuinely missing. + +**Assert-then-confirm, not menu-with-escape.** When PRODUCT.md and the user's prompt make one option obvious, name it and ask the user to confirm or override. Don't enumerate "Restrained / Committed / Or something else?" as a real choice; "This reads as Restrained, confirm?" beats a four-option menu when the answer is already clear. ### Purpose & Context - What is this feature for? What problem does it solve? @@ -36,6 +38,7 @@ Discovery must include at least one user-answer round unless PRODUCT.md, DESIGN. - What are the realistic ranges? (Minimum, typical, maximum, e.g., 0 items, 5 items, 500 items) - What are the edge cases? (Empty state, error state, first-time use, power user) - Is any content dynamic? What changes and how often? +- What visual assets are real content here? Note required images, product shots, illustrations, maps, textures, diagrams, generated objects, or existing project assets. ### Design Direction @@ -72,9 +75,9 @@ After the discovery interview, generate a small set of visual direction probes * - The work is **net-new** or directionally ambiguous enough that visual exploration will clarify the brief. - The requested fidelity is **mid-fi, high-fi, or production-ready**. Skip for sketch-only planning. -- The current harness has **built-in image generation capability** (for example, Codex with a native image tool). Do **not** ask the user to set up external APIs, shell scripts, or one-off tooling just to do this. +- The current harness gives you native image generation (Codex's `image_gen`, an equivalent MCP tool, or similar). Don't ask the user to install APIs or tooling. -When those conditions are met, this step is mandatory for Codex and any harness with built-in image generation. Use native image generation; in Codex, use the built-in `image_gen` tool via the imagegen skill. If image generation is unavailable, do not ask the user to install APIs or tooling. State in one line that the image step is skipped because the harness lacks native image generation, then proceed. +When those conditions are met, this step is mandatory. If image generation isn't natively available, skip silently and proceed; don't announce the skip. Use probes to explore visual lanes, not to replace the brief. @@ -104,11 +107,20 @@ The probes should differ in primary visual direction (hierarchy, topology, densi - Do **not** treat generated imagery as final UX specification, final copy, or final accessibility behavior. - Do **not** use this step for minor refinements of existing work. It's for shaping a new surface or clarifying a big directional choice. -If image generation is unavailable, or the task doesn't benefit from it, skip this phase only with a one-line reason and proceed directly to the design brief. +If image generation isn't natively available, skip this phase silently and proceed. ## Phase 2: Design Brief -After the interview and any required probes, synthesize everything into a structured design brief. Present it to the user for explicit confirmation before considering this command complete. Stop after asking for confirmation; do not proceed to craft or implementation in the same response unless the user has already approved the brief. +After the interview and any required probes, present a brief and **end your response**. The user must confirm before any implementation runs. Do not present a brief and then continue to code in the same response, even if the brief feels obvious to you. The user's confirmation is the gate. + +**Choose the brief shape based on how clear the answers are:** + +- **Compact form (3-5 bullets)** when discovery was crisp and the original prompt + PRODUCT.md already pinned scope, content, and direction. State what you're building, the visual lane, and end with one or two specific questions or a clear "confirm or override?" prompt. This is the default for typical craft requests with a clear prompt. +- **Full structured form (sections below)** when the task is genuinely ambiguous, multi-screen, or when the user asked for shape as a standalone step. Use this when the discipline of structure earns its weight. + +Don't pad a clear brief into a long one to look thorough. A 70-line brief restating answers the user just gave is noise, not rigor. Equally, don't skip the confirmation pause to look efficient: the pause is the point. + +If the user already said "approved" or "go" during discovery for the *exact direction you'd present*, that counts as confirmation; you may proceed without asking again. But if your brief adds anything the user hasn't seen and approved, you must stop and confirm. ### Brief Structure @@ -136,16 +148,18 @@ List every state the feature needs: default, empty, loading, error, success, edg How users interact with this feature. What happens on click, hover, scroll? What feedback do they get? What's the flow from entry to completion? **8. Content Requirements** -What copy, labels, empty state messages, error messages, and microcopy are needed. Note any dynamic content and its realistic ranges. +What copy, labels, empty state messages, error messages, and microcopy are needed. Note any dynamic content and its realistic ranges. For image-led surfaces, also list the required image/media roles and their likely source (project asset, generated raster, semantic SVG/CSS, canvas/WebGL, icon library, or accepted omission). **9. Recommended References** Based on the brief, list which impeccable reference files would be most valuable during implementation (e.g., spatial-design.md for complex layouts, motion-design.md for animated features, interaction-design.md for form-heavy features). **10. Open Questions** -Anything unresolved that the implementer should resolve during build. +Anything genuinely unresolved. Don't list "open questions" you've already recommended a default for; assert the default and move on. If you'd write `Recommend: X` next to a question, just decide X. --- -ask the user directly to clarify what you cannot infer. Ask for explicit confirmation of the brief before finishing. If the user disagrees with any part, revisit the relevant discovery questions. A shape run is incomplete until the brief is confirmed. +ask the user directly to clarify what you cannot infer. + +If the user disagrees with any part, revisit the relevant discovery questions. A shape run is incomplete until the user confirms direction (or the user already gave a clear go during discovery, which counts). Once confirmed, the brief is complete. The user can now hand it to /impeccable, or use it to guide any other implementation approach. (If the user wants the full discovery-then-build flow in one step, they should use /impeccable craft instead, which runs this command internally.) diff --git a/HARNESSES.md b/HARNESSES.md index d67b7e9f7..9c764f0c3 100644 --- a/HARNESSES.md +++ b/HARNESSES.md @@ -50,7 +50,7 @@ Fields marked with * are spec-standard. Others are provider extensions. Notes: - Gemini CLI validates only `name` and `description`; other spec fields are parsed but ignored. -- Codex CLI uses a separate `agents/openai.yaml` sidecar for extended metadata (icons, branding, MCP tools, invocation control). +- Codex CLI uses a separate `agents/openai.yaml` sidecar for skill metadata (icons, branding, MCP tools, invocation control). Native Codex custom agents are separate TOML files under `.codex/agents/` or `~/.codex/agents/`. - Kiro recognizes `user-invocable` and `disable-model-invocation` per community reports but does not formally document them. - Unknown fields are silently ignored by all harnesses. @@ -73,6 +73,15 @@ Notes: All harnesses support the `{skill-name}/SKILL.md` directory structure with optional `reference/`, `scripts/`, and `assets/` subdirectories. +## Native Subagent Directory Structure + +| Harness | Native directory | File format | +|---------|------------------|-------------| +| Claude Code | `.claude/agents/` | Markdown with YAML frontmatter | +| Codex CLI | `.codex/agents/` | TOML | + +Impeccable keeps canonical agent prompts under `skill/agents/` and emits provider-native files only for harnesses with documented subagent formats. + ## Placeholder / Variable Substitution Claude Code supports runtime variable substitution directly in SKILL.md bodies: `$ARGUMENTS`, `$0`-`$N`, `${CLAUDE_SKILL_DIR}`, `${CLAUDE_SESSION_ID}`. No other harness supports substitution in skills. diff --git a/PRODUCT.md b/PRODUCT.md index 5e2435b91..abbc1430c 100644 --- a/PRODUCT.md +++ b/PRODUCT.md @@ -6,11 +6,11 @@ brand ## Users -Frontend and full-stack developers who use AI coding tools (Cursor, Claude Code, Gemini CLI, Codex CLI, and others) and want better design output from their AI. They land on the site from GitHub, social media, or word of mouth, already aware that AI-generated UIs have quality problems. They're looking for a practical solution, not education about the problem. +Designers, product managers, and engineers who use AI coding tools (Cursor, Claude Code, Gemini CLI, Codex CLI, and others) and want better design output from their AI. They land on the site from GitHub, social media, or word of mouth, already aware that AI-generated UIs have quality problems. They're looking for a practical solution, not education about the problem. ## Product Purpose -Impeccable gives developers a shared design vocabulary with their AI, delivered as a plug-and-play skill that works in every major AI coding harness. Success is measured in two ways: (1) the developer can steer AI output with design precision instead of vague prose, and (2) the AI produces interfaces that pass professional design review, not "looks like an AI made it" output. +Impeccable gives builders a shared design vocabulary with their AI, delivered as a plug-and-play skill that works in every major AI coding harness. Success is measured in two ways: (1) the user can steer AI output with design precision instead of vague prose, and (2) the AI produces interfaces that pass professional design review, not "looks like an AI made it" output. ## Brand Personality diff --git a/README.md b/README.md index 5d2ae02da..c899efbf5 100644 --- a/README.md +++ b/README.md @@ -145,10 +145,14 @@ cp -r dist/gemini/.gemini your-project/ ```bash # Project-local cp -r dist/agents/.agents your-project/ +mkdir -p your-project/.codex +cp -r dist/codex/.codex/agents your-project/.codex/ # Or user-wide mkdir -p ~/.agents/skills cp -r dist/agents/.agents/skills/* ~/.agents/skills/ +mkdir -p ~/.codex +cp -r dist/codex/.codex/agents ~/.codex/ ``` **GitHub Copilot:** diff --git a/cli/engine/detect-antipatterns-browser.js b/cli/engine/detect-antipatterns-browser.js index 00c608176..876895273 100644 --- a/cli/engine/detect-antipatterns-browser.js +++ b/cli/engine/detect-antipatterns-browser.js @@ -257,6 +257,16 @@ const ANTIPATTERNS = [ skillSection: 'Typography', skillGuideline: 'tiny uppercase tracked label above the hero headline', }, + { + id: 'repeated-section-kickers', + category: 'slop', + severity: 'advisory', + name: 'Repeated section kicker labels', + description: + 'Repeating tiny uppercase tracked labels above section headings turns a brand page into AI editorial scaffolding. Replace them with stronger structure, artifacts, imagery, or a deliberate brand system.', + skillSection: 'Typography', + skillGuideline: 'repeated eyebrow or kicker labels as section scaffolding', + }, // ── Quality: general design and accessibility issues ── { @@ -309,6 +319,13 @@ const ANTIPATTERNS = [ description: 'Text is too close to the edge of its container. Add at least 8px (ideally 12-16px) of padding inside bordered or colored containers.', }, + { + id: 'body-text-viewport-edge', + category: 'quality', + name: 'Body text touching viewport edge', + description: + 'Body paragraphs render flush against the left or right viewport edge with no container providing horizontal padding. Wrap content in a container with at least 16px (ideally 24-32px) of horizontal padding, or apply max-width with mx-auto.', + }, { id: 'tight-leading', category: 'quality', @@ -553,7 +570,20 @@ function checkColors(opts) { const isLargeText = fontSize >= 18 || (fontSize >= 14 && fontWeight >= 700) || isHeading; const threshold = isLargeText ? 3.0 : 4.5; if (ratio < threshold) { - findings.push({ id: 'low-contrast', snippet: `${ratio.toFixed(1)}:1 (need ${threshold}:1) — text ${colorToHex(textColor)} on ${colorToHex(bgs[worstIdx])}` }); + // Skip the false-positive class where text has alpha < 1 AND we + // couldn't find an opaque ancestor (effectiveBg is null, we're + // comparing against gradient-stop fallback). In jsdom mode the + // detector can't resolve `var(--X)` color tokens, so a dark + // section sitting between the text and the body's decorative + // gradient is invisible to us — we end up measuring contrast + // against the body's paper-grain noise instead of the real + // local bg. Real low-contrast bugs use alpha=1 and have a + // resolvable opaque ancestor; semi-transparent Tailwind tokens + // like `text-paper/60` on `bg-ink` sections are the FP pattern. + const isAlphaFallbackFP = !IS_BROWSER && !effectiveBg && (textColor.a != null && textColor.a < 1); + if (!isAlphaFallbackFP) { + findings.push({ id: 'low-contrast', snippet: `${ratio.toFixed(1)}:1 (need ${threshold}:1) — text ${colorToHex(textColor)} on ${colorToHex(bgs[worstIdx])}` }); + } } } @@ -698,41 +728,114 @@ function checkItalicSerif(opts) { }]; } +// Color saturation check. Returns true when the color has visible +// chroma — i.e., it's an "accent color" rather than near-neutral. +// Handles rgb()/rgba(), #hex, oklch(), and hsl(). var() refs are +// expected to be pre-resolved by the caller. +function isAccentColor(cssColor) { + if (!cssColor) return false; + const s = String(cssColor).trim(); + // rgb / rgba — direct channel-distance check. + const rgbM = /rgba?\(\s*(\d+)\s*,?\s+|\s*(\d+)\s*,\s*(\d+)\s*,\s*(\d+)/.exec(s.replace(/rgba?\(\s*/, 'rgb(').replace(/,/g, ', ')); + const rgbStrict = /rgba?\(\s*(\d+)\s*,\s*(\d+)\s*,\s*(\d+)/.exec(s); + if (rgbStrict) { + const r = +rgbStrict[1], g = +rgbStrict[2], b = +rgbStrict[3]; + return (Math.max(r, g, b) - Math.min(r, g, b)) >= 40; + } + // #hex — 3, 4, 6, or 8 digit. + const hexM = /^#([0-9a-f]{3,8})\b/i.exec(s); + if (hexM) { + let h = hexM[1]; + if (h.length === 3 || h.length === 4) h = h.split('').map((c) => c + c).join('').slice(0, 6); + else h = h.slice(0, 6); + if (h.length === 6) { + const r = parseInt(h.slice(0, 2), 16); + const g = parseInt(h.slice(2, 4), 16); + const b = parseInt(h.slice(4, 6), 16); + return (Math.max(r, g, b) - Math.min(r, g, b)) >= 40; + } + } + // oklch(L C H) — chroma C is what matters. Typical neutral grays + // have C < 0.02; visible accents are 0.05+. CSS minification can + // collapse spaces between L% and C ("oklch(43%.15 34)"), so we + // extract all numbers and take the second rather than matching a + // strict L-then-whitespace-then-C pattern. + if (/^oklch\(/i.test(s)) { + const nums = s.match(/\d*\.\d+|\d+/g); + if (nums && nums.length >= 2) { + const c = parseFloat(nums[1]); + return !Number.isNaN(c) && c >= 0.05; + } + } + // hsl(H, S%, L%) — saturation > 20% reads as accent. + const hslM = /hsla?\(\s*[\d.]+\s*,\s*([\d.]+)%/i.exec(s); + if (hslM) { + const sat = parseFloat(hslM[1]); + return !Number.isNaN(sat) && sat >= 20; + } + return false; +} + // Sibling-relationship rule. Anchor on a hero-scale h1, look at the -// previousElementSibling, and gate on uppercase + tracked + small. +// previousElementSibling, and gate on EITHER the classic tracked- +// uppercase eyebrow OR the modern accent-colored bold eyebrow. function checkHeroEyebrow(opts) { const { headingTag, headingText, headingFontSize, siblingTag, siblingText, siblingTextTransform, siblingFontSize, siblingLetterSpacing, + siblingFontWeight, siblingColor, } = opts; if (headingTag !== 'h1') return []; - if (!headingFontSize || headingFontSize < 48) return []; + // We previously gated on headingFontSize >= 48 to anchor "hero scale". + // But modern hero h1s use clamp() / vw / var(--text-*), none of which + // jsdom can resolve — the computed value comes back as "2em" or + // "var(--text-9xl)" and parseFloat returns 2 or NaN. The gate fails + // on virtually every Tailwind v4 / framework build. The other gates + // (sibling text 2-60 chars, font-size ≤ 14px, accent-bold OR + // tracked-caps) are tight enough to avoid false positives on non- + // hero h1s — a tiny tan label directly above any h1 is the + // antipattern regardless of how big the h1 ends up. if (!siblingTag) return []; // An h2 above an h1 is a different anti-pattern (heading hierarchy / dual // headings) — never an eyebrow. if (HEADING_TAGS.has(siblingTag)) return []; const text = (siblingText || '').trim(); - if (text.length < 2 || text.length > 30) return []; + if (text.length < 2 || text.length > 60) return []; + if (!(siblingFontSize > 0 && siblingFontSize <= 14)) return []; - // Uppercase: either via text-transform, or the content is already typed - // uppercase (no lowercase letters, at least one uppercase letter). + // Branch A: classic tracked-uppercase eyebrow. const isUppercased = siblingTextTransform === 'uppercase' || (/[A-Z]/.test(text) && !/[a-z]/.test(text)); - if (!isUppercased) return []; + const isClassicTracked = isUppercased && siblingLetterSpacing >= 1.6; - if (!(siblingLetterSpacing >= 1.6)) return []; - if (!(siblingFontSize > 0 && siblingFontSize <= 14)) return []; + // Branch B: modern accent-bold eyebrow — sentence case, low + // tracking, but bold + accent-colored. The style choices changed; + // the pattern is the same kicker-above-headline anti-pattern. + const weight = Number(siblingFontWeight) || 400; + const isAccentBold = weight >= 700 && isAccentColor(siblingColor || ''); + + if (!isClassicTracked && !isAccentBold) return []; const headingTextSnippet = (headingText || '').trim().slice(0, 60); const eyebrowSnippet = text.slice(0, 40); + const style = isClassicTracked ? 'tracked-caps' : 'accent-bold'; return [{ id: 'hero-eyebrow-chip', - snippet: `eyebrow chip "${eyebrowSnippet}" above ${headingTag} "${headingTextSnippet}"`, + snippet: `eyebrow chip (${style}) "${eyebrowSnippet}" above ${headingTag} "${headingTextSnippet}"`, }]; } +function checkRepeatedSectionKickers(opts) { + const { candidates, minCount = 3 } = opts; + if (!Array.isArray(candidates) || candidates.length < minCount) return []; + return candidates.map(candidate => ({ + id: 'repeated-section-kickers', + snippet: `repeated section kicker "${candidate.kickerText}" before ${candidate.headingTag} "${candidate.headingText}" (${candidates.length} on page)`, + })); +} + const LAYOUT_TRANSITION_PROPS = new Set([ 'width', 'height', 'padding', 'margin', 'max-height', 'max-width', 'min-height', 'min-width', @@ -974,43 +1077,60 @@ function readOwnBackgroundColor(el, computedStyle) { return bg; } -function resolveBackground(el, win) { +function resolveBackground(el, win, customPropMap) { let current = el; while (current && current.nodeType === 1) { const style = IS_BROWSER ? getComputedStyle(current) : win.getComputedStyle(current); - - // If this element has a background-image (gradient or url), it's visually - // opaque but we can't determine the effective color — bail out so callers - // don't get a false solid-color answer. const bgImage = style.backgroundImage || ''; - if (bgImage && bgImage !== 'none' && (/gradient/i.test(bgImage) || /url\s*\(/i.test(bgImage))) { - return null; - } + const hasGradientOrUrl = bgImage && bgImage !== 'none' && (/gradient/i.test(bgImage) || /url\s*\(/i.test(bgImage)); + // Try the solid bg-color FIRST. If the element has both a solid color + // and a gradient/url overlay (a common pattern: `background: var(--paper) + // radial-gradient(...)` for paper-grain texture), the solid color is the + // dominant visible surface for contrast purposes; the overlay is + // decorative. The old behavior bailed on any gradient ancestor, which + // caused massive false-positive contrast findings on grain-textured + // body backgrounds. let bg = parseRgb(style.backgroundColor); if (!IS_BROWSER && (!bg || bg.a < 0.1)) { - // jsdom doesn't decompose background shorthand — parse raw style attr - const rawStyle = current.getAttribute?.('style') || ''; - const bgMatch = rawStyle.match(/background(?:-color)?\s*:\s*([^;]+)/i); - const inlineBg = bgMatch ? bgMatch[1].trim() : ''; - // Check for gradient or url() image in inline style too - if (/gradient/i.test(inlineBg) || /url\s*\(/i.test(inlineBg)) return null; - bg = parseRgb(inlineBg); - if (!bg && inlineBg) { - const hexMatch = inlineBg.match(/#([0-9a-f]{6}|[0-9a-f]{3})\b/i); - if (hexMatch) { - const h = hexMatch[1]; - if (h.length === 6) { - bg = { r: parseInt(h.slice(0,2), 16), g: parseInt(h.slice(2,4), 16), b: parseInt(h.slice(4,6), 16), a: 1 }; - } else { - bg = { r: parseInt(h[0]+h[0], 16), g: parseInt(h[1]+h[1], 16), b: parseInt(h[2]+h[2], 16), a: 1 }; - } + // jsdom returns literal "var(--X)" / "oklch(...)" strings. Resolve + // through customPropMap so Tailwind v4 color tokens become RGB. + if (customPropMap) { + bg = parseColorResolved(style.backgroundColor, customPropMap); + } + if (!bg || bg.a < 0.1) { + // Inline-style fallback. jsdom doesn't decompose background + // shorthand, so colors set via inline style are otherwise invisible. + const rawStyle = current.getAttribute?.('style') || ''; + const bgMatch = rawStyle.match(/background(?:-color)?\s*:\s*([^;]+)/i); + const inlineBg = bgMatch ? bgMatch[1].trim() : ''; + if (inlineBg && !/gradient/i.test(inlineBg) && !/url\s*\(/i.test(inlineBg)) { + bg = parseColorResolved(inlineBg, customPropMap) || parseAnyColor(inlineBg); } } } + if (bg && bg.a > 0.1) { if (IS_BROWSER || bg.a >= 0.5) return bg; } + // No solid bg-color at this level. If THIS level has a gradient/url + // with no underlying solid color we can read: + // • on body/html: assume white. Body-level gradients are almost + // always decorative texture (paper grain, noise) on top of a + // solid bg-color the page set via `background: var(--paper)` + // shorthand — which jsdom can't decompose into bg-color. The + // downstream gradient-stops fallback path produces catastrophic + // false positives in this case (gradient noise stops have + // accidental browns/blacks that look like card backgrounds). + // • on other elements: bail to null and let the caller fall back + // to gradient stops (gradient buttons / hero sections are real + // bgs worth checking against). + if (hasGradientOrUrl) { + if (current.tagName === 'BODY' || current.tagName === 'HTML') { + return { r: 255, g: 255, b: 255, a: 1 }; + } + return null; + } current = current.parentElement; } return { r: 255, g: 255, b: 255 }; @@ -1228,9 +1348,245 @@ function checkElementHeroEyebrowDOM(el) { siblingTextTransform: sibStyle.textTransform || '', siblingFontSize: parseFloat(sibStyle.fontSize) || 0, siblingLetterSpacing: parseFloat(sibStyle.letterSpacing) || 0, + siblingFontWeight: sibStyle.fontWeight || '', + siblingColor: sibStyle.color || '', }); } +// Build a map of CSS custom properties declared on :root / :host / html. +// Used to resolve var(--X) refs that jsdom returns verbatim in +// getComputedStyle. Tailwind v4 routes every utility class through +// CSS vars (font-weight: var(--font-weight-bold), font-size: +// var(--text-xs), letter-spacing: var(--tracking-widest)), so without +// resolution every style-based check silently fails on Tailwind v4 +// builds — the values come back as literal "var(--font-weight-bold)" +// strings and parseFloat returns NaN. +function buildCustomPropMap(document) { + const map = new Map(); + let sheets; + try { sheets = Array.from(document.styleSheets || []); } + catch { return map; } + for (const sheet of sheets) { + let rules; + try { rules = Array.from(sheet.cssRules || []); } + catch { continue; } + for (const rule of rules) { + // Style rules only (type 1). Walk @media / @supports if present. + if (rule.type === 4 /* MEDIA_RULE */ || rule.type === 12 /* SUPPORTS_RULE */) { + try { rules.push(...Array.from(rule.cssRules || [])); } catch { /* ignore */ } + continue; + } + if (rule.type !== 1 /* STYLE_RULE */) continue; + const sel = rule.selectorText || ''; + if (!/(^|,\s*)(:root|html|:host)\b/i.test(sel)) continue; + const style = rule.style; + if (!style) continue; + for (let i = 0; i < style.length; i++) { + const prop = style[i]; + if (!prop || !prop.startsWith('--')) continue; + const val = style.getPropertyValue(prop).trim(); + if (val) map.set(prop, val); + } + } + } + return map; +} + +// Resolve var(--X[, fallback]) refs in a computed-style value string. +// Recurses up to 8 levels for chained refs (--a: var(--b)). Returns +// the original string when no refs are present or the chain doesn't +// resolve. Safe to call on already-resolved values. +function resolveVarRefs(raw, customPropMap, depth = 0) { + if (typeof raw !== 'string' || !raw.includes('var(')) return raw; + if (depth > 8) return raw; + return raw.replace(/var\(\s*(--[a-zA-Z0-9_-]+)\s*(?:,\s*([^)]+))?\)/g, (_m, name, fallback) => { + const v = customPropMap.get(name); + if (v != null) return resolveVarRefs(v, customPropMap, depth + 1); + return fallback ? resolveVarRefs(fallback.trim(), customPropMap, depth + 1) : _m; + }); +} + +// OKLCH → sRGB conversion (Björn Ottosson's matrices). L in 0..1 (or %), +// C in 0..~0.4 typical, H in degrees. Returns clamped {r,g,b,a:1} in 0..255. +// Needed because jsdom doesn't compute oklch() values — getComputedStyle +// returns the literal "oklch(...)" string. Without this, the entire +// Tailwind v4 color palette (which is OKLCH-based) is invisible to the +// detector's contrast / color checks. +function oklchToRgb(L, C, H) { + const hRad = (H * Math.PI) / 180; + const a = C * Math.cos(hRad); + const b = C * Math.sin(hRad); + const l_ = L + 0.3963377774 * a + 0.2158037573 * b; + const m_ = L - 0.1055613458 * a - 0.0638541728 * b; + const s_ = L - 0.0894841775 * a - 1.2914855480 * b; + const lc = l_ * l_ * l_, mc = m_ * m_ * m_, sc = s_ * s_ * s_; + const rLin = 4.0767416621 * lc - 3.3077115913 * mc + 0.2309699292 * sc; + const gLin = -1.2684380046 * lc + 2.6097574011 * mc - 0.3413193965 * sc; + const bLin = -0.0041960863 * lc - 0.7034186147 * mc + 1.7076147010 * sc; + const enc = (x) => { + const c = Math.max(0, Math.min(1, x)); + return c <= 0.0031308 ? 12.92 * c : 1.055 * Math.pow(c, 1 / 2.4) - 0.055; + }; + return { + r: Math.round(enc(rLin) * 255), + g: Math.round(enc(gLin) * 255), + b: Math.round(enc(bLin) * 255), + a: 1, + }; +} + +// Extended color parser: rgb/rgba/hex/oklch. Returns null on no match. +// Use this when the input might be any CSS color form; use plain parseRgb +// when you only expect computed rgb() values from real browsers. +function parseAnyColor(s) { + if (!s || typeof s !== 'string') return null; + const str = s.trim(); + if (str === 'transparent' || str === 'currentcolor' || str === 'inherit') return null; + let m; + m = str.match(/rgba?\(\s*(\d+(?:\.\d+)?)\s*,?\s*(\d+(?:\.\d+)?)\s*,?\s*(\d+(?:\.\d+)?)(?:\s*[,/]\s*([\d.]+))?\s*\)/); + if (m) return { r: Math.round(+m[1]), g: Math.round(+m[2]), b: Math.round(+m[3]), a: m[4] !== undefined ? +m[4] : 1 }; + m = str.match(/^#([0-9a-f]{3,8})$/i); + if (m) { + const h = m[1]; + if (h.length === 3 || h.length === 4) { + return { + r: parseInt(h[0] + h[0], 16), + g: parseInt(h[1] + h[1], 16), + b: parseInt(h[2] + h[2], 16), + a: h.length === 4 ? parseInt(h[3] + h[3], 16) / 255 : 1, + }; + } + if (h.length === 6 || h.length === 8) { + return { + r: parseInt(h.slice(0, 2), 16), + g: parseInt(h.slice(2, 4), 16), + b: parseInt(h.slice(4, 6), 16), + a: h.length === 8 ? parseInt(h.slice(6, 8), 16) / 255 : 1, + }; + } + } + // OKLCH parser. Tailwind v4's CSS minifier squishes the space after + // `%` ("21.5%.02 50"), so the separator between L and C may be absent. + // Match L (with optional %), then C and H separated permissively. + m = str.match(/oklch\(\s*([\d.]+)(%?)\s*[\s,]*\s*([\d.]+)\s*[\s,]+\s*([-\d.]+)(?:deg)?\s*\)/i); + if (m) { + const Lnum = parseFloat(m[1]); + const L = m[2] === '%' ? Lnum / 100 : Lnum; + return oklchToRgb(L, parseFloat(m[3]), parseFloat(m[4])); + } + return null; +} + +// Resolve var() refs in a color string (via customPropMap), then parse. +// Returns null on any failure. Used in jsdom-mode paths where +// getComputedStyle returns literal "var(--X)" or "oklch(...)" strings. +function parseColorResolved(str, customPropMap) { + if (!str) return null; + const resolved = customPropMap ? resolveVarRefs(str, customPropMap) : str; + return parseAnyColor(resolved); +} + +const REPEATED_KICKER_SKIP_SELECTOR = [ + 'nav', + 'form', + 'table', + 'thead', + 'tbody', + 'tfoot', + 'figure', + 'figcaption', + 'ol', + 'ul', + 'li', + '[role="navigation"]', + '[aria-label*="breadcrumb" i]', + '[class*="breadcrumb" i]', + '[data-impeccable-allow-kickers]', +].join(','); + +function cleanInlineText(el) { + return [...el.childNodes] + .filter(n => n.nodeType === 3) + .map(n => n.textContent) + .join(' ') + .replace(/\s+/g, ' ') + .trim(); +} + +function isRepeatedKickerCandidate(opts) { + const { + headingTag, + headingText, + headingFontSize, + kickerTag, + kickerText, + kickerTextTransform, + kickerFontSize, + kickerLetterSpacing, + } = opts; + if (!['h2', 'h3', 'h4'].includes(headingTag)) return false; + if (!headingText || headingText.length < 3) return false; + if (!(headingFontSize >= 20)) return false; + if (!kickerTag || HEADING_TAGS.has(kickerTag)) return false; + if (!['p', 'span', 'div', 'small'].includes(kickerTag)) return false; + if (!kickerText || kickerText.length < 2 || kickerText.length > 34) return false; + if (/^step\s*\d+/i.test(kickerText) || /^\d{1,2}$/.test(kickerText)) return false; + + const isUppercased = kickerTextTransform === 'uppercase' + || (/[A-Z]/.test(kickerText) && !/[a-z]/.test(kickerText)); + if (!isUppercased) return false; + if (!(kickerFontSize > 0 && kickerFontSize <= 14)) return false; + const minTrackedSpacing = Math.max(1, kickerFontSize * 0.08); + if (!(kickerLetterSpacing >= minTrackedSpacing)) return false; + return true; +} + +function collectRepeatedSectionKickerCandidates(doc, getStyle, resolveLetterSpacing) { + const candidates = []; + for (const heading of doc.querySelectorAll('h2, h3, h4')) { + if (heading.closest?.(REPEATED_KICKER_SKIP_SELECTOR)) continue; + const kicker = heading.previousElementSibling; + if (!kicker || kicker.closest?.(REPEATED_KICKER_SKIP_SELECTOR)) continue; + + const headingStyle = getStyle(heading); + const kickerStyle = getStyle(kicker); + const headingText = (heading.textContent || '').replace(/\s+/g, ' ').trim(); + const kickerText = cleanInlineText(kicker) || (kicker.textContent || '').replace(/\s+/g, ' ').trim(); + const headingFontSize = resolveLetterSpacing(headingStyle.fontSize || '', 16) || parseFloat(headingStyle.fontSize) || 0; + const kickerFontSize = resolveLetterSpacing(kickerStyle.fontSize || '', 16) || parseFloat(kickerStyle.fontSize) || 0; + const kickerLetterSpacing = resolveLetterSpacing(kickerStyle.letterSpacing || '', kickerFontSize); + + if (!isRepeatedKickerCandidate({ + headingTag: heading.tagName.toLowerCase(), + headingText, + headingFontSize, + kickerTag: kicker.tagName.toLowerCase(), + kickerText, + kickerTextTransform: kickerStyle.textTransform || '', + kickerFontSize, + kickerLetterSpacing, + })) { + continue; + } + + candidates.push({ + headingTag: heading.tagName.toLowerCase(), + headingText: headingText.replace(/^"|"$/g, '').slice(0, 60), + kickerText: kickerText.slice(0, 40), + }); + } + return candidates; +} + +function checkRepeatedSectionKickersDOM() { + const candidates = collectRepeatedSectionKickerCandidates( + document, + (el) => getComputedStyle(el), + (value, fontSize) => resolveLengthPx(value, fontSize) || 0, + ); + return checkRepeatedSectionKickers({ candidates }); +} + function checkElementMotionDOM(el) { const tag = el.tagName.toLowerCase(); if (SAFE_TAGS.has(tag)) return []; @@ -1381,7 +1737,7 @@ function resolveLengthPx(value, fontSizePx) { // Both adapters resolve font-size, line-height and letter-spacing to pixels // before calling this so the pure function only deals with numbers. function checkQuality(opts) { - const { el, tag, style, hasDirectText, textLen, fontSize, lineHeightPx, letterSpacingPx, rect, lineMax = 80 } = opts; + const { el, tag, style, hasDirectText, textLen, fontSize, lineHeightPx, letterSpacingPx, rect, lineMax = 80, viewportWidth = 0 } = opts; const findings = []; // Skip browser extension injected elements const elId = el.id || ''; @@ -1432,6 +1788,40 @@ function checkQuality(opts) { } } + // --- Body text touching viewport edge --- (browser-only: needs rect) + // Catches the failure mode where the agent ships body paragraphs + // with NO container providing horizontal padding — text bleeds + // directly to the viewport edge. Different from cramped-padding, + // which requires a colored/bordered container. Here the failure + // is the absence of the container entirely. + // + // Gate aggressively to avoid false positives: + // -

or

  • only (body content; not headings, not nav, not + // wrappers) + // - text > 40 chars (paragraph-like, not a label) + // - rect.width > 50% of viewport (real body, not a pull-quote) + // - rect.left < 16 OR rect.right > viewport - 16 (actually + // touching the edge) + // - not inside