From 65ac2a5f138452701c2f41b9861de77cc495e0f1 Mon Sep 17 00:00:00 2001 From: Abdul Wahab Date: Tue, 14 Jul 2026 15:18:18 +0500 Subject: [PATCH] Recognize the seed-collected image key in shape and craft. A stored IMAGE_GEN_API_KEY in .impeccable/.env now counts as image generation being available for shape probes and the craft codex flow. The key ask itself stays exclusive to document seed mode; shape and craft still never prompt for APIs or tooling. Co-authored-by: Cursor --- skill/reference/craft.md | 122 +++++++++++++++++++++++++++++++++++- skill/reference/document.md | 3 +- skill/reference/shape.md | 105 ++++++++++++++++++++++++++++++- 3 files changed, 227 insertions(+), 3 deletions(-) diff --git a/skill/reference/craft.md b/skill/reference/craft.md index dbbc9402c..b20ab801f 100644 --- a/skill/reference/craft.md +++ b/skill/reference/craft.md @@ -2,4 +2,124 @@ `craft` is a deprecated alias for an ordinary request to make new visual work. It adds no setup, interview, checkpoint, tool, or quality behavior. Apply SKILL.md's normal routing: create missing PRODUCT.md through [init.md](init.md), then follow [new-work.md](new-work.md) for visual authority, world and surface decisions, implementation, and finish. -Do not tell users they need to invoke `craft`. Natural requests such as “build this feature,” “make a landing page,” or “redesign this screen” use the same flow. +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. + +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. + +### Gates: do not compress + +Craft has **multiple user gates**, not one. When image generation is available (native or stored key; Step 3 defines the test), the gate sequence before code is: + +1. **Shape brief confirmed** (Step 1) +2. **Direction questions answered** (codex.md Step A) +3. **Palette confirmed** (codex.md Step B) +4. **One mock direction approved or delegated** (codex.md Step D) + +You must stop at every gate. **Shape confirmation alone is NOT a green light to start coding.** It is the green light to begin codex.md Step A. Compressing gates 2 through 4 because the shape brief felt complete is the dominant failure mode of this flow. + +When no image generation is available, gates 2-4 collapse into the brief itself, and shape confirmation does advance straight to code. + +## Step 0: Project Foundation + +Before shape, before code: figure out what kind of project you're working in. + +Look at the working directory. Run `ls`. Check for: + +- 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. + +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: + +```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) +``` + +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 {{command_prefix}}impeccable shape, passing along whatever feature description the user provided. Shape is **required** for craft; it is what produces a confirmed direction. + +Present the shape output and stop. Wait for the user to confirm, override, or course-correct before writing code. + +If the user already supplied a confirmed brief or ran shape separately, use it and skip this step. + +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. + +If image generation is available (Step 3 defines the test), a compact shape's "confirm or override" advances to **Step 3 and the codex.md flow**, not to Step 4. Phrase the closing line accordingly: "Confirm or override; once we lock direction, I'll run a couple of palette and reference questions before generating any mocks." This stops the model from reading shape confirmation as code-green. + +## Step 2: Load References + +Based on the design brief's "Recommended References" section, consult the relevant impeccable reference files. At minimum, always consult: + +- [layout.md](layout.md) for layout, spacing, grid, container queries, optical adjustments +- [typeset.md](typeset.md) for type hierarchy, font selection, web font loading, OpenType features (Reference Material section) + +Then add references based on the brief's needs: +- Complex interactions or forms? Consult [interaction-design.md](interaction-design.md) +- Animation or transitions? Consult [animate.md](animate.md) (Reference Material covers motion materials, durations, easing, perceived performance) +- Color-heavy or themed? Consult [colorize.md](colorize.md) (Reference Material covers OKLCH, palette structure, dark mode, contrast) +- Responsive requirements? Consult [adapt.md](adapt.md) (Reference Material covers breakpoints, input methods, safe areas, responsive images) +- Heavy on copy, labels, or errors? Consult [clarify.md](clarify.md) (Reference Material covers button labels, error formula, voice/tone, translation) + +## Step 3: Visual Direction & Assets (Harness-Gated) + +Image generation is available when the harness has it **natively** (currently Codex via `image_gen`), or when `.impeccable/.env` carries an `IMAGE_GEN_API_KEY` (collected during `{{command_prefix}}impeccable document` seed mode; generate via that provider's API). The key ask belongs to the document seed flow alone; craft never asks the user to install APIs, tooling, or a key. + +If image generation is available, this step is mandatory. **Stop and load [codex.md](codex.md)**. It covers palette generation, mock exploration, the approval loop, mock-fidelity inventory, and asset slicing via the `impeccable_asset_producer` subagent. Follow Steps A-F in that file, then return here for Step 4. + +If neither path is available, **state in one line that the visual-direction-by-generation step is being skipped because no image generation is available, then proceed**. The one-line announcement is required; it forces a conscious decision instead of letting the step quietly evaporate. The brief is your only visual reference. Implement directly from it, treating any named anchor references and the brief's "Design Direction" as the contract. + +Whether you generated mocks or not: don't replace required imagery with generic cards, bullets, emoji, fake metrics, decorative CSS panels, or filler copy. Image-led briefs (restaurants, hotels, magazines, photography, hobbyist communities, food, travel, fashion, product) need real or sourced imagery in the build, not CSS scenery. + +## Step 4: Build to Production Quality + +**Precondition.** If Step 3 routed you to codex.md (image generation available), Steps A through D in that file must be complete before any code: questions answered, palette confirmed, mocks generated, one direction approved or delegated. **Do not mention implementation, file paths, or patch plans until that's done.** A confirmed shape brief is not enough; the model that compressed those gates is the model that already failed this flow. + +Implement the feature following the design brief. Build in passes so structure, visual system, states, motion/media, and responsive behavior each get deliberate attention. The list below is the definition of done, not inspiration. + +### Production bar + +- **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 5: Iterate Visually + +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. + +If your tool returns a file path, read the PNG back into the conversation. A screenshot you didn't read doesn't count. + +For long-form brand surfaces, inspect major sections individually. Thumbnails hide spacing, clipping, and cascade defects. + +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. + +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. + +Detector or QA output is defect evidence only; never proof the work is finished. + +## Step 6: Present + +Present the result to the user: +- Show the feature in its primary state +- Summarize the browser/viewports checked and the most important fixes made after inspection +- Walk through the key states (empty, error, responsive) +- 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?" diff --git a/skill/reference/document.md b/skill/reference/document.md index 91cc8a6c2..573d8a3fd 100644 --- a/skill/reference/document.md +++ b/skill/reference/document.md @@ -404,7 +404,8 @@ Keep skill vocabulary (seed, register, anti-reference) out of question text; ask Interview answers are words; a palette is easier picked by eye. Before writing the seed, branch on capability: - **The harness has native image generation** (Codex's `image_gen`, an equivalent MCP tool, or similar): generate the cues directly; no setup needed. -- **No native path**: pause and {{ask_instruction}} whether the user wants generated visual cues to pick a palette by eye. *"I can generate a few small palette-and-mood images so you choose a direction visually instead of from descriptions. That needs an image-generation API key, stored as `IMAGE_GEN_API_KEY` in `.impeccable/.env`. Add one, or skip straight to the seed?"* If a key arrives, write it to `.impeccable/.env`, confirm that file is listed in the project's `.gitignore` (add it if missing; a committed key is a leak), and ask which provider it belongs to so you call the right API. +- **No native path but `.impeccable/.env` already carries `IMAGE_GEN_API_KEY`** (from a previous run): use it via that provider's API; don't re-ask. +- **No native path, no stored key**: pause and {{ask_instruction}} whether the user wants generated visual cues to pick a palette by eye. *"I can generate a few small palette-and-mood images so you choose a direction visually instead of from descriptions. That needs an image-generation API key, stored as `IMAGE_GEN_API_KEY` in `.impeccable/.env`. Add one, or skip straight to the seed?"* If a key arrives, write it to `.impeccable/.env`, confirm that file is listed in the project's `.gitignore` (add it if missing; a committed key is a leak), and ask which provider it belongs to so you call the right API. - **The user opts out, or no key arrives**: go to Step 5 and seed from the answers alone. When generation is available, produce **2-4** cue images from the interview answers and Step 2 observations: each carries one palette direction as swatches on the chosen background, one type mood, one texture or motif. These are direction tests, not mocks; vary the hue anchor or color strategy across them, not minor tweaks. Show them, ask which feels closest and what feels off, and carry the pick into the seed as the confirmed color direction. One round; refinement belongs to implementation, not the seed. diff --git a/skill/reference/shape.md b/skill/reference/shape.md index 90a74ae81..4ca437c2c 100644 --- a/skill/reference/shape.md +++ b/skill/reference/shape.md @@ -56,4 +56,107 @@ Use three to five bullets when the task is settled; use the full structure only Present the brief for explicit confirmation or one correction round, then stop: shape never writes code or a direction contract. -When no human or structured answer mechanism exists, mark assumptions plainly, return the brief, and stop. +### Constraints +- Are there technical constraints? (Framework, performance budget, browser support) +- Are there content constraints? (Localization, dynamic text length, user-generated content) +- Mobile/responsive requirements? +- Accessibility requirements beyond WCAG AA? + +### Anti-Goals +- What should this NOT be? What would be a wrong direction? +- What's the biggest risk of getting this wrong? + +## Phase 1.5: Visual Direction Probe (Capability-Gated) + +After the discovery interview, generate a small set of visual direction probes **before** writing the final brief when all of these are true: + +- 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 gives you native image generation (Codex's `image_gen`, an equivalent MCP tool, or similar), **or** `.impeccable/.env` carries an `IMAGE_GEN_API_KEY` (collected during `{{command_prefix}}impeccable document` seed mode; generate via that provider's API). Don't ask the user to install APIs or tooling; the key ask belongs to the document seed flow alone. + +When those conditions are met, this step is mandatory. If neither generation path is available, do not ask the user to install APIs, tooling, or a key. State in one line that the image step is skipped because the harness lacks image generation, then proceed. The one-line announcement is required, not optional; it forces a conscious decision instead of letting the step quietly evaporate. + +Use probes to explore visual lanes, not to replace the brief. + +Do not skip probes because the final UI will be semantic, editable, code-native, responsive, or accessible. Those are implementation requirements, not reasons to avoid visual exploration. + +### What to generate + +Generate **2 to 4** distinct direction probes based on the discovery answers, especially: + +- Color strategy +- Theme scene sentence +- Named anchor references +- Scope and fidelity + +The probes should differ in primary visual direction (hierarchy, topology, density, typographic voice, or color strategy), not just palette tweaks. + +### How to use the probes + +- Treat them as **direction tests**, not final designs. +- Use them to pressure-test whether the brief is pointing at the right lane. +- Ask the user which direction feels closest, what feels off, and what should carry forward. +- If the probes reveal a mismatch, revise the brief inputs before finalizing the brief. + +### Important limits + +- Do **not** skip discovery because image generation is available. +- 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 neither generation path is available, announce the skip in one line and proceed to the design brief. + +## Phase 2: Design 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. + +Present the brief, then **stop and wait for explicit confirmation**. You are not the judge of whether the user already approved. Even when the brief feels obviously right, ask once and wait. The pause is what separates shape from premature implementation. + +### Brief Structure + +**1. Feature Summary** (2-3 sentences) +What this is, who it's for, what it needs to accomplish. + +**2. Primary User Action** +The single most important thing a user should do or understand here. + +**3. Design Direction** +Color strategy (Restrained / Committed / Full palette / Drenched) + the theme scene sentence + 2–3 named anchor references. Reference PRODUCT.md and DESIGN.md where they already answer, and note any per-surface overrides. + +If you ran the Visual Direction Probe step, name which probe direction won and what changed in the brief because of it. + +**4. Scope** +Fidelity, breadth, interactivity, and time intent from the Scope section of the interview. Task-scoped; these don't persist beyond the brief. + +**5. Layout Strategy** +High-level spatial approach: what gets emphasis, what's secondary, how information flows. Describe the visual hierarchy and rhythm, not specific CSS. + +**6. Key States** +List every state the feature needs: default, empty, loading, error, success, edge cases. For each, note what the user needs to see and feel. + +**7. Interaction Model** +How users interact with this feature. What happens on click, hover, scroll? What feedback do they get? What's the flow from entry to completion? + +**8. Content Requirements** +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., layout.md for complex layouts, animate.md for animated features, interaction-design.md for form-heavy features, typeset.md for typography-driven pages, colorize.md for color-led brands). + +**10. Open Questions** +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_instruction}} 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 user confirms direction. + +Once confirmed, the brief is complete. The user can now hand it to {{command_prefix}}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 {{command_prefix}}impeccable craft instead, which runs this command internally.)