feat(claude-design): add 04-handoff-and-scope fence vs Anthropic design plugin
Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
This commit is contained in:
parent
2a851f0e12
commit
dc8bc99ee7
1 changed files with 157 additions and 0 deletions
|
|
@ -0,0 +1,157 @@
|
|||
# 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 | — | ✓ `/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 `/critique <path-or-URL>` to get a design critique
|
||||
- Run `/accessibility <path-or-URL>` for a WCAG audit
|
||||
- Run `/ux-copy <path-or-URL>` for copy review
|
||||
- Run `/research-synthesis` if the operator has user-research notes to synthesize
|
||||
- Run `/design-system <path-or-URL>` for design-system consistency check
|
||||
- Run `/handoff <path-or-URL>` for engineering-handoff guidance
|
||||
|
||||
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.
|
||||
|
||||
---
|
||||
|
||||
## 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.
|
||||
Loading…
Add table
Add a link
Reference in a new issue