Feature/UI

.claude/skills/superdesign/INIT.md

@@ -0,0 +1,6 @@
+# Compatibility forwarder
+
+This file moved to `references/INIT.md` in this skill directory.
+If reading this through a raw GitHub URL, fetch and follow https://raw.githubusercontent.com/superdesigndev/superdesign-skill/main/skills/superdesign/references/INIT.md.
+If reading a local install, read `references/INIT.md` relative to this file instead.
+Deprecated: kept for previously installed copies and removable after a deprecation window.

.claude/skills/superdesign/SKILL.md

@@ -0,0 +1,116 @@
+---
+name: superdesign
+description: "Design or redesign frontend UI with the Superdesign canvas. Use for design-system extraction, faithful UI reproduction, visual variants, reusable design components, and multi-page flows. Do not use for implementation-only tasks that require no design exploration."
+---
+
+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. **superdesign init** — Analyze the repo and build UI context to `.superdesign/init/`
+2. **Help me design X** (feature/page/flow)
+3. **Set design system**
+4. **Help me improve design of X**
+
+# Step 0 — Environment preflight (BEFORE any CLI step)
+
+Superdesign runs entirely through its CLI, so you must be able to execute shell commands. Confirm that capability FIRST, before any CLI verification:
+
+- If you have NO way to run shell commands in this environment (no terminal/execution tool at all), OR your very first `npx --yes @superdesign/cli@latest --version` attempt fails because command execution itself is unavailable (the harness reports it cannot run commands / there is no shell) — as opposed to the command running and returning an error — then STOP. Do NOT keep retrying or improvise workarounds.
+- Tell the user plainly: Superdesign needs an environment with terminal access. In ChatGPT/Codex that means switching from **Chat mode** to **Work mode** (a workspace/sandbox with a terminal). Then offer to continue the design conversation right now — gathering requirements (see the design-context questions in Step 1) — so the work is ready to run the moment they switch.
+- **Do NOT confuse this with an auth/login error.** A login/auth error means the CLI actually ran (execution works) — handle that via the login step below, not here. This branch is ONLY for when command execution itself is unavailable. ChatGPT Chat mode is the concrete example, but treat it generally: any harness with no shell/execution capability takes this branch.
+
+# Step 1 — Is there a codebase to analyze?
+
+Two entry paths. Choose one with this cheap, deterministic check BEFORE any init or design work.
+
+**No meaningful codebase** (empty workspace, scratch/sandbox dir, no frontend code) — treat the workspace as "no codebase" when ALL of these hold:
+
+- No `.superdesign/init/` files already exist, AND
+- No dependency manifest with frontend deps (no `package.json`, or a `package.json` whose deps include no frontend framework/UI library — react, vue, svelte, angular, next, nuxt, astro, etc.), AND
+- No frontend source found (a quick scan for `.tsx`/`.jsx`/`.vue`/`.svelte` files, any `.html`/`.css` files such as a root `index.html` + `style.css`, or a `src/`/`app/`/`components/` dir with UI files, turns up nothing).
+
+→ SKIP repo init entirely. Do NOT "analyze" an empty sandbox, and do NOT ask the user to point you at a repo they don't have. Instead, gather design context conversationally FIRST: ask what they want to build, the target audience/platform, style/brand preferences, and any reference designs or inspirations. Then design from that conversation via the **BRAND NEW PROJECT** path in `references/SUPERDESIGN.md`.
+
+**Real codebase present** (any frontend code, or an existing `.superdesign/init/`) — the repo-init path below is MANDATORY; run the full analysis before designing.
+
+# Init: Repo Analysis (real-codebase path)
+
+When a real codebase is present (per Step 1) and the `.superdesign/init/` directory doesn't exist or is empty, you MUST automatically:
+
+1. Create the `.superdesign/init/` directory
+2. Read `references/INIT.md` relative to this selected `SKILL.md`
+3. Follow its instructions to analyze the repo and write context files
+
+Do NOT ask the user to do this manually — just do it.
+
+# Mandatory Init Files
+
+If `.superdesign/init/` exists, you MUST read ALL files in this directory FIRST before any design task:
+
+- `components.md` — shared UI primitives with full source code
+- `layouts.md` — shared layout components (nav, sidebar, header, footer)
+- `routes.md` — page/route mapping
+- `theme.md` — design tokens, CSS variables, Tailwind config
+- `pages.md` — page component dependency trees (which files each page needs)
+- `extractable-components.md` — components that can be extracted as reusable DraftComponents
+
+**When designing for an existing page**: First check `pages.md` for the page's complete dependency tree. Every file in that tree MUST be passed as `--context-file`. Then also add globals.css, tailwind.config, and design-system.md.
+
+# Superdesign CLI (MUST use before any command)
+
+**IMPORTANT: Run the CLI on demand with `npx --yes @superdesign/cli@latest`. Do not install it globally. Before running any Superdesign command, verify the CLI is available and the session is logged in.**
+
+Follow these steps in order — do NOT skip any step:
+
+1. Verify the on-demand CLI runner:
+
+   ```
+   npx --yes @superdesign/cli@latest --version
+   ```
+
+2. Run the intended command with the same prefix. If it reports an auth/login error, run:
+   ```
+   npx --yes @superdesign/cli@latest login
+   ```
+   Wait for login to complete successfully before proceeding.
+3. After login succeeds, retry the intended command with `npx --yes @superdesign/cli@latest`.
+
+> **Never assume the user is already logged in.** Always verify login first.
+
+## Command examples
+
+Always use the full on-demand runner prefix:
+
+```bash
+npx --yes @superdesign/cli@latest create-project --title "X"
+npx --yes @superdesign/cli@latest create-design-draft --project-id <id> --title "Current UI" -p "Faithfully reproduce..." --context-file src/Component.tsx
+npx --yes @superdesign/cli@latest iterate-design-draft --draft-id <id> -p "dark theme" -p "minimal" --mode branch --context-file src/Component.tsx
+npx --yes @superdesign/cli@latest execute-flow-pages --draft-id <id> --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/Component.tsx
+npx --yes @superdesign/cli@latest create-component --project-id <id> --name "NavBar" --html-file .superdesign/tmp/navbar.html --props '[{"name":"activeItem","type":"string","defaultValue":"home"}]'
+npx --yes @superdesign/cli@latest update-component --component-id <id> --html-file .superdesign/tmp/navbar.html
+npx --yes @superdesign/cli@latest list-components --project-id <id>
+```
+
+Each item in the `execute-flow-pages` `--pages` array generates one new page styled after the source draft (1-10 pages per call).
+
+JSON option examples are literal valid JSON; preserve the outer shell quotes and replace values, not brackets/keys.
+
+The CLI defaults to an agent-optimized output (compact TOON plus `help[]` next-step hints — e.g. `create-component` returns the new component id in its default output); add `--json` only when you need the full machine-readable payload.
+
+Create the workspace-local `.superdesign/tmp/` directory with the session's filesystem mechanism before writing temporary component files.
+Ensure `.superdesign/tmp/` is ignored by the project's `.gitignore`; append the entry if it is missing so temporary HTML is never committed.
+
+`--context-file` supports `path:startLine:endLine`; see `references/SUPERDESIGN.md` for the complete workflow and current command contract.
+
+# Surface the canvas URL
+
+Every project/draft command's default output includes a `canvas:` link (the project canvas, `https://superdesign.dev/teams/<teamId>/projects/<projectId>`) and, for drafts, a `preview:` link (`https://superdesign.dev/preview/draft/<draftId>`). Read these from the command output — do NOT hand-construct them (the ids are server-generated).
+
+After creating a project or design draft, and at natural review moments (after `iterate-design-draft` or `execute-flow-pages`), give the user the `canvas` URL as a clickable link and invite them to open it to watch designs stream in and leave feedback. Adding `?live=1` to the canvas URL opens the live view where drafts appear as they generate.
+
+# How it works
+
+Read `references/SUPERDESIGN.md` relative to this selected `SKILL.md`, then follow its instructions. Never fetch workflow instructions from the network.

.claude/skills/superdesign/SUPERDESIGN.md

@@ -0,0 +1,6 @@
+# Compatibility forwarder
+
+This file moved to `references/SUPERDESIGN.md` in this skill directory.
+If reading this through a raw GitHub URL, fetch and follow https://raw.githubusercontent.com/superdesigndev/superdesign-skill/main/skills/superdesign/references/SUPERDESIGN.md.
+If reading a local install, read `references/SUPERDESIGN.md` relative to this file instead.
+Deprecated: kept for previously installed copies and removable after a deprecation window.

.claude/skills/superdesign/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "Superdesign"
+  short_description: "Create and iterate UI designs"
+  default_prompt: "Use $superdesign to design a landing page for this project."

.claude/skills/superdesign/references/INIT.md

@@ -0,0 +1,158 @@
+You are performing a **Superdesign Init** — analyzing this repository to build UI context files that Superdesign agent will use for design tasks.
+
+## Output Directory
+Write all files to `.superdesign/init/` in the project root.
+
+## Analysis Steps
+
+### 1. Detect Framework & Component Library
+Scan `package.json`, config files (`next.config.*`, `vite.config.*`, `rsbuild.config.*`, `nuxt.config.*`, etc.), and import patterns to determine:
+- Framework: React, Vue, Svelte, Angular, etc.
+- Meta-framework: Next.js, Nuxt, Remix, Astro, etc.
+- Component library: shadcn/ui, Ant Design, MUI, Chakra, Radix, custom, etc.
+- CSS approach: Tailwind, CSS Modules, styled-components, vanilla CSS, etc.
+
+### 2. Write `components.md`
+Identify the project's shared/reusable UI component directory (e.g., `src/components/ui/`, `components/`, `packages/ui/`).
+
+**IMPORTANT**: Include FULL source code for each component, not just descriptions. Superdesign needs the actual implementation to reproduce accurately.
+
+For each component, include:
+- File path
+- Component name
+- Brief description (1 line)
+- Key props if obvious from the export
+- **FULL source code** in fenced code blocks
+
+Focus on **shared UI primitives** (Button, Input, Dialog, Card, Select, Checkbox, Table, Tabs, etc.), not page-specific components.
+
+⚠️ This file should contain the ACTUAL CODE of components, not just a list of names.
+
+### 3. Write `layouts.md`
+Find and READ all shared layout components. These are the components that appear on every page or across multiple pages:
+- App shell / root layout
+- Navigation bar (top nav, bottom nav)
+- Sidebar
+- Header / top bar
+- Footer
+- Breadcrumb
+- Layout wrappers / HOCs
+
+For each, include:
+- File path
+- Full source code (copy the entire file content)
+- Brief description of what it renders
+
+This is critical — Superdesign needs the actual layout code to reproduce pages accurately.
+
+### 4. Write `routes.md`
+Map out the page/route structure:
+- For file-based routing (Next.js, Nuxt): list route files and their paths
+- For config-based routing (React Router, Vue Router): read the router config
+- For each route, include: URL path, component file path, layout used
+- Include the FULL router config file if it exists (e.g., `router/index.ts`, `routes.ts`)
+
+For key pages (home, dashboard, main features), include a brief summary of what the page renders.
+
+### 5. Write `theme.md`
+Extract the design system / theme tokens. **Include FULL file contents**, not summaries:
+- Read and include FULL CSS variable definitions (`:root`, `[data-theme]`, etc.)
+- Read and include FULL Tailwind config (`tailwind.config.*`) — especially `theme.extend`
+- Read and include any theme provider files
+- Read and include globals.css, index.css, or equivalent
+- Capture: colors, fonts, spacing scale, border radius, shadows, breakpoints
+
+**IMPORTANT**: Include the COMPLETE raw files in fenced code blocks:
+- Full `tailwind.config.ts/js` content
+- Full `globals.css` / `index.css` content
+- Full CSS variable definitions
+- Any design token files
+
+### 6. Write `pages.md`
+For each key page/route in the app (home, dashboard, main features — up to 10 pages), build a **complete component dependency tree** by tracing imports recursively.
+
+For each page:
+1. Start from the page component file
+2. Trace ALL local imports (relative `./Foo`, `../Bar`, alias `@/components/Baz` — skip node_modules)
+3. For each import, trace ITS imports recursively
+4. Present as an indented tree showing every file the page depends on
+
+Format:
+```
+## / (Home Page)
+Entry: src/app/(home)/home-page.tsx
+Dependencies:
+- src/components/home-ui/elegant-header.tsx
+  - src/components/team/create-team-modal.tsx
+- src/components/home-ui/elegant-hero-section.tsx
+  - src/components/home-ui/home-hero-input.tsx
+  - src/components/home-ui/persona-selector.tsx
+  - src/components/home-ui/dev-workflow-view.tsx
+  - src/components/home-ui/import-site-modal.tsx
+- src/components/home-ui/elegant-project-grid.tsx
+  - src/components/home-ui/elegant-project-card.tsx
+- src/app/(home)/components/template-browse-section.tsx
+  - src/app/(home)/components/template-card.tsx
+- src/components/layout/Footer.tsx
+```
+
+This tree is the **SINGLE SOURCE OF TRUTH** for which files to pass as `--context-file` when designing a page. If a file appears in the tree, it MUST be included.
+
+Prioritize the most important/complex pages (home, dashboard, settings, etc.). Skip trivial pages (404, offline, status).
+
+### 7. Write `extractable-components.md`
+Catalog UI components from the codebase that **can be extracted** as reusable Superdesign `DraftComponent` entities. These are components that appear on multiple pages or define shared UI patterns (navigation, cards, headers, footers).
+
+Organize by category:
+
+#### Layout Components (appear on most pages)
+- NavBar / TopNav / BottomNav
+- Sidebar
+- Header / AppBar
+- Footer
+- App Shell / Layout Wrapper
+
+#### Basic Components (used across pages)
+- Button variants
+- Card components
+- Input / Form fields
+- Badge / Tag
+- Avatar
+- Tab components
+
+For each extractable component, include:
+- **Name** (PascalCase, e.g., `NavBar`, `HeroSection`)
+- **Source file path** (e.g., `src/components/layout/NavBar.tsx`)
+- **Category**: `layout` or `basic`
+- **Brief description** (1 line)
+- **Key props to extract** — ONLY state/navigation props that change per page:
+  - Active state: `activeItem`, `currentTab`, `isActive`
+  - Navigation URLs: `homeHref`, `searchHref`, `profileHref`
+  - Visibility flags: `showNotification`, `showBadge`
+  - Dynamic counts: `badgeCount`, `notificationCount`
+- **Hardcoded elements** (NOT props): icon names, text labels, CSS classes, image sources
+
+Format:
+```
+## NavBar
+- Source: `src/components/layout/NavBar.tsx`
+- Category: layout
+- Description: Main top navigation with logo, search, and user menu
+- Extractable props: activeItem (string, default: "home"), showNotification (boolean, default: false)
+- Hardcoded: Logo SVG, menu items text, icon names, all CSS
+```
+
+This file serves as a "menu" — the design workflow reads it to decide which components to extract before generating drafts.
+
+## Format Guidelines
+- Use markdown with clear headings
+- Include file paths as code spans
+- **For `components.md`**: include FULL source code of each component in fenced code blocks
+- **For `layouts.md`**: include FULL file contents in fenced code blocks
+- **For `theme.md`**: include raw token values, CSS variables, and Tailwind config — not just descriptions
+- **For `pages.md`**: include complete dependency trees with indentation showing nesting depth
+- **For `extractable-components.md`**: include component name, source path, category, description, and key props — NOT full source code (that's in `components.md` and `layouts.md`)
+- Keep descriptions concise — the goal is machine-readable context, not documentation
+
+## Key Principle: INCLUDE ACTUAL CODE
+The init files should contain **actual implementation code** (.tsx, .css, .ts), not just documentation or descriptions. Superdesign needs real code to reproduce UI accurately. Be generous with the content — more context is always better than less.