SuperDesign helps you (1) find design inspirations/styles and (2) generate/iterate design drafts on an infinite canvas.

Core scenarios (what this skill handles)

1. Help me design X (feature/page/flow)
2. Set design system
3. Help me improve design of X

Quickstart

Install CLI

npm install -g @superdesign/cli@latest

Usage telemetry

SuperDesign collects anonymous CLI command usage and failure codes to improve reliability. It never sends prompts, file contents, paths, hostnames, or credentials. Set DO_NOT_TRACK=1 (or SUPERDESIGN_TELEMETRY_DISABLED=1) to disable all usage telemetry.

Authentication & environment

• auth status --json — machine-readable auth state: authenticated, source (config | env), team, and the resolved configPath. It is a query, not a gate, so it always exits 0.
• SUPERDESIGN_TOKEN — provide the API token directly. It wins over the on-disk config, and when set no config file is required at all (useful in read-only-HOME sandboxes and CI). Never persisted; never sent to telemetry.
• SUPERDESIGN_CONFIG_DIR — override the config directory (highest precedence). Otherwise $XDG_CONFIG_HOME/superdesign is used when XDG_CONFIG_HOME is set, falling back to ~/.superdesign. Existing ~/.superdesign installs keep working unchanged. Point this at a writable path if the default location is read-only.
• superdesign login --no-browser — do not launch a browser; print the authorization URL and session code so you can complete auth manually (headless/agent use). Add --json to receive the auth-session payload (URL + code) as JSON before polling begins.
• list-models — the unified model catalog: draft LLMs (for --model on draft commands) and image/video generation models, each with style notes. list-models <model-id> prints details (generation models include the full parameter schema). --json keeps the legacy models whitelist key.

Install skills for any coding agent

npx skills add superdesigndev/superdesign-skill

Prompt in any agent

/superdesign help me design X

--

Tooling overview

A) Inspiration & Style Tools (generic, always available)

Use these to discover style direction, references, and brand context:

• Search prompt library (style/components/pages)

  superdesign search-prompts --query "<query>" --json
  superdesign search-prompts --tags "style" --json
  superdesign search-prompts --tags "style" --query "<style query>" --json

• Get full prompt details

  superdesign get-prompts --slugs "<slug1,slug2,...>" --json

• Extract brand guide from a URL

  superdesign extract-brand-guide --url https://example.com --json

B) Canvas Design Tools

Use design agent to generate high quality design drafts:

• Create project (auto-detects .superdesign/design-system.md as prompt)
• Create design draft
• Iterate design draft (replace / branch)
• Plan flow pages → execute flow pages
• Fetch specific design draft

C) Image & Video Generation (quote → confirm; spends credits)

Generation is a two-step protocol so credits are never spent without the user's knowledge:

1. generate-image / generate-video return a free quote (price, balance, expiry, and the exact confirm command). Nothing is charged.
2. confirm-generation <id> --credits <N> executes it - the only command that spends credits, and --credits must restate the quoted price exactly.

Three rules for agents:

1. Confirmation protocol. confirm-generation spends credits. NEVER run it without the user's explicit confirmation of the quoted credits in this conversation. If it gets interrupted by a timeout, re-run the same command or use get-generation <id> --wait - it is idempotent and will not double-charge. Do not re-quote after an interruption.
2. Host-native images first. If your host agent has native image generation and the user just needs an image asset, generate it natively and import with superdesign upload-asset (free). Use superdesign generate-image when the user asks for a specific Superdesign model, wants to compare results, or wants the generation tracked in the Superdesign ledger. For video there is no native alternative - superdesign generate-video is the path.
3. Pick draft models deliberately. Model choice matters for draft quality. Run superdesign list-models and pick a draft model that fits the task instead of always using the default - e.g. models known for strong front-end aesthetics for visual-heavy pages, faster models for quick ideation. Mention your pick and why to the user.

The human can pre-authorize small spends with superdesign config set generation.autoConfirmBelow <0-200> (default 0 = always ask; only a human should change this).

Overall SOP for designing features on top of existing app:

1. Investigate existing UI, workflow
2. Setup design system file if not exist yet
3. Requirements gathering: use askQuestion tool to clarify requirements with users (Optionally use Inspiration tool to find inspiration when needed)
4. Ask user whether ready to design in superdesign OR implement UI directly
5. If yes to superdesign 5.1 Create/update a pixel perfect html replica of current UI of page that we will design on top of in .superdesign/replica_html_template/<name>.html (html should only contain & reflect how UI look now, the actual design should be handled by superdesign agent) 5.2 Create project with this replica html 5.3 Start desigining by iterating & branching design draft based on designDraft ID returned from project

Always-on rules

• Design system should live at: .superdesign/design-system.md
• If .superdesign/design-system.md is missing, run Design System Setup first.
• Use askQuestion to ask high-signal questions (constraints, taste, tradeoffs).
• Always use --json for machine parsing.

replica_html_template rules (Canvas only)

The purpose of replica html template is creating a lightweight version of existing UI so design agent can iterate on top of it (Since superdesign doesn't have access to your codebase directly, this is important context)

Overall process for designing features on top of existing app:

1. Identify & understand existing UI of page related
2. Create/update a pixel perfect replica html in .superdesign/replica_html_template/<name>.html (Only replicate how UI look now, do NOT design)

• If design task is redesign profile page, then replicate current profile page UI pixel perfectly
• If design task is add new button to side panel, identify which page side panel is using, then replicate that page UI pixel perfectly

replica_html_template = BEFORE state (what exists now). It provides context for SuperDesign agent. Actual design will be done via superdesign agent, by passing the prompt

The replica_html_template must contain ONLY UI that currently exists in the codebase.

• DO NOT design or improve anything in the replica_html_template
• DO NOT add placeholder sections like <!-- NEW FEATURE - DESIGN THIS -->
• DO create pixel-perfect replica of current UI state
• Save to: .superdesign/replica_html_template/<name>.html

Naming & Reuse

Naming convention Name replica_html_template for reusability: Use the page route (e.g., home.html, settings-profile.html, dashboard.html) This makes it easy to identify if a page_template already exists.

Before creating a replica_html_template:

1. Check if .superdesign/replica_html_template/ already contains a matching file
2. If exists: reuse it or update to reflect the latest existing UI
3. If not exists: create the neww file

Example: Adding a "Book Demo" section to home page

BAD approach:

<!-- replica_html_template includes a sketched Book Demo section -->
<section class="book-demo">
  <!-- DESIGN THIS - Add CTA here -->
  <h3>Book a Demo</h3>
  <button>Schedule</button>
</section>

GOOD approach:

<!-- replica_html_template is pure replica of existing home page (hero + projects) -->

Then in the iterate command: 1/ create project passing this replica html 2/ create design draft based on design draft id

1) Design System Setup

Step 0 — Ask user (one question)

"Do you want to create a new design system or extract from the current codebase?"

A) Extract from codebase

1. Investigate codebase:
   • Product context: what is being built, target users, core value proposition, key user journeys and page structure
   • design tokens, typography, colors, spacing, radius, shadows
   • motion/animation patterns
   • example components usage + implementation patterns
2. Write standalone design system to:
   • .superdesign/design-system.md
   • Must be implementable without the codebase

B) Create a new design system (to improve current UI)

1. Investigate codebase to understand:
   • Product context: what is being built, target users, core value proposition, key user journeys and page structure
   • needed pages/components
2. Gather inspirations (generic tools):
   • superdesign search-prompts --tags "style" --json
   • superdesign get-prompts --slugs ... --json
   • optional: superdesign extract-brand-guide --url ... --json
3. Interview user (askQuestion) to choose direction
4. Write:
   • .superdesign/design-system.md (product context + UX flows + visual design, adapted to references)

2) Designing X (feature/page/flow)

Example workflow - Add feature to existing page

1. Investigate existing design and Ask targeted questions (askQuestion) about requirements + taste
2. After clarifying, Ask user whether ready to design in superdesign OR implement UI directly
3. If design in superdesign 3.1 Ensure .superdesign/design-system.md exists (setup if missing) 3.2 Identify page most relevant, and build a pixel-perfect replica in replica_html_template:
   • .superdesign/replica_html_template/<page>-<feature>.html 3.3 Create project with replica_html_template (returns draftId):

   superdesign create-project \
     --title "<feature>" \
     --template .superdesign/replica_html_template/<file>.html \
     --json

   → Note: draftId in response is the baseline draft → Auto-detects .superdesign/design-system.md as project prompt 3.4 Branch designs from baseline (use draftId from step 3.3)

   superdesign iterate-design-draft \
     --draft-id <draftId> \
     -p "Dark theme with neon accents" \
     -p "Minimal with more whitespace" \
     -p "Bold gradients and shadows" \
     --mode branch \
     --json

   3.5 Share design title & preview URL → collect feedback → iterate

Advanced usage

Design multiple page OR a full user journey

Execute:

superdesign execute-flow-pages \
  --draft-id <draftId> \
  --pages '[{"title":"Signup","prompt":"..."},{"title":"Payment","prompt":"..."}]' \
  --json

Get HTML reference from a draft

superdesign get-design --draft-id <draftId>

Quick reference (key commands)

# Inspirations
superdesign search-prompts --query "<query>" --json
superdesign search-prompts --tags "style" --json
superdesign get-prompts --slugs "<slug1,slug2>" --json
superdesign extract-brand-guide --url https://example.com --json

# Canvas - Create project (auto-detects .superdesign/design-system.md as prompt)
superdesign create-project --title "X" --json
superdesign create-project --title "X" --template ./index.html --json

# Iterate: replace mode (single variation, updates in place)
superdesign iterate-design-draft --draft-id <id> -p "..." --mode replace --json

# Iterate: Explore multiple versions & variations (each prompt = one variation, prompt should be just directional, do not specify color, style, let superdesign design expert fill in details, you just give direction)
superdesign iterate-design-draft --draft-id <id> -p "dark theme" -p "minimal" -p "bold" --mode branch --json

# Iterate: Auto explore (only give exploration direction, and let Superdesign fill in details, e.g. explore different styles; Default do not use this)
superdesign iterate-design-draft --draft-id <id> -p "..." --mode branch --count 3 --json

# Fetch & get designs
superdesign fetch-design-nodes --project-id <id> --json
superdesign get-design --draft-id <id> --json

# Create new design from scracth without any reference - ONLY use this for creating brand new design, default NEVER use this
superdesign create-design-draft --project-id <id> --title "X" -p "..." --json

# Image & video generation - two steps, credits spent ONLY at confirm
superdesign list-models bytedance/seedance-1-pro-fast     # full parameter schema
superdesign generate-image --project-id <id> --prompt "..." --model bytedance/seedream-5.0-lite   # FREE quote
superdesign generate-video --project-id <id> --prompt "..." --image <node-id> --resolution 720p --duration 8   # FREE quote
superdesign confirm-generation <id> --credits <quoted-N>  # SPENDS credits; requires user approval first
superdesign get-generation <id> --wait                    # resume an interrupted wait (idempotent)
superdesign list-generations --kind video                 # the team asset ledger

# Import HTML you authored with YOUR OWN model (no AI generation, no credits).
# Viewport is required; see `import-design-draft --help` for the HTML contract.
superdesign import-design-draft --project-id <id> --title "X" --device desktop --html-file ./page.html --generated-by <your-model-id>
# Push a fixed/new version onto an existing draft (revertible)
superdesign import-design-draft --into <draftId> --html-file ./page-v2.html --generated-by <your-model-id>