SuperAPI AI Directory
Partner中文AI newsFavorites
Skillsdesign-import

design-import

Design & creation

View repository

Updated 10-16 01:50

About this skill

Design Import

Turn a Claude Design handoff bundle into scaffolded React components, with provenance and dedup against the existing codebase.

design-import https://claude.ai/design/abc123      # From handoff URL
design-import /tmp/handoff-bundle.json             # From local file

When to use

After exporting a handoff bundle from claude.ai/design. This skill is the entry point — it does NOT open a PR, run tests, or deploy. For the end-to-end flow (import → tests → PR), use design-ship instead.

Pipeline

Handoff bundle (URL or file)
  │
  ▼
┌──────────────────────────────┐
│ 1. PARSE + VALIDATE          │  via claude-design-orchestrator agent
│    - Fetch bundle             │  Schema validation
│    - Compute bundle_id (sha)  │  Surface deviations
└──────────┬───────────────────┘
           │
           ▼
┌──────────────────────────────┐
│ 2. RECONCILE TOKENS           │  Diff bundle tokens vs project tokens
│    - Read project tokens      │  Conflicts → AskUserQuestion
│    - Apply additions          │  Additions → write to design-tokens.json
└──────────┬───────────────────┘
           │
           ▼
┌──────────────────────────────┐
│ 3. DEDUP COMPONENTS           │  For each proposed component:
│    Storybook MCP first        │   • exact match → reuse (skip)
│    21st.dev next              │   • similar match → adapt
│    Filesystem grep last       │   • no match → scaffold
└──────────┬───────────────────┘
           │
           ▼
┌──────────────────────────────┐
│ 4. SCAFFOLD                   │  Delegate to design-to-code per component
│    (skipped components        │  Use bundle's tsx_scaffold as seed
│     logged but not touched)   │  Apply project tokens
└──────────┬───────────────────┘
           │
           ▼
┌──────────────────────────────┐
│ 5. WRITE PROVENANCE           │  .claude/design-handoffs/<bundle_id>.json
│    Bundle → files → (PR)      │  PR field empty until design-ship
└──────────┬───────────────────┘
           │
           ▼
   Import manifest (stdout)

Argument resolution

ARG = "$1"  # First positional argument

if ARG.startswith("http://") or ARG.startswith("https://"):
    bundle_source = "url"
    bundle_input = ARG
elif Path(ARG).exists():
    bundle_source = "file"
    bundle_input = ARG
else:
    AskUserQuestion(questions=[{
      "question": "I couldn't resolve that as a URL or file. What is it?",
      "header": "Bundle source",
      "options": [
        {"label": "Paste handoff URL", "description": "claude.ai/design URL"},
        {"label": "Paste file path", "description": "Local handoff JSON"},
        {"label": "Cancel", "description": "Abort import"}
      ],
      "multiSelect": False
    }])

Phase 1 — Parse + validate

Delegate to the orchestrator agent. The agent fetches, extracts the tarball, reads the README + chats, parses the HTML prototypes, and produces a normalized payload. Do NOT reimplement parsing here — the agent owns the (real, tarball-based) schema.

Agent(
  subagent_type="ork:claude-design-orchestrator",
  description="Parse and normalize handoff bundle",
  prompt=f"""Parse the Claude Design handoff bundle at {bundle_input}.

  This is a gzipped tarball (NOT a JSON manifest). Layout:
    <project>/README.md          ← read first
    <project>/chats/*.md         ← read all (load-bearing)
    <project>/project/*.html     ← prototypes (may be absent if incomplete)

  Tasks:
  1. Fetch the bundle (WebFetch if URL → saved .bin path; Read if local file)
  2. Extract: `tar -xzf <bin> -C /tmp/<scratch>/`
  3. Read README.md, then every chats/*.md (intent + clarifications live here)
  4. Compute bundle_id = sha256(canonical bundle URL or absolute path)
  5. If project/ is MISSING → return status="incomplete" with the assistant's
     last unanswered question; do NOT crash. Surface "what user should do".
  6. If project/ exists → pick primary HTML:
     - Prefer the file matching the URL's ?open_file= query param
     - Else first alphabetical
  7. From the primary HTML, extract:
     - Inline `:root { --... }` CSS custom properties as design tokens
     - Component sections (named via class/id/data-screen-label)
     - Asset references (<link>, <img>) — keep as URLs, do not download
     - EDITMODE JSON block (design-time state — capture as ANNOTATION only)
  8. Produce normalized output payload (see agent spec)
  9. Write provenance to .claude/design-handoffs/<bundle_id>.json:
     - bundle_url, bundle_id, fetched_at, status, components: [], pr: null
  10. Return the normalized payload as JSON

  Surface any deviations from the expected tarball layout explicitly.
  Never expect a JSON `components[]` field — that was the old (wrong) shape.
  """
)

Phase 2 — Reconcile tokens

Read the normalized token_diff from the agent's payload.

Diff field Action
added Append to project's design-tokens.json (or Tailwind config). No prompt — additions are safe.
modified Show diff. AskUserQuestion: keep project value, accept bundle value, or open editor.
conflicts Block scaffolding. AskUserQuestion to resolve before continuing. 
if token_diff["conflicts"]:
    AskUserQuestion(questions=[{
      "question": f"Token conflict on {conflict.path}. Project says {conflict.project}, bundle says {conflict.bundle}. Resolve?",
      "header": "Token conflict",
      "options": [
        {"label": "Keep project value", "description": "Bundle adapts to project"},
        {"label": "Accept bundle value", "description": "Project adapts to bundle (writes new token)"},
        {"label": "Both — namespace bundle's", "description": f"Add as {conflict.path}.imported"}
      ],
      "multiSelect": False
    }])

Phase 3 — Dedup components

The agent already ran component-search per component. Read decisions from the normalized payload:

decision Behavior
reuse Log "skipped (existing: )" — do nothing on disk
adapt Pipe through ork:design-to-code with --adapt-from <existing-path> context
scaffold Pipe through ork:design-to-code with the bundle's tsx_scaffold as seed

Phase 4 — Scaffold

For each component with decision scaffold or adapt, invoke design-to-code. The spawns run in the background at the same time, so each one gets its own worktree (isolation="worktree", #4557): ork agents carry no frontmatter isolation, and without it every component writes into your tree at once.

for component in payload["components"]:
    if component["decision"] in ("scaffold", "adapt"):
        # Compose, don't reimplement — design-to-code owns the EXTRACT/MATCH/ADAPT/RENDER pipeline
        Agent(
          subagent_type="ork:frontend-ui-developer",
          name=f"scaffold-{component['name']}",
          description=f"Scaffold {component['name']} from bundle",
          prompt=f"""Use the design-to-code skill to scaffold this component.

          Source: handoff bundle {payload['bundle_id']}
          Component: {component['name']}
          Target path: {component['target_path']}
          Bundle scaffold seed:
          ```tsx
          {component['tsx_scaffold']}
          ```
          Resolved tokens: {component['tokens_resolved']}
          Decision: {component['decision']}
          {f"Adapt from: {component['existing_match']}" if component['decision'] == 'adapt' else ''}

          Write the component, mirror existing project file structure, use project tokens.
          Commit it in your worktree before you return, and end your reply with
          your branch name and commit sha. Uncommitted files are not merged.
          """,
          run_in_background=True,
          isolation="worktree",
          max_turns=25,
        )

Collect and merge the component worktrees

Wait for every scaffold agent to return before Phase 5. For each one:

  1. Check its worktree is clean: git -C <worktree> status --porcelain prints nothing. If it prints files, commit them there and note it in the report.
  2. Merge its branch into the current branch. A conflict means two components wrote the same file: stop and report both paths.
  3. Confirm component['target_path'] exists after the merge. A component whose agent failed or wrote elsewhere goes into failed_components: it is reported, not recorded as written.

Phase 5 — Provenance

Update the provenance file with the actual file paths written:

provenance = Read(payload["provenance_path"])
provenance["components"] = [
    {"name": c["name"], "decision": c["decision"], "path": c["target_path"]}
    for c in payload["components"]
    if c["name"] not in failed_components  # from "Collect and merge" step 3
]
provenance["imported_at"] = now()
Write(payload["provenance_path"], provenance)

Output — import manifest

Print a concise summary (not a wall of JSON):

Imported bundle <bundle_id>
  Source: <bundle_url>
  Provenance: .claude/design-handoffs/<bundle_id>.json

Components:
  ✓ PricingCard          scaffold  src/components/pricing/PricingCard.tsx
  ↻ Button               reuse     existing: src/components/ui/Button.tsx
  ⤳ Hero                 adapt     adapted from: src/components/Hero.tsx

Tokens:
  + 3 new (added to design-tokens.json)
  ~ 1 modified (user accepted bundle value)
  ✗ 0 conflicts unresolved

Next: design-ship <bundle_id>   # to open PR
      expect                     # to verify

Hooks

  • After completion, the post-design-import hook recommends expect (non-blocking, see hook for details).

Composition

Skill Role
design-to-code Owns the actual scaffold pipeline (EXTRACT/MATCH/ADAPT/RENDER). This skill delegates to it per component.
component-search Used by the orchestrator agent for dedup
design-context-extract Used if bundle is missing design_tokens block
design-system-tokens Token reconciliation reference
remember / memory Provenance + prior-import detection

NOT this skill's job

Concern Owned by
Open PR design-ship
Run tests post-design-import hook → expect
Generate Storybook stories cover (called by design-ship)
Re-prompt Claude Design Not yet — no public API

Limitations

  • No public Claude Design API yet: bundles are one-shot exports. To iterate, re-export from claude.ai/design and re-import. The reverse-path (drift detection + refinement prompt) is tracked in M124 — Claude Design Drift Sync (Bet B): #1391, #1393, #1394, #1395, #1397.
  • Schema is provisional: Claude Design has not published a stable bundle schema. The orchestrator agent adapts to deviations but may need updates as the format stabilizes.
  • Asset URLs are referenced, not downloaded: bundle asset_urls are kept as-is. If you need them in-repo, run a separate sync step.