design-ship

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Design Ship

One command: Claude Design handoff URL → reviewable GitHub PR.

bash

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

一条命令：Claude Design交付URL → 可评审的GitHub PR。

bash

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

When to use

使用场景

You have a Claude Design handoff URL (or file) and want a PR opened against the current branch. No intermediate steps, no manual test generation, no manual PR drafting.

For just-the-import (no tests, no PR), use

/ork:design-import

instead.

当你拥有Claude Design交付URL（或文件），并希望针对当前分支创建PR时使用。无需中间步骤，无需手动生成测试，无需手动撰写PR。

如果仅需导入（无需测试和PR），请改用

/ork:design-import

。

Pipeline

工作流管道

Handoff bundle (URL or file)
  │
  ▼
┌──────────────────────────────┐
│ 1. /ork:design-import         │  Scaffold components, write provenance
│    (delegates to orchestrator │  Tokens reconciled
│     for parse + dedup)        │  Components written or reused
└──────────┬───────────────────┘
           │
           ▼
┌──────────────────────────────┐
│ 2. /ork:cover                 │  Storybook stories per new component
│    (Storybook + Playwright)   │  Playwright E2E for new routes/views
└──────────┬───────────────────┘
           │
           ▼
┌──────────────────────────────┐
│ 3. /ork:expect                │  Diff-aware browser verification
│    (CDP + ARIA-tree-first)    │  Screenshots saved for PR body
└──────────┬───────────────────┘
           │
           ▼
┌──────────────────────────────┐
│ 4. /ork:create-pr             │  PR opened with:
│                               │   - Claude Design URL link
│                               │   - Before/after screenshots
│                               │   - Component scaffold list
│                               │   - Coverage delta
│                               │   - Label: claude-design
└──────────┬───────────────────┘
           │
           ▼
┌──────────────────────────────┐
│ 5. UPDATE PROVENANCE          │  Patch .claude/design-handoffs/<id>.json
│                               │  with the opened PR number + URL
└──────────────────────────────┘

交付包（URL或文件）
  │
  ▼
┌──────────────────────────────┐
│ 1. /ork:design-import         │  生成组件脚手架，写入溯源信息
│    (委托给编排器执行解析与去重) │  令牌已协调
│                               │  组件已创建或复用
└──────────┬───────────────────┘
           │
           ▼
┌──────────────────────────────┐
│ 2. /ork:cover                 │  为每个新组件生成Storybook stories
│    (Storybook + Playwright)   │  若注册了新路由/视图则生成Playwright E2E测试
└──────────┬───────────────────┘
           │
           ▼
┌──────────────────────────────┐
│ 3. /ork:expect                │  基于差异的浏览器验证
│    (CDP + ARIA-tree-first)    │  保存截图用于PR正文
└──────────┬───────────────────┘
           │
           ▼
┌──────────────────────────────┐
│ 4. /ork:create-pr             │  创建PR并包含以下内容：
│                               │   - Claude Design URL链接
│                               │   - 前后对比截图
│                               │   - 组件脚手架列表
│                               │   - 覆盖率变化
│                               │   - 标签：claude-design
└──────────┬───────────────────┘
           │
           ▼
┌──────────────────────────────┐
│ 5. 更新溯源信息                │  修补.claude/design-handoffs/<id>.json文件
│                               │  添加已创建的PR编号 + URL
└──────────────────────────────┘

Pre-flight

前置检查

Before starting the pipeline, verify the working tree is clean enough to ship:

python

status = Bash("git status --porcelain")
if status:
    AskUserQuestion(questions=[{
      "question": "Working tree has uncommitted changes. How to proceed?",
      "header": "Pre-flight",
      "options": [
        {"label": "Commit them first", "description": "Run /ork:commit, then proceed with ship"},
        {"label": "Stash and restore", "description": "Stash now, restore after PR opens"},
        {"label": "Include in this PR", "description": "Risky — only if changes are related"},
        {"label": "Cancel", "description": "Abort design-ship"}
      ],
      "multiSelect": False
    }])

current_branch = Bash("git branch --show-current")
if current_branch in ("main", "master", "dev"):
    AskUserQuestion(questions=[{
      "question": f"You're on {current_branch}. Create a feature branch?",
      "header": "Branch",
      "options": [
        {"label": "Yes — feat/design-ship-<bundle-id>", "description": "Recommended"},
        {"label": "Cancel", "description": "Switch branch yourself first"}
      ],
      "multiSelect": False
    }])

启动工作流管道前，请确保工作树足够干净以执行交付：

python

status = Bash("git status --porcelain")
if status:
    AskUserQuestion(questions=[{
      "question": "Working tree has uncommitted changes. How to proceed?",
      "header": "Pre-flight",
      "options": [
        {"label": "Commit them first", "description": "Run /ork:commit, then proceed with ship"},
        {"label": "Stash and restore", "description": "Stash now, restore after PR opens"},
        {"label": "Include in this PR", "description": "Risky — only if changes are related"},
        {"label": "Cancel", "description": "Abort design-ship"}
      ],
      "multiSelect": False
    }])

current_branch = Bash("git branch --show-current")
if current_branch in ("main", "master", "dev"):
    AskUserQuestion(questions=[{
      "question": f"You're on {current_branch}. Create a feature branch?",
      "header": "Branch",
      "options": [
        {"label": "Yes — feat/design-ship-<bundle-id>", "description": "Recommended"},
        {"label": "Cancel", "description": "Switch branch yourself first"}
      ],
      "multiSelect": False
    }])

Phase 1 — Import

阶段1 — 导入

Delegate to

/ork:design-import

with the bundle argument. Capture its output (the import manifest) — it includes the bundle_id, list of components written, and the provenance file path.

If import fails, stop. Do NOT proceed to test generation against partially-imported components.

将交付包参数传递给

/ork:design-import

执行。捕获其输出（导入清单）——其中包含bundle_id、已创建组件列表以及溯源文件路径。

如果导入失败，立即停止。请勿针对部分导入的组件继续生成测试。

Phase 2 — Cover

阶段2 — 覆盖测试

Run

/ork:cover

scoped to the components written by phase 1:

python

component_paths = [c["path"] for c in import_result["components"] if c["decision"] != "reuse"]

Agent(
  subagent_type="test-generator",
  description="Cover the freshly-imported components",
  prompt=f"""Use the cover skill to generate tests for these components (scoped — do not regenerate suites for unrelated files):
  {component_paths}

  Tiers needed:
  - Storybook stories per component (mandatory)
  - Playwright E2E if any new route was registered (check src/app or src/pages)
  - Unit tests if the components include non-trivial logic (skip for pure-presentation)
  """
)

针对阶段1创建的组件，运行

/ork:cover

：

python

component_paths = [c["path"] for c in import_result["components"] if c["decision"] != "reuse"]

Agent(
  subagent_type="test-generator",
  description="Cover the freshly-imported components",
  prompt=f"""Use the cover skill to generate tests for these components (scoped — do not regenerate suites for unrelated files):
  {component_paths}

  Tiers needed:
  - Storybook stories per component (mandatory)
  - Playwright E2E if any new route was registered (check src/app or src/pages)
  - Unit tests if the components include non-trivial logic (skip for pure-presentation)
  """
)

Phase 3 — Expect

阶段3 — 验证

Run

/ork:expect

to do diff-aware browser verification. This produces the screenshots that go into the PR body:

python

Agent(
  subagent_type="expect-agent",
  description="Diff-aware verification of imported components",
  prompt=f"""Use the expect skill on the current diff.

  Extra: capture before/after screenshots for each new component
  and save them to .claude/design-handoffs/{bundle_id}/screenshots/.
  These will be uploaded to the PR body.

  If verification fails, do not block — report findings and continue.
  Failures will surface in the PR review.
  """
)

运行

/ork:expect

执行基于差异的浏览器验证。这将生成用于PR正文的截图：

python

Agent(
  subagent_type="expect-agent",
  description="Diff-aware verification of imported components",
  prompt=f"""Use the expect skill on the current diff.

  Extra: capture before/after screenshots for each new component
  and save them to .claude/design-handoffs/{bundle_id}/screenshots/.
  These will be uploaded to the PR body.

  If verification fails, do not block — report findings and continue.
  Failures will surface in the PR review.
  """
)

Phase 4 — Create PR

阶段4 — 创建PR

Use

/ork:create-pr

with a body templated from the bundle and verification results:

python

pr_body = f"""## Summary
Generated from Claude Design handoff: {bundle_url}

Bundle ID: `{bundle_id}` · Provenance: `.claude/design-handoffs/{bundle_id}.json`

使用

/ork:create-pr

，并根据交付包和验证结果生成PR正文模板：

python

pr_body = f"""## Summary
Generated from Claude Design handoff: {bundle_url}

Bundle ID: `{bundle_id}` · Provenance: `.claude/design-handoffs/{bundle_id}.json`

Components

Decision	Component	Path
{table_from(import_result['components'])}

Decision	Component	Path
{table_from(import_result['components'])}

Tokens

Added: {len(token_diff['added'])}
Modified: {len(token_diff['modified'])}
Conflicts (resolved): {len(token_diff['conflicts'])}

Added: {len(token_diff['added'])}
Modified: {len(token_diff['modified'])}
Conflicts (resolved): {len(token_diff['conflicts'])}

Verification (

/ork:expect

)

Verification (

/ork:expect

)

{expect_summary}

Coverage delta (

/ork:cover

)

Coverage delta (

/ork:cover

)

{coverage_delta}

Screenshots

{screenshot_table}

🤖 Opened by

/ork:design-ship

· Closes: (none — link issues manually) """

Bash(f"gh pr create --title '{pr_title}' --body @- <<< '{pr_body}' --label claude-design")

undefined

{screenshot_table}

🤖 Opened by

/ork:design-ship

· Closes: (none — link issues manually) """

Bash(f"gh pr create --title '{pr_title}' --body @- <<< '{pr_body}' --label claude-design")

undefined

Phase 5 — Update provenance

阶段5 — 更新溯源信息

Patch the provenance file with the opened PR number and URL:

python

provenance = Read(f".claude/design-handoffs/{bundle_id}.json")
provenance["pr"] = {"number": pr_number, "url": pr_url, "opened_at": now()}
Write(f".claude/design-handoffs/{bundle_id}.json", provenance)

修补溯源文件，添加已创建的PR编号和URL：

python

provenance = Read(f".claude/design-handoffs/{bundle_id}.json")
provenance["pr"] = {"number": pr_number, "url": pr_url, "opened_at": now()}
Write(f".claude/design-handoffs/{bundle_id}.json", provenance)

Failure modes

故障模式

Phase	Failure	Behavior
Pre-flight	Dirty tree, on main	AskUserQuestion, do not proceed silently
1. Import	Schema deviation, token conflict	`design-import` already prompts; if user cancels, abort
2. Cover	Test generation fails	Continue to expect — tests are recoverable in PR review
3. Expect	Browser verification fails	Continue to PR — failures noted in PR body
4. Create PR	`gh` not authenticated	Stop, surface auth error
5. Provenance	File not writable	Warn but do not fail (PR is already open)

阶段	故障	行为
前置检查	工作树未清理，处于主分支	询问用户问题，不会静默执行
1. 导入	Schema偏差，令牌冲突	`design-import` 会提示用户；若用户取消，则终止流程
2. 覆盖测试	测试生成失败	继续执行验证步骤 — 可在PR评审中修复测试
3. 验证	浏览器验证失败	继续创建PR — 故障会记录在PR正文中
4. 创建PR	`gh` 未认证	停止流程，显示认证错误
5. 溯源信息	文件不可写	发出警告但不终止流程（PR已创建）

Composition

组件构成

Skill	Role
`design-import`	Phase 1 — scaffold components
`cover`	Phase 2 — Storybook + Playwright
`expect`	Phase 3 — diff-aware browser verification
`create-pr`	Phase 4 — open PR with templated body
`remember` / `memory`	Provenance updates

技能	角色
`design-import`	阶段1 — 生成组件脚手架
`cover`	阶段2 — Storybook + Playwright测试生成
`expect`	阶段3 — 基于差异的浏览器验证
`create-pr`	阶段4 — 创建带模板正文的PR
`remember` / `memory`	更新溯源信息

NOT this skill's job

非本技能职责

Concern	Owned by
Parsing bundles	`claude-design-orchestrator` agent (called by `design-import` )
Component dedup	Orchestrator agent (called by `design-import` )
Test execution (CI)	GitHub Actions — this skill only generates tests
Merging the PR	Human reviewer — never auto-merge

事项	负责方
解析交付包	`claude-design-orchestrator` agent（由 `design-import` 调用）
组件去重	编排器agent（由 `design-import` 调用）
测试执行（CI）	GitHub Actions — 本技能仅生成测试
合并PR	人工评审者 — 绝不会自动合并

Limitations

局限性

No auto-merge: this skill opens the PR; humans review and merge.
No iteration loop: if the PR review surfaces design changes, you currently re-export from Claude Design and re-run
```
/ork:design-ship
```
. (See Bet B for the future drift-sync workflow.)
Single-bundle scope: one invocation, one bundle, one PR. Multi-bundle batches are not supported.

无自动合并：本技能仅创建PR；由人工评审并合并。
无迭代循环：若PR评审中提出设计变更，目前需从Claude Design重新导出并重新运行
```
/ork:design-ship
```
。（未来的漂移同步工作流请查看Bet B。）
单交付包范围：一次调用仅处理一个交付包，生成一个PR。不支持多交付包批量处理。

design-ship

Original

Translation

Design Ship

Design Ship

When to use

使用场景

Pipeline

工作流管道

Pre-flight

前置检查

Phase 1 — Import

阶段1 — 导入

Phase 2 — Cover

阶段2 — 覆盖测试

Phase 3 — Expect

阶段3 — 验证

Phase 4 — Create PR

阶段4 — 创建PR

Components

Components

Tokens

Tokens

Verification (
`/ork:expect`
)

Verification (
`/ork:expect`
)

Coverage delta (
`/ork:cover`
)

Coverage delta (
`/ork:cover`
)

Screenshots

Screenshots

Phase 5 — Update provenance

阶段5 — 更新溯源信息

Failure modes

故障模式

Composition

组件构成

NOT this skill's job

非本技能职责

Limitations

局限性

design-ship

Original

Translation

Design Ship

Design Ship

When to use

使用场景

Pipeline

工作流管道

Pre-flight

前置检查

Phase 1 — Import

阶段1 — 导入

Phase 2 — Cover

阶段2 — 覆盖测试

Phase 3 — Expect

阶段3 — 验证

Phase 4 — Create PR

阶段4 — 创建PR

Components

Components

Tokens

Tokens

Verification (/ork:expect)

Verification (/ork:expect)

Coverage delta (/ork:cover)

Coverage delta (/ork:cover)

Screenshots

Screenshots

Phase 5 — Update provenance

阶段5 — 更新溯源信息

Failure modes

故障模式

Composition

组件构成

NOT this skill's job

非本技能职责

Limitations

局限性

Verification (
`/ork:expect`
)

Verification (
`/ork:expect`
)

Coverage delta (
`/ork:cover`
)

Coverage delta (
`/ork:cover`
)