design-import

name	design-import
license	MIT
compatibility	Claude Code 2.1.220+. Requires: claude-design-orchestrator agent. Optional: stitch, 21st-dev-magic, storybook-mcp MCP servers (used transitively via design-to-code).
description	Scaffolds React components from a Claude Design handoff bundle and stops at files on disk: no stories, no tests, no pull request. Use when handed a claude.ai/design URL or a local bundle file; when that same scaffold should carry on through test generation, browser verification and an opened PR, run /ork:design-ship instead.
argument-hint	<handoff-url | path-to-bundle.json>
tags	["claude-design","handoff","design-import","design-to-code","bundle","scaffold","frontend"]
context	fork
background	false
version	1.0.0
author	OrchestKit
user-invocable	true
complexity	medium
persuasion-type	collaborative
effort	high
model	sonnet
agent	claude-design-orchestrator
allowed-tools	["Read","Write","Edit","Glob","Grep","Bash","WebFetch","AskUserQuestion","Agent","TaskCreate","TaskUpdate","TaskList"]
skills	["design-to-code","component-search","design-context-extract","design-system-tokens","remember","memory"]
metadata	{"category":"workflow-automation","mcp-server":"stitch, 21st-dev-magic, storybook-mcp"}
triggers	{"keywords":["import claude design","design handoff","handoff bundle","claude.ai/design","design-import"],"examples":["import this Claude Design handoff: https://claude.ai/design/abc123","scaffold the components from this bundle","design-import /tmp/handoff.json"],"anti-triggers":["export","brainstorm","extract design tokens"]}
paths	["src/components/**/*.{tsx,css}",".claude/design-handoffs/**","**/*design-tokens*"]

Design Import

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

/ork:design-import https://claude.ai/design/abc123      # From handoff URL
/ork: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 /ork: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 /ork: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=[{
      : ,
      : ,
      : [
        {: , : },
        {: , : },
        {: , : }
      ],
      : 
    }])