Design Workflow: Claude Code ↔ GitHub ↔ Claude Design

How a design need becomes shipped CSS/HTML, with as much of the loop automated as Claude Design’s actual integration surface allows. Tracked in issue #338 (Phase 4).

What can and cannot be automated

Verified in practice on the #322 pilot (PR #373), superseding what the launch docs implied:

Into Claude Design: manual only. Submitting a brief and assets requires a human in the claude.ai/design UI. This is the one remaining manual transport.
Out of Claude Design: automated. Claude Code’s DesignSync tool reads a Claude Design project directly (signed in via /design-login): get_project resolves the project from its share URL, list_files enumerates its files, get_file fetches contents (256 KiB per-file cap). No manual export step.
Share URLs are not fetchable over plain HTTP. claude.ai/design/p/... links are Cloudflare-protected — curl and WebFetch get a 403. The share URL is the project identifier handed to DesignSync, not a downloadable bundle. Do not burn time retrying HTTP fetches against it.
Inputs it accepts: file uploads (images/PDF/docs), screenshots, and linking a code repository (private-repo linking still unverified — the pilot used packet upload).
Available on Pro/Max/Team/Enterprise; usage shares the normal Claude limits.
Session persistence: verified — the standing project retained its files and chat context across the pilot’s multi-day iteration.

The loop below automates everything except one ~1-minute manual transport (packet in), at a clean seam so a future submission API can replace it without changing anything else.

The loop

GitHub issue (requirement)
      │
      ▼
[1] Claude Code: /design-request <issue#>        ← automated
      builds design packet, comments on issue
      │
      ▼
[2] Sean: drag packet into claude.ai/design      ← manual, ~1 min
      iterate there; inline comments/edits are the design review surface
      │
      ▼
[3] Sean: paste the project's share URL          ← manual, ~10 sec
      │
      ▼
[4] Claude Code: /design-implement <issue#> <url> ← automated
      import via DesignSync → translate → branch → lint/test →
      screenshots → PR linked to issue
      │
      ▼
[5] GitHub PR review (Sean + Copilot)             ← existing process
      code-level feedback → Claude Code fixes on the branch
      design-level feedback → Claude Code writes a delta brief → back to [2],
      same Claude Design session so its context carries forward

For small spot designs, skip Claude Design entirely: Claude Code mocks up HTML/CSS directly (as a Claude Artifact or a branch), Sean reviews in chat, then implement. Reserve the full loop for larger surfaces and visual exploration.

Step detail

[1] `/design-request <issue#>` — packet build

Reads the issue plus the design doc’s constraints, then assembles tmp/design_packets/<issue#>-<slug>/ (gitignored; regenerable) containing:

BRIEF.md — the design doc’s Paste-In Prompt narrowed to this surface: scope, hard constraints (custom CSS only, list rows, semantic OKLCh tokens, system fonts, localizable strings, EuRom5 contrastive patterns where relevant), and required outputs.
css/ — _global.css (tokens/layers) plus the stylesheets relevant to the surface.
markup/ — the current ERB partials for the surface.
screenshots/current/ — fresh signed-in captures of the target pages, taken via the Cuprite harness (see below), desktop and mobile widths.
screenshots/reference/ — the relevant subset of docs/features/immersive_redesign_screenshots/ (existing-* for current state, example-* for functional patterns — the brief must say the examples are functional references, not visual targets).

Zips the packet and posts a status comment on the issue (prefixed “Commented by Claude”): what’s in the packet, its path, and the exact next step.

[2] Into Claude Design (manual)

Drag the zip into a Claude Design session (reuse one standing “Immersive Design System” session so context accumulates rather than restarting each time — persistence verified on the pilot). Iterate using Claude Design’s inline comments and direct edits — that is the mockup review surface; no bespoke review tooling gets built.

[3] Hand over the project URL (manual, ~10 sec)

Paste the project’s share URL (claude.ai/design → Share) to Claude Code. No export needed — the URL only identifies the project.

[4] `/design-implement <issue#> <project-share-url>` — implementation

Imports the project via the DesignSync tool (get_project on the share URL → list_files → get_file); saves the design files to docs/design/returns/<issue#>-<slug>/ (committed — it’s the design-intent provenance for the PR).
Translates into app conventions rather than pasting the bundle’s CSS verbatim: semantic tokens, BEM-ish single-class selectors, ERB partials, icon() helper, locale keys for all strings.
Branches, implements, runs standardrb/erb_lint/tests, captures before/after screenshots via the harness, opens a PR linked to the issue with the screenshots and a pointer to the returns directory.

[5] Review on GitHub

Normal PR process. Claude Code addresses code-level comments on the branch. For design-level changes, it drafts a short delta brief (what to change and why, in the Paste-In Prompt’s voice) and the loop re-enters at [2].

Screenshot capture harness

Fresh current-state captures use the existing system-test infrastructure (ApplicationSystemTestCase: Cuprite + Chrome via BROWSER_PATH, fixture users for signed-in state, save_screenshot), wrapped as lib/tasks/design.rake + test/system/design_capture_test.rb (the test skips itself unless invoked through the task, so normal suite runs are unaffected):

bin/rails 'design:capture[/decks /admin/design_system/bridge]'
# -> tmp/design_captures/<slug>-desktop.png (1280) and <slug>-mobile.png (375)
# OUT=dir overrides the output directory; CAPTURE_USER=user signs in as a
# different fixture (default admin); port 3000 must be free; set BROWSER_PATH
# if Chrome isn't on the default path

Sources

https://www.anthropic.com/news/claude-design-anthropic-labs
https://support.claude.com/en/articles/14604416-get-started-with-claude-design
https://support.claude.com/en/articles/14604397-set-up-your-design-system-in-claude-design
https://support.claude.com/en/articles/14604406-claude-design-admin-guide-for-team-and-enterprise-plans