Claude Design Handoff Rules

Updated: 2026-07-23

This document describes only the workflow between Codex and Claude Design.

The single source of truth for the functional design contract is:

• docs/process/claude-free-design-contract.md

The transfer-channel doctrine (what counts as normative input for Codex wiring) is governed by:

• docs/process/design-codex-transfer-contract.md

Do not duplicate the contract here. If a hook, state, slot, field, or action rule changes, update docs/process/claude-free-design-contract.md only.

The functional requirements brief for screen flow, inputs, actions, navigation, and states is archived (historical reference only — the living sources are src/react/contracts/designContract.ts and docs/contracts/*-props.md):

• docs/archive/claude-functional-requirements.md

Branch and ownership rules live in:

• docs/process/branch-workflow.md

Claude Design work should normally happen on claude/ui and stay inside the UI ownership boundary described there.

The boundary is responsibility-based: Claude owns the visual surface; Codex owns production behavior and wiring. Codex may therefore make a minimal binding change inside src/react/ui/** when it preserves the approved design. The canonical R&R and preview boundary are in docs/process/claude-free-design-contract.md under “R&R: Visual Design vs. Functional Integration”.

Role Split

Claude Design's delivered surface is the visual UI source of truth. Functional state transitions and production behavior follow the agreed contracts. Codex must not reshape the surface to fit the previous app structure.

Codex owns:

• backend functions and service adapters
• app state needed to support Claude's flow
• data hierarchy
• Supabase persistence
• calculations and tests
• controlled inputs, search/filter/IME, navigation, callbacks, async behavior, and all production wiring without changing Claude's visual design

Claude Design owns:

• visual flow and screen choreography
• layout
• composition
• typography
• spacing
• component shape
• mobile and desktop UI structure
• CSS class names and visual styling
• framework choice for the design surface. If Claude ships React, the app surface should use React.

Codex To Claude

Codex should send Claude:

• target screen
• required product flow and action semantics
• app states
• data shape
• dynamic slots and lists
• required contract markers from docs/process/claude-free-design-contract.md
• relevant screen contracts from docs/contracts/*-props.md
• stress cases such as long names, many sets, empty data, and large numbers
• current functional constraints only when they affect behavior

Codex should not prescribe:

• visual choreography or composition
• exact spacing
• card shapes
• color taste
• typography scale
• desktop/mobile composition
• static fixture HTML/CSS that implies a preferred layout
• current index.html or app CSS as the visual baseline
• screenshots or skeletons as mandatory structure unless the user explicitly approved that direction

If Codex must mention current HTML/CSS for implementation context, label it as an integration target only, not as a design reference.

Claude To Codex

Claude should send complete replacement design artifacts:

• screen HTML, component HTML, or React components
• screen-scoped CSS
• state notes
• responsive notes
• preserved contract markers
• a preview state matrix and visual verification notes

Claude previews may include fixtures and mock callbacks to demonstrate visual states and intent emission. They must not become alternate implementations of production search, persistence, auth, RPC, canonicalization, or calculations.

Previews and fixtures exist only in Claude Design's local environment. They are not in this repository, never part of the delivery scope (src/react/ui/** + docs/contracts/**), and the courier strips them if a zip accidentally includes them. Behavior and state-selection rules transfer only through the props contract documents (docs/process/design-codex-transfer-contract.md).

Claude should not send CSS patches that depend on previous layout CSS staying alive. Claude may ignore the current DOM structure, wrapper hierarchy, presentation classes, and spacing system.

Codex Integration

When Codex applies Claude design:

1. Identify the screen root.
2. Replace the previous screen surface instead of layering patches.
3. Preserve or adapt only the functional boundary needed for data/auth/storage.
4. Remove previous screen-specific CSS that no longer applies.
5. Keep Claude's visual flow and composition unchanged unless the user explicitly changes the product direction.
6. Add backend/service functions around Claude's app rather than rewriting Claude's components for the old architecture.
7. Make the smallest necessary binding change inside the UI component when a controlled prop, callback, IME event, or semantic marker cannot be connected from the container alone; preserve layout and styling exactly.

Container Merge Rule

src/react/app.jsx is the React app container, not a design surface. Claude Design should not edit it directly in normal UI work, but Claude UI changes often require Codex to wire new props, callbacks, route state, and data hydration there.

When app.jsx conflicts during a merge:

• Treat main as the source of truth for functional fixes, backend wiring, auth, persistence, tests, and data loading.
• Treat the design branch as the source of truth for the latest approved Claude UI-flow and required component props/callbacks.
• Do not choose either side wholesale. Compose them.
• Do not alter the visual design in src/react/ui/** while resolving container conflicts. Minimal functional bindings are allowed under the canonical R&R; visual conflicts stay with Claude Design.

The detailed Korean policy lives in docs/process/branch-workflow.md under "React Container Merge Policy".

Claude Design Start Prompt

The following is a copy-ready task preamble. Append the target screen, props contract, required states, and stress cases after it.

먼저 docs/process/claude-free-design-contract.md의
“R&R: Visual Design vs. Functional Integration”과 대상 화면의
docs/contracts/*-props.md를 읽어줘.

너는 화면의 시각 디자인을 소유해. layout, markup composition, CSS,
typography, spacing, responsive structure, animation, 그리고 loading/empty/
error/pending/selected 상태가 어떻게 보이는지를 자유롭게 설계해줘.

실제 기능 배선은 Codex가 소유해. production search/filter/IME,
canonical ID, navigation, auth, persistence, RPC, data merge, domain 계산을
screen component나 preview에 구현하지 말고, agreed props와 callbacks로
값을 받고 user intent만 올려줘.

preview에서는 fixture와 mock callback으로 모든 시각 상태와 intent 발생을
시험해도 돼. 단, preview 전용 adapter는 fixture/preview 경로에 격리하고
production app에서 import되지 않게 해줘. preview 통과는 시각 상태와
contract 확인이고, 실제 기능 및 회귀 테스트는 Codex가 맡아.

전달물에는 component/CSS, preserved props·callbacks·markers, responsive
notes, preview state matrix, long/empty/loading/error stress 확인 결과를 포함해줘.