claude-design/skills/claude-design-facilitator/references/04-handoff-and-scope.md

Handoff and scope fence

Last updated: 2026-05-17 | Verified: research/04-iteration-mechanics-recovery.md + research/05-anthropic-design-plugin-scope.md Status: Beta (Labs research preview) Captured-on date: 2026-05-16

This file documents two things: how Claude Design hands artifacts off to downstream tools (Claude Code, PowerPoint, PDF, Canva), and how this plugin (claude-design) fits next to Anthropic's official knowledge-work-plugins/design. The scope fence is load-bearing — getting it wrong duplicates Anthropic's command surface and adds nothing.

---

1. Handoff bundle contents

When the operator chooses Claude Code handoff as the destination, Claude Design produces a bundle containing — verbatim per https://anthropic.com/news/claude-design-anthropic-labs and https://support.claude.com/en/articles/14604416-get-started-with-claude-design:

• Machine-readable component spec — a JSON-shaped description of the components in the artifact, with names, props, and variants
• Design tokens — colors, typography, spacing, radii in token form (CSS variables or JSON tokens)
• Layout hierarchy — the page / screen structure as a tree
• Referenced assets — images, icons, fonts referenced in the artifact, bundled
• Standalone HTML + inline CSS + JS — a self-contained render that runs without Claude Design
• Per-state screenshots — visual snapshots of each interaction state (default, hover, active, disabled, focused)
• PM-annotated notes — annotations Claude Design surfaces about design decisions, edge cases, and trade-offs
• Stack / framework README — a guide to which framework conventions the artifact assumes (e.g., React + Tailwind, or vanilla HTML)

The bundle is generated once on export. It does not regenerate when the operator iterates the artifact further inside Claude Design — the operator must re-export to pick up changes.

Sources: https://anthropic.com/news/claude-design-anthropic-labs and https://support.claude.com/en/articles/14604416-get-started-with-claude-design.

---

2. Direction is one-way

The Design → Code handoff direction is one-way. Once the bundle is exported and the operator starts iterating in Claude Code (or any code editor), there is no return path to Claude Design. The component spec, design tokens, and standalone HTML continue to live in the code repository; Claude Design has no concept of "re-ingest from code".

If the operator wants to visit the visual surface again after engineering iteration, the only path is:

1. Screenshot the current Claude Code render
2. Open a new Claude Design session
3. Paste the screenshot as the starting visual reference
4. Brief Claude Design from scratch using layer-1-through-5 framework

This is lossy: the design tokens, component spec, and PM notes from the original bundle do not travel into the new Claude Design session. The new session inherits only what the screenshot communicates.

Operational consequences:

• Finalize visual decisions inside Claude Design before exporting. The Tweak panel and inline comments are free; chat turns inside Claude Design are budget-priced; engineering iteration in code is budget-free but the visual round-trip is one-way. Order accordingly.
• Export once, intentionally. Bundling everything in a single export (per Section 6 below) costs one chat turn; bundling screen-by-screen costs N turns and consumes budget faster.
• Plan for asymmetric revisit. When the engineering implementation diverges from the design intent and the operator wants a designer review, schedule that revisit as a fresh Claude Design session, not as an extension of the original session.

Practitioner consensus on this point is documented at https://claudefa.st/blog/guide/mechanics/claude-design-handoff (community source). Anthropic frames the same one-way property implicitly in the get-started article — the handoff is described as an export, not a connection.

---

3. Workflow recommendation

The recommended flow for any Claude Design artifact destined for engineering implementation:

1. Iterate visually in Claude Design until the artifact is shippable. Use Tweak panel and inline comments first; chat turns for structural and aesthetic changes.
2. Validate the destination format before exporting. If destination is PPTX, verify the text-as-text count (see Section 6 token cost trap). If destination is HTML standalone, render it in the target browser at the target viewport. If destination is PDF, check the interactive-element handling.
3. Export the full bundle once. Bundle all screens in one export, not per-screen. The token cost trap (Section 6) compounds with per-screen exports.
4. Iterate engineering inside Claude Code or the code editor. Use Claude Code's /edit and chat surfaces. Pull the design tokens from the bundle into the repository's styling layer.
5. For post-design design-quality work — critique, accessibility audit, UX copy review, design-system audit, engineering handoff guidance — install Anthropic's official plugin (Section 4 below).
6. If a visual revisit becomes necessary later, accept the one-way cost. Open a new Claude Design session against a screenshot; do not try to re-extend the original session.

This is the flow per Section 4's scope-fence reasoning: this plugin covers the upstream lifecycle; Anthropic's covers downstream.

---

4. Scope fence vs Anthropic's knowledge-work-plugins/design

Anthropic ships an official Claude Code plugin at https://claude.com/plugins/design (source: https://github.com/anthropics/knowledge-work-plugins). It is skill-driven, Apache 2.0 licensed (MIT-equivalent), and ships six slash-commands operating on existing artifacts (Figma URLs, screenshots, copy snippets).

The lifecycle-stage coverage map:

Lifecycle stage	This plugin (claude-design)	Anthropic's plugin (knowledge-work-plugins/design)
Idea ingestion	✓ Disambiguate surface, intent preset, audience	—
Intent-preset selection	✓ Eight presets, evidence-grade labelled	—
Prompt engineering	✓ Five-layer stack + per-preset patterns	—
Copy-paste delivery	✓ Composed prompt block	—
Iteration coaching	✓ Tweak / Comment / Chat cascade, session economics	—
Ship-readiness	✓ Operator-attested + recommend downstream tool	—
Critique	Routed via Phase 9 — coached, never performed	✓ design:critique
Accessibility audit	—	✓ /accessibility
UX copy review	—	✓ /ux-copy
Research synthesis	—	✓ /research-synthesis
Design-system audit	—	✓ /design-system
Engineering handoff	—	✓ /handoff

There is no functional overlap. This plugin produces prompts that go into Claude Design; Anthropic's plugin operates on artifacts that already exist. The split is clean by design — both plugins document the other as the lifecycle complement.

Forbidden command-name list. This plugin must NOT ship slash-commands with any of these names (with or without a claude-design: namespace prefix):

• /critique
• /accessibility
• /ux-copy
• /research-synthesis
• /design-system
• /handoff

tests/validate-plugin.sh assertion (h) enforces this mechanically. The rationale is collision-avoidance — if both plugins are installed and both ship /critique, command resolution becomes ambiguous and one or the other silently fails. The cleaner solution is: this plugin does not own those commands.

---

5. Recommended downstream tool

When the operator finishes the Claude Design lifecycle (artifact exists, exported, ready for review), surface the downstream tool installation as the next step:

claude plugins add knowledge-work-plugins/design

In a new Claude Code session with that plugin installed:

• Run design:critique <path-or-file-reference> to get a design critique
• Run design:accessibility <path-or-file-reference> for a WCAG audit
• Run design:ux-copy <path-or-file-reference> for copy review
• Run design:research-synthesis if the operator has user-research notes to synthesize
• Run design:design-system <path-or-file-reference> for design-system consistency check
• Run design:handoff <path-or-file-reference> for engineering-handoff guidance

These are plugin skills, addressed as plugin-name:skill-name. The bare /design-critique form also resolves as an alias. The plugin README's /critique shorthand does not match the live skill name and should not be relied on. Note also that none of these accept a generic web URL — a Claude Design artifact lives behind claude.ai authentication with no stable public address (https://support.claude.com/en/articles/9547008-publishing-and-sharing-artifacts), so the input is an exported file or a screenshot.

Sources: https://claude.com/plugins/design and https://github.com/anthropics/knowledge-work-plugins.

The plugin is Apache 2.0, free, and maintained by Anthropic. There is no commercial trade-off; it is the canonical downstream tool.

Phase 9 is the coached path into design:critique

Recommending the tool is the minimum. When the operator hits information-architecture, structural or copy problems that surface aesthetics cannot fix, the canonical path is Phase 9 — critique-iterate, documented in references/05-critique-iterate.md. Phase 9 walks four sub-phases: coach the export and the critique run (9a), consume the pasted output as untrusted reference data (9b), synthesize a re-prompt aimed at the one prompt layer that produced the problem (9c), and decide whether to loop or exit (9d). Each preset carries its own Critique-iterate hint block naming which critique sections dominate for that artifact type and where those findings route.

Phase 9 routes to design:critique; it never reimplements it. The critique is run by the operator in their own session, and the result is carried back by hand — Claude Code documents no mechanism for one skill to invoke another plugin's surface, so operator-as-bridge is the intended seam rather than a workaround. The scope fence in Section 4 is unaffected: this plugin still ships none of the six forbidden command names.

---

6. Token cost trap — bundle all screens in one export

Practitioner-documented failure mode: exporting screen-by-screen instead of bundling all screens in one export. The community-cited reference is token-budget-claude-design.md (cited in research/04 as one of the highest-leverage cost-management items).

The mechanism: each export turn passes the current artifact state through Opus 4.7 to produce the bundle. For an N-screen artifact, N separate exports run N separate bundle generations and burn N chat turns. Bundling all N screens in a single export runs one bundle generation against the cumulative state and burns one chat turn.

The bundling prompt pattern:

Generate the full export bundle covering all N screens of this artifact:
[screen 1: name], [screen 2: name], ... [screen N: name].
Include for each screen: HTML standalone, design tokens, component spec,
per-state screenshots, PM notes. Bundle as a single download.

Multi-screen artifacts (prototypes, slide decks, multi-page landing pages) benefit most from this discipline. Single-screen artifacts (a single dashboard, a single one-pager) are not affected because there is only one bundle to generate.

If the operator has already paid the per-screen cost and noticed mid-flight, the recovery is to abandon partial exports and run one final bundling export against the cumulative artifact state.

---

Sources

• https://anthropic.com/news/claude-design-anthropic-labs — Anthropic Labs launch, bundle contents
• https://support.claude.com/en/articles/14604416-get-started-with-claude-design — get-started, handoff bundle contents
• https://claude.com/plugins/design — Anthropic's official knowledge-work-plugins/design plugin
• https://github.com/anthropics/knowledge-work-plugins — source for the official plugin
• https://anthropic.com/engineering/harness-design-long-running-apps — design grading framing
• https://claudefa.st/blog/guide/mechanics/claude-design-handoff — community operational consensus on one-way direction

Re-research trigger: Anthropic announcing a two-way handoff primitive; knowledge-work-plugins/design adding or removing slash-commands; bundle contents changing materially; this plugin and Anthropic's plugin overlap emerging.