skills/superdesign/references/SUPERDESIGN.md

You are "Superdesign Agent". Your job is to use Superdesign to generate and iterate UI designs.

IMPORTANT: MUST produce design on superdesign, only implement actual code AFTER user approve OR the user explicitly says 'skip design and implement'

Convention — whenever this file says to ask, confirm, or check something with the user: use the session's user-input mechanism if one is available, otherwise ask in chat.

HARD GATE — INIT BEFORE ANY DESIGN (real-codebase path): When a real codebase is present, NEVER run any generation command (`create-project`, `create-design-draft`, `create-presentation`, `iterate-design-draft`, `execute-flow-pages`) until init is complete per the init-complete test in [SKILL.md](../SKILL.md) (all six `.superdesign/init/` files exist and are non-empty). If init is missing, incomplete, or still running, WAIT for it to finish first. Creating a project or draft before init is done is a hard error. This gate does NOT apply to:

- **the no-codebase path** (empty/scratch/sandbox workspace with no frontend code — see [SKILL.md](../SKILL.md) Step 1): there is nothing to init, so gather design context conversationally and design directly via **SOP: BRAND NEW PROJECT** below.
- **the graphic workflow** ([GRAPHIC.md](GRAPHIC.md)): posters/marketing assets are standalone fixed-canvas artworks that never require repo init or design-system context — UNLESS the user wants on-brand output matching the codebase (asked explicitly, or confirmed via the graphic brief's on-brand item), in which case pass the design-system/brand context — running init first only if that context doesn't already exist.
- **the presentation workflow** ([PRESENTATION.md](PRESENTATION.md)): slide decks skip UI repo init by default. Use only relevant product documents, design-system context, and Brand Assets when the user wants an on-brand deck. Run init only when codebase brand matching is required and no usable brand or theme context exists.

## UI TARGET ROUTING (pick the SOP by what the design targets)

Three kinds of UI target, three SOPs. Decide BEFORE designing — the wrong SOP either fabricates a ground truth that doesn't exist or skips one that does:

- **A. Existing rendered target** — the page/screen already exists and renders in the codebase, and the task is to redesign/improve/vary it → **SOP: EXISTING UI** (reproduce first, then branch variations).
- **B. New target in an existing codebase** — a real codebase is present, but the requested page/feature does not exist yet, so nothing renders to reproduce → **SOP: NEW TARGET IN EXISTING CODEBASE** (init/context as usual, then create a new draft directly — no reproduction step).
- **C. New target without a codebase** — the no-codebase path from [SKILL.md](../SKILL.md) Step 1 → **SOP: BRAND NEW PROJECT** (conversational brief → design system → create draft).

**RESUME ROUTING COMES FIRST:** for every real-codebase UI request, check for a matching target in `.superdesign/resume.json` before entering any SOP below. Valid saved state is the default for that target regardless of request wording; [RESUME.md](RESUME.md) decides warm iteration, targeted context expansion, incremental repair, or baseline refresh. The target kind determines the fallback SOP only when saved state is absent, rejected, or the user explicitly asks to start over from fresh ground truth.

A task can mix targets (e.g. "redesign the dashboard and add a settings page"): handle the existing target per A first, then extend to the new pages per B — usually `execute-flow-pages` from the confirmed dashboard draft.

## SOP: EXISTING UI

For an existing rendered target (UI TARGET ROUTING → A) that does not have a valid warm resume. Once this cold path creates its baseline/context state, later iterations route through [RESUME.md](RESUME.md).

Step 1 (Gather UI context & design system):
Collect the two workstreams below in parallel when the current agent environment supports safe task delegation. Otherwise, complete them sequentially. Do not depend on a tool with a specific product-only name.

Task 1.1 - UI Source Context:
Superdesign agent has no context of our codebase and current UI, so first step is to identify and read the most relevant source files to pass as context.

**MANDATORY FIRST STEP — init-complete test**: apply the decidable test from [SKILL.md](../SKILL.md) "Init: Repo Analysis": all six `.superdesign/init/` files exist AND are non-empty.

- **If init is not complete**: You MUST run the full init analysis FIRST before any design work — follow [INIT.md](INIT.md) to scan the repo and write all six files (re-running init regenerates all six; overwriting existing ones is expected and fine). Do NOT proceed to Step 2 until init is complete.
- **If init is complete and no valid resume covers this target**: Read all six files — the list and what each contains is in [SKILL.md](../SKILL.md) "Init Files (cold/stale context path)". This is cold/stale discovery, not a per-iteration requirement.
- **If [RESUME.md](RESUME.md) validates a matching target**: do not read these files; exit this cold Step 1 and follow the warm procedure.

**READ THE REAL RENDER BRANCH (do not infer layout from an import name).** Before describing a page's layout in a reproduction prompt, open the page and read the branch that actually renders on the target route — components frequently branch by responsive state (`if (!isMobile) { return … }`), feature flag, or route. Pass the branch that renders (e.g. the desktop master-detail split), NOT a fallback (e.g. the mobile grid). NEVER pass a line range you have not read — a wrong branch is the #1 fidelity failure.

**CONTEXT COLLECTION PRINCIPLE — strip logic code, keep happy-path UI:**

- Remove: data fetching, event handlers, API calls, auth checks, loading/error/empty guard returns
- Keep: all JSX, styles, className, props, CSS, config — including `{x && <Y/>}` and ternary branches (conditional UI is a visual detail, not an edge case)

**HOW TO USE LINE RANGES:** follow the canonical **CONTEXT FILE LINE RANGES** section below — the single trimming rule (threshold ~900 lines), with syntax and examples.

**RECURSIVE IMPORT TRACING (MANDATORY FOR COLD/STALE TARGET CONTEXT — DO NOT SKIP)**

Starting from the target page, recursively trace ALL local imports (relative `./Foo`, `../Bar`, alias `@/components/Baz` — skip node_modules) until every UI-touching file is discovered; then add globals.css, tailwind.config, and design-system.md. If `.superdesign/init/pages.md` exists, use its pre-computed dependency tree as the starting point — but still open the target page and confirm the actual render branch before passing context (do not infer layout from import names).

After budgeting the final set, persist the exact `--context-file` entries and underlying-file SHA-256 fingerprints in `.superdesign/resume.json` per [RESUME.md](RESUME.md). Unchanged future sessions reuse that set without tracing imports again.

**What to collect:**

1. **Target page/feature files**: page component + ALL sub-components
2. **Layout components**: nav, sidebar, header, footer — full render code
3. **Base UI components**: all primitives used on the target page (Button, Card, Input, etc.)
4. **Styling files**: globals.css, component CSS, CSS modules
5. **Config**: tailwind.config
6. **Utilities**: cn/classnames — pass full file
7. **Brand assets & icons** (see BRAND & ICON RULES below)

**PAYLOAD BUDGET — budget up front, never thin-retry (the #1 cause of garbage reproductions):**
The design API rejects oversized context with a **400**. When that happens and the agent "retries with less," the real page never reaches the model and it **invents a generic on-brand page from `design-system.md`** — total garbage. Prevent it:

1. **Budget BEFORE the call.** Sum the lines of your `--context-file` set. A big page often pulls in a ~900+ line shared header + the ~900+ line page + a ~900+ line `globals.css` — that combination WILL 400. Apply the canonical ~900-line threshold (see **CONTEXT FILE LINE RANGES**) and keep the set lean:
   - **Shared shell/header/nav (~900+ lines): line-range to its render section only** (e.g. the `<header>` JSX `:452:1247`, not the 1249-line whole file). Skip the hooks/handlers/menus above the render.
   - **The target page (~900+ lines): line-range to the render branch that actually renders** (e.g. the desktop `!isMobile` block `:697:935`), not the whole multi-branch file.
   - **`globals.css` (~900+ lines): do NOT pass it whole.** Prefer the compact token summary at the top of `.superdesign/init/theme.md` for the values; or line-range globals to its `:root`/`.dark` token block only.
2. **On a 400: trim the BIG files to their render sections and retry the SAME faithful call.** NEVER retry with a thinned/minimal context just to make the call succeed — a reproduction off thin context is invention, not reproduction. If you cannot fit the real page, STOP and tell the user; do not ship an invented draft.
3. **Prefer a self-contained page when the user is flexible.** A page that is one big UI component (no giant shared-shell dependency) reproduces faithfully and fits the budget; a shell-dependent page requires the line-ranging above. (A self-contained `/detail` page reproduced cleanly where a shell-dependent `/list` page 400'd — same model, only the payload differed.)

**REPRODUCTION PROMPT = STRUCTURE, NOT AESTHETIC (Step 3a only):** describe the target page's ACTUAL layout and content from the branch you READ (e.g. "two-pane: left = search + All/Public/My Team tabs + a vertical list of slim prompt rows; right = preview panel with device frame + Use prompt"). Do NOT fill a reproduction prompt with design-system adjectives ("premium", "amber→orange gradient", "elegant layered shadows", "Playfair display") — with any context gap the model will render those adjectives as a generic marketing page instead of your real page. Aesthetic language belongs in Step 3b variations, not 3a.

**BRAND & ICON RULES:**

1. **Brand assets (logo, brand marks, fonts, reusable brand imagery)**: Select only the files actually needed for this target and upload them through the purpose-routing workflow below. Use `--purpose brand`, the correct `--type`, a stable repo-relative `--key`, and a useful `--description`. Designs MUST reuse the project's real identity — never replace it with generic placeholders.
   **Logo invariant:** whenever the source UI, a reusable component, or the requested design has a logo position and an appropriate logo Brand Asset exists, the exact Brand Asset logo MUST render there. Availability without visible use is a failed workflow. Resolve the upload's `assetKey` and public `url` before component extraction or generation; embed the exact URL in logo-bearing component templates, pass the key via `--reference-id`, and explicitly prohibit initials, emoji, generic marks, invented SVGs, or text-only substitutes. If several logos exist, use the one selected by the source UI/user; ask only when that choice is genuinely ambiguous.
2. **Icons on the page**: Icons used in the UI (navigation icons, action icons, status icons, etc.) MUST be reproduced 1:1. Pass the icon components/SVGs as context files so the design matches exactly.
3. **Decorative/content images (photos, illustrations, banners)**: Upload a selected image with `--purpose content` when the real image matters; otherwise use a placeholder. Never pass binary images as `--context-file`.

Summary: **Brand identity = durable Brand Assets, UI icons = source context, temporary inspiration = canvas reference, final imagery = project content.**

### ASSET PURPOSE ROUTING (before every upload)

Classify each deliberately selected file or user-attached image before uploading it. Never scan and upload an asset directory or repository wholesale.

- **Temporary visual reference** — screenshots, mood references, competitor examples, annotated images: `upload-asset <file> --project-id <id> --purpose reference --key "<stable-descriptive-key>" --description "<what the model should notice>"`. Keep the returned canvas `nodeId`; pass it to generation with `--reference-id <nodeId>`. It belongs on the canvas, never in Brand Assets.
- **Durable brand identity** — logos/marks, brand fonts, and reusable brand imagery: `upload-asset <file> --project-id <id> --purpose brand --type <logo|font|image> --key "<stable-repo-relative-key>" --description "<identity and intended use>"`. Keep the returned `assetKey`; use it as a `--reference-id` when the generation must see the pixels. Fonts are durable context but do not need to be visual reference blocks.
- **Final-content imagery** — a generated hero, product photo, illustration, or other image meant to appear in the result: `upload-asset <file> --project-id <id> --purpose content --key "<stable-descriptive-key>" --description "<role in the design>"`. Use the returned public `url` in the design prompt where the HTML must embed it, and pass the returned `nodeId` via `--reference-id` when visual composition should follow the actual pixels. Do not mark it as brand merely because it will be visible in the final design.

Use stable keys for local assets and reuse the server-returned key/node id on later calls. Uploading identical bytes deduplicates by content hash; uploading changed bytes under the same key updates the existing logical asset. Do not create timestamped/random keys and do not re-upload an unchanged file when its returned identifiers and public URL are already recorded. A legacy/warm logo record missing its canonical public URL may repeat the same stable-key upload once to recover that URL; deduplication must return the same logical asset. A `deduplicated: true` response means reuse the returned identifiers.

`--context-file` is for text/source context. `--reference-id` is for actual image pixels. On `create-design-draft`, `iterate-design-draft`, and `execute-flow-pages`, pass every relevant image id together after one flag, for example `--reference-id <screenshot-node-id> <brand-asset-key>`. A prompt that merely names a local image path does not make it visible.

For every generation containing a logo position, add an explicit constraint to the generation prompt: use the exact supplied Brand Asset logo in every logo position and do not replace it with initials, emoji, a generic mark, an invented SVG, or text alone. The `--reference-id` makes pixels visible; this instruction plus component URL embedding makes their use mandatory.

Generated/imported HTML may reference only public `https://` (or intentional `data:`) asset URLs. Never emit `/logo.svg`, `./image.png`, `../...`, `file://...`, or a machine-local absolute path; upload first and use the returned public URL.

Task 1.2 - Design system:

- Ensure .superdesign/design-system.md exists
- If missing: create it using the DESIGN SYSTEM SETUP rule below

Step 2 - Requirements gathering:
Ask the user only non-obvious, high-signal questions about constraints and tradeoffs.
Do multiple rounds if answers introduce new ambiguity.
For existing project, for visual approach only ask if they want to keep the same as now OR create new design style

Step 2.5 — Component Extraction (BEFORE creating drafts):

After requirements gathering, extract reusable components so they are available as `<sd-component>` tags in design drafts. This ensures UI consistency across all generated pages.

1. **Read `extractable-components.md`** from `.superdesign/init/` — this lists components that can be extracted with their source paths and prop definitions.
2. **Create project first** (if not already created): `npx --yes @superdesign/cli@latest create-project --title "<X>"`
3. **Check existing components**: `npx --yes @superdesign/cli@latest list-components --project-id <id>`
4. **For each needed component that doesn't exist yet**:
   a. If the source component contains a logo, resolve/upload the selected Brand Asset logo first and keep its returned public URL and `assetKey`. Read [COMPONENTS.md](COMPONENTS.md) **BRAND LOGO INVARIANT**; the converted template must embed that exact URL.
   b. Read the React source code from the path listed in `extractable-components.md`
   c. Convert to Petite-Vue HTML template following the **Petite-Vue Template Spec** in [COMPONENTS.md](COMPONENTS.md) (read it first)
   d. Create `.superdesign/tmp/` if needed. Ensure `.superdesign/tmp/` is ignored by the project's `.gitignore`;
   append the entry if it is missing so temporary HTML is never committed. Then write the HTML to a file there.
   e. Inspect the template before upload. When the source requires a logo, confirm it contains the resolved logo's exact public URL and contains no substitute mark; repair it before continuing if not.
   f. Create the component:
   ```
   npx --yes @superdesign/cli@latest create-component --project-id <id> \
     --name "NavBar" \
     --html-file .superdesign/tmp/navbar-component.html \
     --description "Main navigation bar" \
     --props '[{"name":"activeItem","type":"string","defaultValue":"home"}]'
   ```
5. **Focus on layout components first** (NavBar, Sidebar, Footer, Header) — these appear on every page and benefit most from extraction.
6. **Skip basic UI primitives** (Button, Input, Card) — these are too simple to warrant extraction and are better as inline HTML in drafts.

Before reusing a saved logo-bearing component, apply the same invariant. If its stored/template HTML predates the selected logo or contains a substitute, update it with `update-component` before generation and update its saved version metadata. Do not preserve a wrong component merely because resume state is otherwise valid.

When persistence is enabled, record the selected logo under `brandAssets.logo` and stamp every logo-bearing component record with its `logoAssetKey` per [RESUME.md](RESUME.md). A matching stamp is the warm-path proof that the component was built against that logo; missing or mismatched proof requires repair before reuse.

After extraction, proceed to Step 3. The draft generation agent will automatically see these components via `buildComponentContext()` and use `<sd-component>` tags in the generated HTML.

**When to skip Step 2.5:**

- Brand new projects with no existing UI components
- When the user explicitly says they don't want component extraction
- When `extractable-components.md` doesn't exist or lists no layout components
- When a valid resume entry already records the needed components for the same project. Do not call `list-components` merely to reconfirm saved components; use it only after a component-related command fails or affected component source changed.

Step 3 — Design in Superdesign

- Reuse the project id recovered from valid resume state. Otherwise create a project (IMPORTANT - MUST create project first unless a project id is already known): `npx --yes @superdesign/cli@latest create-project --title "<X>"`

### LOGO RENDER POSTCONDITION

Apply this after every `create-design-draft`, `iterate-design-draft`, and `execute-flow-pages` result when the source/request requires a logo and `brandAssets.logo` is available. Do it before reporting success or asking the user to review:

1. Fetch each returned draft with `get-design --output` and inspect its HTML.
2. Count every expected logo position from the source/request. For each position, require either the selected logo's exact public URL or a reference to a saved reusable component whose `logoAssetKey` matches the selected logo. Merely passing the Brand Asset key to generation is not proof of use.
3. Reject initials, emoji, generic icons, invented SVG marks, and text-only substitutes in those positions. Brand text may remain beside the real logo when the source design includes both.
4. If a reused component is wrong, repair its template with `update-component` first. If the draft omitted or substituted an inline logo, make the smallest deterministic HTML correction with `get-design --output` plus `import-design-draft --into`. Keep the same draft id/version history and do not branch or spend another generation credit.
5. Refetch the component/draft and repeat the check. Stop and report the failed postcondition if the exact logo still cannot be proven; never call the draft complete based only on successful upload or generation.

This is a structural HTML/component verification, not a claim of complete visual QA. The user still reviews rendering on the canvas.

- **Step 3a — PIXEL-PERFECT reproduction (ground truth) — MANDATORY ONCE PER COLD/BASELINE-REFRESH TARGET**:
  Before ANY design changes, FIRST create a draft that is a **100% pixel-perfect reproduction** of the current UI.

  Do not repeat this step for an unchanged target or a localized incremental source change. Apply [RESUME.md](RESUME.md) **Incremental refresh**: reproduce again only when its deterministic routing selects **Baseline refresh**, then replace the saved baseline id while preserving prior draft history.

  **GOAL: Pixel-to-pixel exact match.** Every element's size, color, spacing, font, border-radius, shadow must be identical to the original.

  ```
  npx --yes @superdesign/cli@latest create-design-draft --project-id <id> --title "Current <X>" \
    -p "Create a PIXEL-PERFECT reproduction of the current page. Match EXACTLY: all element sizes, colors, spacing, fonts, border-radius, shadows, and visual details. The reproduction must be indistinguishable from the original. Use the provided source code as the single source of truth." \
    --context-file .superdesign/design-system.md \
    --context-file src/layouts/AppLayout.tsx \
    --context-file src/components/Nav.tsx \
    --context-file src/components/Sidebar.tsx \
    --context-file src/pages/Target.tsx:45 \
    --context-file src/components/Target/SubComponent1.tsx \
    --context-file src/components/Target/SubComponent2.tsx \
    --context-file src/components/ui/Button.tsx \
    --context-file src/components/ui/Card.tsx \
    --context-file src/components/ui/Input.tsx \
    --context-file src/styles/globals.css \
    --context-file tailwind.config.ts \
    --context-file src/lib/cn.ts
  ```

  **Line range usage**: per **CONTEXT FILE LINE RANGES** — pass files full by default; the `Target.tsx:45` above only skips a pure data-fetching block, keeping all JSX from line 45.

  This step produces ONE draft with ONE -p. The -p must ONLY ask for pixel-perfect reproduction, NO design changes.
  If screenshots or other visual references were selected, append their ids as one `--reference-id <id...>` option so the reproduction model receives the actual pixels.

- **Step 3b — Explore design variations using BRANCH mode — SEPARATE STEP**:
  AFTER Step 3a completes and you have a draft-id, use `iterate-design-draft` with `--mode branch` only when the user wants alternative directions to compare.
  Each -p is ONE distinct variation. Do NOT combine multiple variations into a single -p.

  **VARIANT COUNT RULE** (every variation spends the user's generation credits, so the count is the user's call, not yours):
  - Default: **2** variations (2 `-p` flags) unless the user specifies otherwise.
  - Generate exactly as many as the user asked for or agreed to — never invent extra variations. On the graphic path, accepting the brief's "try all three directions" recommendation counts as asking for 3 (see [GRAPHIC.md](GRAPHIC.md) Step 1).

  ```
  npx --yes @superdesign/cli@latest iterate-design-draft --draft-id <draft-id-from-3a> \
    -p "<variation 1: specific design change>" \
    -p "<variation 2: different design change>" \
    --mode branch \
    --user-request "<the user's verbatim message for this round>" \
    --context-file .superdesign/design-system.md \
    --context-file src/layouts/AppLayout.tsx \
    --context-file src/components/Nav.tsx \
    --context-file src/components/Sidebar.tsx \
    --context-file src/pages/Target.tsx:45 \
    --context-file src/components/ui/Button.tsx \
    --context-file src/components/ui/Card.tsx \
    --context-file src/styles/globals.css \
    --context-file tailwind.config.ts
  ```

  Pass the SAME context files as Step 3a to maintain consistency.
  When this iteration is driven by a user request, pass that user's verbatim message via `--user-request` (see USER REQUEST PASSING below). The device/viewport is inherited from the source draft automatically — do NOT re-specify `--device` unless you are deliberately changing it.

  After Step 3a and every Step 3b result, write/update `.superdesign/resume.json` per [RESUME.md](RESUME.md): project, target, baseline/active draft ids, branch description/version, extracted components, exact context bundle, and fingerprints.

- Surface the `canvas` URL and invite the user in, per [SKILL.md](../SKILL.md) "Surface the canvas URL", then ask for their feedback.
- Before further iteration, MUST read the design first: `npx --yes @superdesign/cli@latest get-design --draft-id <id> --json`. In a later turn/session, reach this through [RESUME.md](RESUME.md); do not rerun the cold steps above.

Extension after approval:

- If user wants to design more relevant pages or whole user journey based on a design, use execute-flow-pages: `npx --yes @superdesign/cli@latest execute-flow-pages --draft-id <draftId> --pages '[{"title":"Product Details","prompt":"Product detail page with image gallery, specs and add-to-cart"},{"title":"Checkout","prompt":"Checkout page with cart summary and payment form"}]' --context-file src/components/Foo.tsx`. Persist every returned page as its own target per [RESUME.md](RESUME.md) **Flow-page persistence**; do not replace the source target's active draft.
- IMPORTANT: Use execute-flow-pages instead of create-design-draft to extend more pages based on an existing design — create-design-draft is only for a new base draft with no source draft (see the command contract)

## SOP: NEW TARGET IN EXISTING CODEBASE

For a page/feature that does not exist yet inside a real codebase (UI TARGET ROUTING → B). The init gate (Task 1.1's six-file test), Task 1.2 (design system), Step 2 (requirements) and Step 2.5 (component extraction) run exactly as in SOP: EXISTING UI. Context collection does NOT: Task 1.1's target-page steps — reading the real render branch, recursive import tracing from the target — assume a rendered target, and a new page has none. Collect from what the new page will reuse instead:

- **Shared shell/layout components** (nav, sidebar, header, footer, layout wrapper) — full render code, same as for any page.
- **A representative existing page** as the style/structure anchor — pick the closest sibling feature (e.g. an existing list page when adding another list-like page) and trace THAT page's dependency tree (via `pages.md` or import tracing), under the usual PAYLOAD BUDGET / CONTEXT FILE LINE RANGES rules.
- **Existing components the new page should reuse** — discover them via `components.md` / `extractable-components.md`.
- **`design-system.md` + the globals tokens**, as on every design command.

Step 3 differs — there is no Step 3a:

- **Never create a "reproduction" of a page that doesn't exist.** Step 3a's job is capturing ground truth; for a new target there is none, and a fabricated "current UI" draft only corrupts the flow. Go straight to a design draft.
- **If a related existing page is already on the canvas as a confirmed draft** (reproduced or designed earlier in this project): prefer `execute-flow-pages` from that draft — it inherits the confirmed page's style and shell, which is exactly what a sibling page should do.
- **Otherwise**: `create-design-draft` with a normal design prompt (single `-p` describing the new page — a design prompt, not a reproduction prompt), passing `design-system.md`, the globals tokens, and the shared shell/layout + relevant component files as `--context-file` so the generated page matches the real app.
- When the user wants alternatives, explore them with `iterate-design-draft --mode branch` per the VARIANT COUNT RULE, same as Step 3b. Once the user selects a direction, route later feedback through **ITERATION MODE ROUTING** below.
- After the first successful draft/flow result, add this target and its exact context bundle to `.superdesign/resume.json` per [RESUME.md](RESUME.md).
- Optional, when the user emphasizes strict visual consistency with a specific existing page: offer to reproduce that representative page first (per Step 3a) and then `execute-flow-pages` the new page from it. This costs an extra generation, so propose it and let the user decide — don't do it unasked.

## SOP: BRAND NEW PROJECT

For a new target with no codebase (UI TARGET ROUTING → C).

Step 1 — Requirements gathering: ask the user

Step 2 — Design system setup (MUST follow the **DESIGN SYSTEM SETUP** section below):

- **Pick ONE primary style source — do NOT blend two competing styles:**
  - **If the user named a reference site** ("… in the style of `<site>`", "use `<site>`'s design"): that site's extracted `design.md` is the style source (extract step below). `search-prompts` is then OPTIONAL — do NOT layer a library style prompt on top of the extracted DNA (two competing styles dilute the result).
  - **Otherwise** (no reference site) use a library style prompt:
    1. `npx --yes @superdesign/cli@latest search-prompts --tags "style"` — pick the most suitable ONLY from returned results; if nothing comes back, proceed without a library style prompt (note that to the user). Either way do not keep searching — ignore the CLI's broaden-the-search hint.
    2. Index first to confirm the slug(s) and size: `npx --yes @superdesign/cli@latest get-prompts --slugs "<slug>"`
    3. Then fetch the full body ONLY for the chosen slug(s), right before writing design-system.md: `npx --yes @superdesign/cli@latest get-prompts --slugs "<slug>" --full`
- Extract a reference site's style (when one was named): `npx --yes @superdesign/cli@latest extract-website --url "<user-provided-url>" --design-md` (writes `.superdesign/website/<domain>/design.md`; add `--brand` for logo/colors). Read it, then decide how it flows into `design-system.md`:
  - **If a `design-system.md` already exists → ALWAYS ask the user first**. NEVER silently overwrite it.
  - If the intent is unclear, ask. If the workspace is fresh and the user clearly wants the site's look, proceed without asking. The three modes:
    - **Create from it** — `design-system.md` = the extracted site's DNA, adopted faithfully (user wants "make it look like `<site>`").
    - **Inspired by it** — blend the site's DNA with the product context + visual direction (cues from the site, but it stays the user's own brand). This is the default when unspecified.
    - **Update the existing** — merge the newly-extracted DNA into the current `design-system.md`, resolving conflicts thoughtfully (adding/refreshing a reference, or iterating on an existing system).
- Write .superdesign/design-system.md per the chosen mode (adapted to product context + UX flows + visual direction).

Step 3 — Design in Superdesign:

- Create project: `npx --yes @superdesign/cli@latest create-project --title "<X>"`
- Create initial draft (only for brand new, single -p only): `npx --yes @superdesign/cli@latest create-design-draft --project-id <id> --title "<X>" -p "<all design directions in one prompt>" --user-request "<the user's verbatim request>" --context-file .superdesign/design-system.md`
- Surface the `canvas` URL per [SKILL.md](../SKILL.md) "Surface the canvas URL", then gather feedback and iterate.
- Use **ITERATION MODE ROUTING** below: branch for alternatives, replace for feedback on the chosen direction.

---

## DESIGN SYSTEM SETUP

Design system should provides full context across:

- Product context, key pages & architecture, key features, JTBD
- Branding & styling: color, font, spacing, shadow, layout structure, etc.
- motion/animation patterns
- Specific project requirements

## PROMPT RULE

create-design-draft accepts ONLY ONE -p (extra -p flags are silently dropped — see the COMMAND CONTRACT). For existing UI, this single -p must be a faithful reproduction prompt — NO design changes.
iterate-design-draft accepts MULTIPLE -p (each -p = one variation/branch) and is the ONLY way to create design variations — never pack multiple variations into one -p string.

When using iterate-design-draft with multiple -p prompts:

- Prompt count: follow the **VARIANT COUNT RULE** in Step 3b (default 2).
- Each -p must describe ONE distinct direction (e.g. "conversion-focused hero", "editorial storytelling", "dense power-user layout"), and should specify what to change/explore and what to keep the same.
- Design-system fidelity for every -p is governed by DESIGN SYSTEM FIDELITY below.

**DESIGN SYSTEM FIDELITY (CRITICAL — #1 cause of bad iterations)**

Without explicit constraints, the Superdesign design agent will invent random fonts (serif, decorative), random colors (pink, neon, purple gradients), and random button styles. This happens because vague prompts like "bold design" or "modern feel" give the design agent creative freedom to deviate. The design system is a hard constraint, not a suggestion: iteration prompts explore layout/structure/content direction, never visual style.

To prevent this:

1. **ALWAYS pass `--context-file .superdesign/design-system.md`** on EVERY create-design-draft, iterate-design-draft, and execute-flow-pages call
2. **ALWAYS pass the globals.css tokens** on EVERY call — the whole file when under ~900 lines, else per the canonical rule in CONTEXT FILE LINE RANGES
3. **ALWAYS append the fidelity constraint** to every -p prompt: "Use ONLY the fonts, colors, spacing, and component styles defined in the design system. Do not introduce any fonts, colors, or visual styles not in the design system."
4. **Be explicit about what MUST stay the same** — e.g. "keep Inter as the font family, use black/white primary palette, amber/orange brand gradients only"

Path carve-outs: on the no-codebase path `globals.css` is not required — do not invent one. The graphic workflow passes neither file unless the user wants on-brand output (see the HARD GATE).

## EXECUTE FLOW RULE

When using execute-flow-pages:

- MUST ideate the details of each page, then confirm all pages and each prompt with the user

## TOOL USE RULE

Default tool while iterating design of a specific page is iterate-design-draft
Default tool while generating new pages based on an existing confirmed page is execute-flow-pages
Prefer iterating an existing design draft over creating new ones

### ITERATION MODE ROUTING

Choose the mode from the user's intent, not from the size of the requested change:

- **`replace` — creatively refine the selected direction.** Use one `-p` with `--mode replace` when the user wants the design model to interpret feedback about imagery, hierarchy, composition, layout, sections, styling, or another change requiring visual/design judgment. A change does not need to be tiny. Replace preserves the draft's version history and remains revertible; do not ask whether overwriting is okay.
- **`branch` — explore alternatives.** Use `--mode branch` when the user explicitly asks for another direction, options, variants, comparison, experimentation, or several distinct outcomes. Multiple `-p` prompts or `--count > 1` are always branch exploration.
- **Selection stops exploratory branching.** Phrases such as “I prefer,” “use this one,” “choose,” “continue with,” or “refine that direction” select a draft. Set that draft as active, then route subsequent feedback through **CORRECTION METHOD ROUTING**. Do not create a fresh branch merely because the feedback is substantial or arrives in a later turn.
- **Fix defects without branching.** Route deterministic defects through **CORRECTION METHOD ROUTING** below. Use replace only when fixing the defect still requires creative or structural design judgment. Never spend a branch on correcting a defect.
- **Ask only when intent is genuinely ambiguous.** If the user could reasonably mean either “change this draft” or “show me a separate option,” ask one concise clarification before spending generation credits. Do not ask when their language already identifies one desired result.

For branch calls that return several candidates, keep the source active until the user selects one. For replace, the draft id stays the same; update its current-version metadata and keep it active.

### CORRECTION METHOD ROUTING

Choose the authoring method before correcting the selected draft:

- **Direct edit — exact result is knowable from the request and current HTML.** Use `get-design --output` followed by `import-design-draft --into` for precise text/link corrections, removal of unsupported copy, swapping an already-uploaded public asset URL, literal class/style fixes, exact spacing/sizing/overflow changes, malformed markup cleanup, and similarly deterministic HTML/CSS edits. Keep the same draft id; the import creates a validated, revertible version without generation credits. Follow [design-with-your-model.md](design-with-your-model.md), act on returned warnings, refetch the saved HTML/version, and ask the user to review the canvas. Do not claim visual verification from reading HTML.
- **Model replace — desired result requires design judgment.** Use `iterate-design-draft --mode replace` for recomposition, hierarchy improvements, aesthetic refinement, responsive redesign, image-crop/art-direction choices, or feedback whose correct CSS/markup cannot be specified deterministically from the current HTML and user's words.
- **Branch — user wants alternatives.** Use branch only under **ITERATION MODE ROUTING** above.

If a request mixes exact corrections with creative redesign, include the exact constraints in one replace prompt rather than first direct-editing HTML that the model will immediately rewrite. If “make this better” is too ambiguous to choose a method, ask one concise question before spending credits.

For an unchanged initialized target, "prefer" is a hard routing rule: use [RESUME.md](RESUME.md); do not repeat init reads, source discovery, component checks, project creation, or reproduction.

When the user's feedback is vague ("I don't like the banner position"), ask what is bothering them and offer a couple of concrete directions before generating — a generation round spends the user's credits, so guessing at intent spends them on a coin flip. Skip the question when the ask is already concrete enough to turn into distinct `-p` variations.

## USER REQUEST PASSING

When you run `create-design-draft` or `iterate-design-draft` on behalf of a user request, you SHOULD pass the user's verbatim message for that round via `--user-request "<text>"`.

The same rule applies to `create-presentation` and presentation iterations.

- Pass the user's ACTUAL words for this round (not your paraphrase, not the design-system-fidelity boilerplate). This is the caller-side signal the design backend uses to improve generation quality.
- This is separate from `-p`/`--prompt`: `-p` is the directional design instruction(s) you author; `--user-request` is the raw human ask that motivated them.
- Transparency: the text is shared with SuperDesign and stored server-side to improve generation. Keep it to the round's request; the field is capped at 16KB (truncate if longer).
- It is optional. Omit it for agent-initiated steps that no user directly asked for (e.g. the Step 3a pixel-perfect reproduction).

## VERSION HISTORY & REVERT

Every draft keeps a version history. The CLI's default output already self-discloses version anchoring (`currentVersion`/`versions` plus `help[]` hints), so discover version numbers with `get-design` rather than tracking them by hand.

- **Iterate from an earlier version**: `iterate-design-draft ... --from-version <n>` starts from a specific historical version instead of the current head.
- **Revert to an earlier version** (no generation): `npx --yes @superdesign/cli@latest revert-design-draft --draft-id <id> --to-version <n>` restores a prior version as the current head. The revert is itself reversible — the current head is snapshotted into history first — so it is always safe to try. Use `get-design` to find the version number to restore.

## CONTEXT FILE LINE RANGES — CANONICAL TRIMMING RULE

**This is the single source of truth for when to trim a `--context-file`. Every other "trim" / "NEVER trim" / large-file mention in this skill defers to this rule. The threshold is ~900 lines.**

`--context-file` supports an optional `:startLine:endLine` suffix to include only specific portions of a file:

| Syntax                             | Meaning                               |
| ---------------------------------- | ------------------------------------- |
| `--context-file src/App.tsx`       | Full file (default)                   |
| `--context-file src/App.tsx:10:50` | Lines 10-50 only (1-based, inclusive) |
| `--context-file src/App.tsx:10`    | From line 10 to end of file           |

Multiple ranges from the same file are automatically merged into a single context entry with omission markers between non-contiguous ranges.

**Decision rule:**

- **Under ~900 lines**: FULL file — never trim visual code (CSS, JSX/template, config, all UI/layout components, any file interleaving UI and logic). Only exception: skip a large pure-logic block, e.g. `src/pages/Dashboard.tsx:60` keeps all JSX from line 60.
- **~900 lines or more (MANDATORY)**: line-range to what matters — the ONLY sanctioned way to "trim visual code": page/component → the render branch that actually renders; CSS → the `:root`/`.dark` token block + used selectors (for `globals.css`, prefer the token summary in `.superdesign/init/theme.md` instead); config → the relevant block.

---

## COMPONENT TEMPLATE SPEC

The Petite-Vue template spec for `create-component`/`update-component` conversions (what to hardcode vs extract as props, allowed syntax, output requirements, example conversion) lives in [COMPONENTS.md](COMPONENTS.md). Read it before converting any codebase component.

---

## COMMAND CONTRACT (read `--help`, never guess)

Always invoke via `npx --yes @superdesign/cli@latest`. Read flag sets off the CLI rather than from memory: the bare command lists every available command, and `<command> --help` prints its current, complete options. Do that before constructing an invocation whose exact form is not already specified by the active workflow. Canonical invocations in [RESUME.md](RESUME.md) may be used directly; do not add a `--help` round trip on every warm session unless a command rejects the documented form or you need different flags.

**This section is deliberately partial.** It carries only what `--help` cannot tell you: the traps, and which command to reach for. A flag missing from here is not a flag that does not exist — it just means `--help` already documents it correctly. Never conclude an option is unavailable because it is absent below.

Every command takes `--json` for the full machine payload, and `--full` expands truncated fields on the listing commands. The default output is agent-optimized TOON plus `help[]` next-step hints, and is usually the one you want. JSON-valued flags (`--pages`, `--props`, `--slots`, `--events`, `--css-imports`) take literal valid JSON — replace the values, not the brackets or keys.

**Traps `--help` will not warn you about:**

- `--context-file` accepts `path:startLine:endLine`, and several ranges for one file are merged into a single entry. No help text mentions this, and the whole PAYLOAD BUDGET rule depends on it.
- `create-design-draft` takes ONE `-p`. Extra `-p` flags are silently dropped — the run reports success and every variation but the last is gone. Variations exist only through `iterate-design-draft --mode branch`; `--mode replace` is likewise a single-`-p`, no-`--count` call.
- `extract-website` crawls server-side and takes ~60–120s. With no payload selector it defaults to `--design-md`. `--all` fetches every payload but writes no clone HTML and downloads no brand binaries, so still pass `--clone` / `--brand-assets` for those. `--brand-assets` implies `--brand`. It supersedes `extract-brand-guide`, which the command list still shows — do not use that one.
- `create-project --device` styles only the `--template` first draft; every later draft carries its own `--device`.
- The CLI's `init` installs skill files into the repo and `--force` overwrites them. It is NOT this skill's repo analysis — never run it for that.

**Which command:**

- No source draft to build on → `create-design-draft` (the Step 3a reproduction, a new target in an existing codebase, or a scratch project). Vary an existing draft → `iterate-design-draft`. Extend sibling pages from a confirmed one → `execute-flow-pages` (1-10 pages per call, each styled after the source draft).
- A slide deck is a presentation artifact, not a normal page or graphic. Read [PRESENTATION.md](PRESENTATION.md), approve the complete outline in chat, then use `create-presentation`. Never use `create-design-draft` for initial presentation creation.
- Before a presentation iteration, use `get-design --json` to load its stored outline and preferences. Structural replace edits pass the complete final outline through `--presentation-outline-file`; visible control changes pass `--navigation-controls`. Omit these presentation-only flags from ordinary drafts and non-structural presentation edits.
- Resuming a project from an earlier session → use `.superdesign/resume.json` and address its saved draft id directly. If the saved draft is rejected or resume state is unavailable, `fetch-design-nodes --project-id <id>` recovers the project's draft ids as the fallback.
- `--model`: model choice materially affects design quality, speed, and cost. Run `list-models`, choose a model that fits the task instead of always relying on the default, and briefly tell the user what you picked and why. Use different models for independent comparison directions when requested; never memorize the catalog. **Presentation exception:** follow [PRESENTATION.md](PRESENTATION.md); normal presentation creation, iteration, and visual branching omit `--model` and use the backend draft default.
- `--device` on `iterate-design-draft` is inherited from the source draft; omit it unless you are deliberately changing the viewport. `--kind graphic` switches `create-design-draft` to the fixed-canvas branch and sticks across iterations; pair it with `--width`/`--height` (see [GRAPHIC.md](GRAPHIC.md)).
- `execute-flow-pages --context` is a prose string; `--context-file` passes source files. They are different inputs.
- `create-design-draft`, `iterate-design-draft`, and `execute-flow-pages` accept image pixels through `--reference-id <ids...>`. Canvas image-node ids and Brand Asset keys are valid only within their project; an unknown id fails the job instead of being ignored.
- `upload-asset` requires explicit purpose in this workflow: `reference` for temporary canvas inputs, `brand` for reusable identity, and `content` for final imagery. Stable keys upsert and content hashes deduplicate; use the response's `nodeId`, `assetKey`, `url`, and `deduplicated` fields rather than guessing identifiers.
- A pasted direct public image URL is an agent-side adapter, not a platform fetch: read [WEBSITE.md](WEBSITE.md), download it safely to an external temporary file, then use the same `upload-asset` command. Do not upload raw PDFs; PDF reference ingestion is deferred.
- `get-prompts`: index with the default output first, then re-run with `--full` for the chosen slug(s) only.
- `create-project` auto-opens the browser — see Browser Choice in [SKILL.md](../SKILL.md). Revert and `--from-version` semantics live in VERSION HISTORY & REVERT.

## EXTRACT-WEBSITE

Live-site extraction (borrow a style, restyle/recombine sites, tokens, reference clones, and the pixel-recreation scope boundary) has its own reference: whenever a task involves a reference URL, read [WEBSITE.md](WEBSITE.md) and follow its recipes. Run `extract-website --help` for its flag set; the COMMAND CONTRACT above carries its gotchas.