Claude Design ↔ Claude Code Workflow

1. Overview

EMS portal UIs are designed in Claude Design (web) and implemented in Claude Code (WSL, this repository). The two produce different artefacts at different stages, and both need shared context to stay coherent. This page defines the workflow that bridges them.

The workflow has three load-bearing pieces:

  1. A shared screen-naming convention — <prefix><NN>-<kebab-name> — used by both Claude Design’s project structure and the repo’s use-cases module, so a single key links design, spec, and implementation.

  2. Upstream structure: a use-case page per screen (or screen cluster), with actor / flows / API surface / design anchors. This is what gives Claude Design something concrete to design.

  3. Downstream handoff via Claude Design’s URL fetch: Claude Code retrieves the design at port time using the URL Claude Design emits — no manual copy-paste, no committed design files in the repo.

This document is greenfield as of 2026-04-24 — no established workflow to describe. First real uses will validate (or revise) it; treat as a living document.

See also: Portal Pattern, Dev-Mode UI Awareness.

2. The Two Tools, Side by Side

Dimension Claude Design Claude Code

Environment

Web app (browser)

CLI in WSL / local terminal

Input

Prose briefs + context blocks pasted by the user

Full repository, project memory, tool use (file read/write, shell, git, web fetch)

Output

HTML + CSS mockups, JSX samples illustrating behaviour, served via a stable design URL

Angular components, tests, commits, design-journal entries, PRs

State

Project-scoped folder structure inside Claude Design; persists across sessions there

Versioned in git; durable across sessions in this repo

Best at

Iterating on visual structure, layout variations, interaction patterns

Integration with existing code, refactoring, end-to-end feature slices

Blind spots

Repo layout, existing Angular patterns, EMS domain specifics

Visual-design intuition; whether a layout feels right

Use Claude Design to answer "what should this screen look like and how should it behave"; use Claude Code to answer "how does this fit into the codebase and work end-to-end".

3. Screen Naming Convention

Every screen (or tightly-related screen cluster) has a stable identifier of the form <prefix><NN>-<kebab-name>:

Prefix Scope Examples

S

Super-tenant admin / configuration screens (cross-tenant, platform-level)

S01-super-tenant

T

Tenant-specific admin / configuration screens (within one tenant’s scope)

T01-tenant-admin

E

Event-specific screens

E01-event-overview, E02-event-participants, E03-event-setup, E04-event-results

M

Membership-specific screens

M01-membership-types, M02-membership-members

A

Affiliation-specific screens

A01-…​

C

Common — anything that doesn’t fit the above (structural, landing pages, cross-cutting components)

C01-structure, C02-number-capture

The same identifier appears in three places:

  1. Claude Design project: as a folder name (E02-event-participants/).

  2. Use-cases Antora module in this repo: as the page filename (E02-event-participants.adoc).

  3. ADO work item title prefix and tag.

A screen ID never gets renamed once issued, even if the cluster narrows or expands. If a use case is split, the new ones get fresh IDs at the next available number; the old ID is retired or kept as a parent.

NN is two digits with leading zero. Numbers are allocated sequentially per prefix; gaps are fine.

4. Upstream Structure: Use Cases

A use-case page is the canonical text spec for a screen. It tells Claude Design what to design and Claude Code what to implement, in the same words.

4.1. Module location

docs-event/modules/use-cases/
├── nav.adoc
├── pages/
│   ├── index.adoc
│   ├── C01-structure.adoc
│   ├── C02-number-capture.adoc
│   ├── E01-event-overview.adoc
│   ├── E02-event-participants.adoc
│   ├── E03-event-setup.adoc
│   ├── E04-event-results.adoc
│   ├── M01-membership-types.adoc
│   ├── M02-membership-members.adoc
│   ├── S01-super-tenant.adoc
│   └── T01-tenant-admin.adoc
└── partials/
    └── use-case-template.adoc

Flat structure — the prefix in the filename is the grouping signal; nav.adoc provides the visual hierarchy.

4.2. Use-case page structure

Use the template (stored at partials/use-case-template.adoc for include:: consistency). Each page covers one screen ID; multi-screen flows reference each other via xref.

= [E02] Event Participants
:status: design-todo|in-design|handoff-ready|implementing|done
:design-url: https://api.anthropic.com/v1/design/h/<hash>?open_file=E02-event-participants%2F...
:related-ado: US #NNN
:related-journal: design-journal/2026-MM/event-participants.adoc

== Summary

[2-3 sentence orientation — what this screen does for the user, where it sits in the journey]

== Actor & Context

*Actor*: <role — staff admin, event organiser, public registrant, etc.>
*Frequency*: <how often the actor uses this>
*Precondition*: <auth state, data state, navigation context required to enter>
*Entry point*: <how the actor arrives — link from X, button on Y, deep link>

== Main Flow

. <step 1>
. <step 2>
...

== Alternative Flows

* *AF-1*: <when X happens, …>
* *AF-2*: <error path>

== Acceptance Criteria

* [ ] <observable outcome 1>
* [ ] <observable outcome 2>

== API Surface

[cols="2,3",options="header"]
|===
| Call | Purpose
| `GET /api/event-participants?eventId={id}` | Load list
| `POST /api/event-participants` | Create
| ...
|===

== Out of Scope

* <what this screen explicitly doesn't do>

== Design Anchors

* xref:architecture:portal-pattern.adoc[Portal Pattern]
* xref:common-design:UIDesignPrinciples.adoc[UI Design Principles]
* design-journal/YYYY-MM/<related>.adoc — if this iterates a prior design

== Notes

[any open questions, design hypotheses, integration concerns]

The :design-url: attribute carries the Claude Design URL (filled in once the first design session has produced a stable artefact). This is what Claude Code WebFetches at port time — see Design → Code Handoff.

4.3. Generation approach

  1. Hand-written, mostly. Use cases are domain-specific; no script writes them well.

  2. Endpoint reference can be seeded by a small script that walks admin-service/src/main/java/…​/web/rest/ for @RestController + @Operation and produces a per-bounded-context endpoint catalogue. Use this catalogue when filling in the API Surface section. Keep the generator simple — it produces an endpoint list as a partials/api-catalogue.adoc, included into use-case pages on demand. Defer until enough use cases exist to feel the pain of repetition.

4.4. ADO mirroring

Each use-case page corresponds to an ADO work item with the same title ([E02] Event Participants). The work item carries the phase tag — see Session Ownership Discipline.

5. Claude Design Session Kickoff

At the start of a design session, paste:

  1. The use-case page in full — it is the brief.

  2. Architecture context — the page(s) relevant to the screen (auth-related → Session-Held JWT, multi-tenant → Portal Pattern § tenant resolution, anything that re-renders on data change → SPA Cache & CDN Strategy).

  3. Design principles — common-design/pages/UIDesignPrinciples.adoc.

  4. Prior design lineage — if Claude Design’s project already has a folder for this screen ID with HTML/JSX, it picks that up automatically. Paste any out-of-Claude-Design references (other portals' equivalent screens, design-journal threads).

  5. Known constraints — multi-tenancy implications, responsive floor, target component vocabulary (PrimeNG + ng-bootstrap on the Angular side).

Total paste: aim for under 3000 words. Claude Design has context limits and degrades with noise. Paste what is load-bearing, leave the rest in the repo for the user to follow up.

What NOT to paste:

  • Anything from .claude/projects/…​/memory/ — that is Claude Code’s persistent memory, not useful in design and may contain sensitive details (API keys, DB credentials).

  • Off-topic architecture pages.

  • Implementation code from the legacy admin-ui — admin-ui is pre-pattern; carrying its visual decisions forward undermines the redesign goal.

6. Design → Code Handoff

Claude Design has a built-in handoff feature. After a session that produces a stable design, the user clicks Share in Claude Design. A handoff message is copied to clipboard. The user pastes that message into a Claude Code session.

6.1. Recognising the share-paste pattern

When a user message starts with "Fetch this design file, read its readme, and implement the relevant aspects of the design." followed by a https://api.anthropic.com/v1/design/h/…​; URL and an Implement: line, Claude Code is being asked to run the handoff protocol below. Treat this exact phrase as a trigger pattern.

6.2. Two share variants

Variant Format When the user uses it

File-specific (preferred)

 
Fetch this design file, read its readme, and implement the relevant aspects of the design.
https://api.anthropic.com/v1/design/h/<hash>?open_file=<URL-encoded folder>%2F<URL-encoded filename>
Implement: <folder>/<filename>

Default. User shared from a specific file open in Claude Design. Names the focal file. Aligns with the one-use-case-at-a-time workflow.

Project-level

 
Fetch this design file, read its readme, and implement the relevant aspects of the design.
https://api.anthropic.com/v1/design/h/<hash>
Implement: the designs in this project

User shared from the project root. No open_file= parameter. Implement: says "the designs in this project". Useful for whole-project surveys (rare).

Both variants return the same gzipped tarball — the entire project archive. The difference is only the Implement: directive: file-specific tells Claude Code to focus on one screen; project-level says to consider the project as a whole.

6.3. Examples (real, observed during 2026-04-27 round-trips)

# File-specific (focal: C01 Structure)
Fetch this design file, read its readme, and implement the relevant aspects of the design.
https://api.anthropic.com/v1/design/h/X_oDgDmZJFD44gRpuWfxrg?open_file=C01-structure%2FStructure.html
Implement: C01-structure/Structure.html

# File-specific (focal: C03 Public Landing)
Fetch this design file, read its readme, and implement the relevant aspects of the design.
https://api.anthropic.com/v1/design/h/qfhdiErWlyK7H2ZWXBhyhA?open_file=C03-public-landing%2FPublic+Landing.html
Implement: C03-public-landing/Public Landing.html

# File-specific (focal: E05 Events Control Centre — first forward round-trip,
# brief-driven design pass)
Fetch this design file, read its readme, and implement the relevant aspects of the design.
https://api.anthropic.com/v1/design/h/ZGNhPMg2Rg9OnC8wv5geQw?open_file=E05-events-control-centre%2FEvents+Control+Centre.html
Implement: E05-events-control-centre/Events Control Centre.html

# Project-level
Fetch this design file, read its readme, and implement the relevant aspects of the design.
https://api.anthropic.com/v1/design/h/CAR4pymaouKfw-ZORXgPzw
Implement: the designs in this project

6.4. Claude Code’s port-time protocol

  1. WebFetch the design URL. The URL returns a gzipped tarball (application/gzip, ~100KB typical) of the entire Claude Design project — not just the named file. Claude Code’s WebFetch summarizer cannot read binary content, so the tarball gets saved to a tool-results path and then decompressed locally (e.g. tar -xzf <path> -C /tmp/<screen-id>-design).

  2. Read the bundle README at event-and-membership-admin-portal/README.md. Claude Design ships a top-level "coding agents read this first" with handoff guidance — read it, it tells you what to read next.

  3. Read the project README at event-and-membership-admin-portal/project/README.md for the locked structural decisions and folder layout.

  4. Read the screen folder’s README at event-and-membership-admin-portal/project/<screen-id>/README.md for screen-specific intent and decisions.

  5. Read the named HTML file — the markup itself, plus any sibling CSS / JSX in the folder.

  6. Optionally read chats/ if intent is unclear — the folder contains the back-and-forth transcripts between the user and Claude Design that produced the design. Long, but where the why lives.

  7. Open the matching use-case page in this repo — docs-event/modules/use-cases/pages/<screen-id>.adoc. Update the :design-url: attribute if it has changed.

  8. Identify the Angular module home — admin-portal-app/src/app/features/<context>/ based on the screen-ID prefix:

    Prefix Module

    S

    features/super-admin/

    T

    features/tenant-admin/

    E

    features/events/

    M

    features/membership/

    A

    features/affiliation/

    C

    app/shared/ or core/ depending on whether it’s a screen or a building block

  9. Create the component — ng generate component features/<context>/<screen-id-kebab> (or manually).

  10. Port HTML → component template:

    • Copy the design HTML.

    • Replace static text with {{ …​ }} interpolation.

    • Replace static lists with *ngFor / @for.

    • Replace conditional regions with *ngIf / @if.

    • Bind form elements with [formControl] / [formGroup].

    • Translate className → class if anything came from the JSX rather than the HTML.

  11. Port CSS → component styles — drop into <screen>.component.scss. Audit for unscoped global selectors (Angular view encapsulation handles most). Remove resets duplicated by @ems/shared-ui base styles.

  12. Port JSX behaviour → TypeScript class:

    • The JSX file shows state shape, event handlers, conditional render logic. Translate:

    • State (useState) → signal() or BehaviorSubject<T> on the component.

    • Effects (useEffect) → effect(), lifecycle hooks (ngOnInit, ngOnDestroy), or subscribe() on a service stream.

    • Event handlers → component methods called from the template ((click)="handle()").

  13. Wire API calls via the generated admin-service TypeScript client (see OpenAPI Contract Flow). Do not hand-write HttpClient.

  14. Tests — component spec, harness loader for interaction, fixture data shaped from the use-case API surface.

  15. Run locally — npm start, exercise the flow.

  16. Commit — implementation + the :design-url: update + a phase-tag transition (see below). One PR per use case unless multiple are tightly coupled.

6.5. Why no committed design files

The design URL is the canonical reference. Committing HTML/CSS/JSX into the repo creates a duplicate that drifts from the live Claude Design state. Three trade-offs make the URL approach right:

  • Lineage stays single-source-of-truth in Claude Design.

  • Git diffs stay focused on Angular implementation, not on regenerated mockup HTML that does not influence runtime behaviour.

  • WebFetch is cheap — re-fetching at every port iteration costs nothing.

Trade-off accepted: if the URL session expires or the user loses access to that Claude Design project, the design is unrecoverable from the repo alone. Observed mitigation: regenerating the handoff URL from Claude Design produces a fresh durable URL (the URL hash is per-export, not per-project — a new export can replace an old expired URL). Update the use-case page’s :design-url: whenever a fresh export happens.

If the URL approach proves insufficient under real adversarial conditions, the fallback is a critical-design snapshot: commit the tarball as admin-portal/design-source/<screen-id>-<YYYYMMDD>.tgz at major milestones. Defer until needed.

6.6. Important: URL access patterns observed in practice

  1. One fetch returns the whole project, not just the named file. The ?open_file=… parameter is a hint to a UI client about which file is the focal point, but the response payload is the complete project archive. Cache the decompressed archive locally and read other screens' files without re-fetching.

  2. URLs do expire — within hours. A URL produced by an earlier handoff may return 404 once that session has been replaced by a newer export. Observed validity in practice (2026-04-27): less than 8 hours between original export and 404. Always use the most recent URL the user provides. If a URL returns 404, ask the user to re-export from Claude Design and provide the fresh URL — do not retry the same hash. The URL is not stable across exports.

  3. Authentication. The URL works without an interactive browser session — it is signed with the hash. The hash itself is the bearer credential. Treat URLs as moderately sensitive; do not check them into public artefacts beyond the use-case page in this repo.

6.7. When the design doesn’t port cleanly

If the markup uses idioms that don’t translate to Angular gracefully (deeply-nested template fragments, contenteditable without form bindings, custom-element prototypes, layouts that fight Angular’s view-encapsulation model), do not hack the HTML to fit. Pause the port, flag in the PR description, re-open Claude Design with the constraint added to the brief, accept the new design, then continue. Quietly reworking the design in code loses the lineage.

7. Session Ownership Discipline

Two sessions (one Claude Design, one Claude Code) working on the same screen ID at the same time produce drift. Phase tags on the ADO work item track who owns the work right now.

Phase tag Meaning

design-todo

Use-case page exists; no design session yet. Claude Design can pick up; Claude Code does not implement.

in-design

Claude Design is iterating. The design URL exists but may not be stable. Claude Code does NOT touch this screen’s Angular.

handoff-ready

Design is signed off; design URL stable. Use-case page’s :design-url: updated. Ready for Claude Code to implement.

implementing

Claude Code is porting + integrating. Claude Design does NOT iterate (unless the user explicitly re-opens by moving the tag back to in-design).

done

Merged + deployed. Both tools are done with this screen.

Tag transitions are explicit comments on the ADO work item. Example:

Design session 2026-05-02 complete. Design URL stable at:
https://api.anthropic.com/v1/design/h/rz3ia-AFw1WLiyq8x8A2OQ?open_file=E02-event-participants%2F...
Moving E02 to handoff-ready.

7.1. When the user is operating both tools sequentially

Most common today: open Claude Design, iterate, settle, then open Claude Code to implement. Phase tags are the durable record; in the moment, the user has full context.

7.2. When implementation reveals a design issue

It happens. Angular’s view encapsulation surfaces a layout assumption the mockup didn’t foresee; a responsive edge case shows up; a flow’s step 3 needs to go before step 2.

  1. Pause implementation. Phase → in-design.

  2. Open Claude Design with the current state — the screen ID’s folder is already there.

  3. Settle on the revision. Claude Design emits a fresh handoff URL.

  4. Update :design-url: in the use-case page.

  5. Phase → handoff-ready → implementing. Continue porting.

Do not iterate the design inside Angular templates. The repo’s Angular code is downstream of the design URL; reversing that direction breaks the protocol.

8. Memory Coordination

This repository has Claude Code memory under .claude/projects/-home-christhonie-dev-ems/memory/ — persistent across sessions, rich with decisions and references. Claude Design does not share this memory.

Item Lives in Carries to Claude Design?

Architecture decisions (portal pattern, token exchange, tenant model)

docs-event/modules/architecture/pages/

Paste the page relevant to the screen.

Design decisions (journal entries)

design-journal/

Paste the thread if the screen is iterating on prior design.

Use-case spec

docs-event/modules/use-cases/pages/<screen-id>.adoc

Paste in full — this is the brief.

Design principles / tokens

docs-event/modules/common-design/pages/UIDesignPrinciples.adoc

Paste every session; small and always relevant.

Claude Code’s auto-memory

.claude/projects/…​/memory/

No. Internal Claude Code context, not useful in design.

Environment / credentials

memory + secrets + values files

Never. Web tools and secrets do not mix.

When a Claude Design session produces a significant decision beyond layout (component structure, interaction pattern, multi-screen relationship), record it in:

  • The use-case page itself if it’s screen-specific.

  • A new design-journal entry if it’s cross-cutting (e.g. "list-screen pagination pattern" applying to all 02- style screens).

  • UIDesignPrinciples.adoc if it gets elevated to a project-wide convention.

The next Claude Design session picks up the decision via the paste-in protocol. Without this step, the decision dies with the session.

9. First-Use Checklist

Before opening Claude Design for the first session under WS2:

  • Use-case page exists for the screen ID and is filled out per the template.

  • Architecture pages identified and ready to paste.

  • Design principles page ready to paste.

  • ADO work item exists with design-todo (will move to in-design at session start).

  • Screen ID matches Claude Design’s folder name exactly.

After the design session:

  • Use-case page’s :design-url: updated to the latest stable URL.

  • Phase tag moved to handoff-ready.

  • Any cross-cutting decisions captured (use-case page, design journal, or principles doc).

Before opening Claude Code to port:

  • Phase tag is handoff-ready.

  • Use-case page is current (acceptance criteria still match Claude Design’s output).

  • Claude Design’s handoff message ready to paste into Claude Code.

After porting:

  • Implementation merged.

  • Phase tag moved to done.

  • Workflow doc updated with any friction encountered.

10. What This Document Is Not

  • Not a Claude Design product manual. Claude Design is an Anthropic web product; its product docs live there. This page assumes familiarity.

  • Not a substitute for visual design conventions. See common-design/pages/UIDesignPrinciples.adoc.

  • Not Angular-specific. The S/T/E/M/A/C convention and use-case template apply regardless of UI stack; only the port-step targets are Angular-flavoured.

  • Not Claude-specific in principle. If we later use a different design tool (Figma, v0, another AI tool), the screen-naming convention and use-case structure still apply. The handoff section becomes tool-specific.

11. Living Document

First validated use: TBD. Revisit after the first 3-5 real cycles. Open questions to resolve in practice:

  1. Paste-in word budget — is ~3000 words the right ceiling? Session degradation may push us lower; track which paste compositions produced the cleanest first design.

  2. JSX → Angular translation patterns — are there 2-3 repeating patterns (state + handlers + conditional render) that deserve named migrations? Capture once they show.

  3. Snapshot policy — does the URL-only handoff hold under real adversarial conditions (URL invalidation, lost project access)? If a snapshot becomes necessary, formalise.

  4. Endpoint catalogue generator — when there are 5+ use cases per bounded context, build the @RestController walker. Not before.

12. Reference

File Role

Use Cases

The use-cases module — one page per screen ID, this is what feeds Claude Design

docs-event/modules/use-cases/partials/use-case-template.adoc

Canonical use-case template for include:: re-use

admin-portal-app/src/app/features/<context>/

Where Angular implementations land per S/T/E/M/A/C prefix

13. Related Documentation

14. Change History

Date Change

2026-04-24 (revised)

Reframed around Claude Design’s URL-based handoff (fetch on demand, no committed design files). Renamed "Feature Inventory" to "Use Cases" throughout. Adopted the <S|T|E|M|A|C><NN>-<kebab-name> screen-ID convention shared with Claude Design’s project structure.

2026-04-24

Initial draft. Greenfield — no prior workflow to codify.