[FEATURE] Design Contract — a continuity bridge between Claude Design and Claude Code

Preflight Checklist

• [x] I have searched existing requests and this feature hasn't been requested yet
• [x] This is a single feature request (not multiple features)

Problem Statement

Claude Design draws and iterates the UI. Claude Code builds the backend and wiring. Nothing durable connects them. Every session starts cold, the handoff is lossy (screenshots, prose), and when a DTO or endpoint changes, the design silently goes out of sync.

The fix is a pattern your users already trust: give the UI↔backend slice the same thing a GitHub Issue gives a code task — a persistent, referenceable, stateful unit of work. We call it a Design Contract: a versioned file in the repo that both agents read and write, that flags drift, and that any surface can reopen by a stable handle.

It's a small, low-risk surface (a static artifact — no runtime LLM dependency) that multiplies the value of two flagship products at once.

The real problem

UI-plus-backend projects run on an implicit contract: the UI expects certain fields, states, and bindings; the backend must supply them. Today that contract lives in someone's head and in ephemeral chat. Four failure modes follow:

1. Cold starts. Each new Design or Code session rebuilds context from scratch. Loading/error/empty states decided in the design never travel to the code, and vice versa.
2. Silent drift. A renamed DTO field or reshaped endpoint never reaches the design. The UI keeps targeting a contract the backend no longer honors.
3. Lossy handoff. Design → Code today is a screenshot or a paragraph. The structured part — bindings, states, data dependencies — is lost and re-derived by hand.
4. No referenceable unit. There's no "continue the checkout flow" that reopens the full context of that slice.

Proposed Solution

1. The artifact — Design Contract. A git-tracked file (design/<slug>.contract.json + a rendered .md for review) that captures the coupling surface, not the pixels:

• Components & states — variants and required states (idle / loading / error / empty / partial / success).
• Data bindings — for each data-bound element: name, type, nullability, format.
• Backend dependencies — endpoints, DTOs/ViewModels and their expected shapes.
• Interaction spec — actions, commands (MVVM: ICommand, CanExecute), navigation, side effects.
• Provenance — origin commit/hash per side, to detect drift.

The contract is the source of truth; canvas and code are projections of it.

1. Bidirectional sync. Design edits update the contract and mark new backend requirements; Claude Code validates code against it and flags drift when a DTO/endpoint/ViewModel diverges. Changes surface as a reviewable diff — never applied silently.

1. Stable handle. A durable id (design/checkout-flow) reopens full context anywhere: claude design open checkout-flow in the CLI; canvas + code side by side in Desktop/Cowork. Continuity anchored in a versioned artifact, not in chat history.

Productivity & time gains

These are the concrete wins. Magnitudes are illustrative, but the categories are real and recurring on every full-stack iteration:

1. No re-explanation tax. Each session today opens with minutes of restating the data shape, states, and intent. The contract makes that load instant. ~5–15 min saved per session resumed.
2. Handoff goes from manual to free. Building a structured spec by hand (the screenshot-plus-prose-plus-cleanup ritual) collapses into "the contract is the handoff." ~15–30 min saved per Design→Code transfer.
3. Drift caught at author time, not at runtime/QA. A nullability or shape mismatch found while coding costs minutes; the same bug found in QA or production costs hours and a context switch. Shifts an entire class of integration bugs left.
4. No duplicated derivation. Bindings and states are authored once and consumed by both sides, instead of being re-inferred in the design and again in the code. Eliminates one full pass of redundant work per screen.
5. Fewer rework loops. The design↔implement↔mismatch↔redesign cycle is the expensive one. A shared contract removes the "mismatch" leg for most changes. Typically saves 1–2 round-trips per feature.
6. Cross-surface continuity. Resume on CLI, Desktop, or Cowork without rebuilding mental state — the handle restores it. Removes context-rebuild cost on every surface switch.
7. Compounding accuracy. Generated ViewModels and bindings land aligned to the design on the first try more often, so less of the agent's output is discarded — better tokens-to-shipped-code ratio, which is also a product-quality and cost win for Anthropic.

Alternative Solutions

Alternatives considered:

• Manual specs (.uispec.json + Markdown export): workable, but outside the agents' loop — hand-curated on every handoff, no automatic drift detection.
• Screenshots / prose: lose all structure (bindings, states, dependencies); not reproducible.
• Chat context only: ephemeral, not versionable, not referenceable, doesn't cross surfaces.

Priority

High - Significant impact on productivity

Feature Category

Interactive mode (TUI)

Use Case Example

Example flow (MVVM / .NET):

1. In Claude Design, I lay out an order screen with loading / error / empty / success. Design emits design/order-detail.contract.json with bindings (OrderId: string, Total: decimal, Items: OrderLine[]) and dependency GET /orders/{id} → OrderDto.
2. I commit. The contract travels with the repo.
3. Days later, in Claude Code (CLI), I ask for OrderDetailViewModel. It reads the contract and generates a ViewModel and bindings already aligned to the designed states — error and empty included.
4. The backend changes: OrderDto.Total becomes decimal?. Claude Code detects the drift and flags it — the UI didn't plan for a null total. I decide: add a state (back to Design) or handle it in the ViewModel.
5. Anytime, claude design open order-detail reopens everything with intact context.

Additional Context

_No response_