bilel salem

Posted on May 6

From Prompt to Pull Request: Using Claude Design, Claude Code, and GitHub Together

#ai #github #webdev #productivity

Why this matters

For years, the design-to-engineering handoff has been the most expensive translation step in product work. A designer mocks something up in Figma. An engineer rebuilds it in React, makes a dozen small judgment calls about spacing and states the design didn't cover, and ships something that's kind of the same. Two weeks later, the designer notices the buttons are 2px off and the empty state is missing entirely.

Anthropic shipped Claude Design to collapse that gap. It's a design tool that talks to a coding agent (Claude Code) that talks to your repo. Same model family at every step — no JPEGs being thrown over a wall.

This article walks through the full pipeline:

Building a prototype in Claude Design
Handing it off to Claude Code
Wiring the whole thing to GitHub so PRs get opened automatically

If you've already got a Pro/Max/Team/Enterprise Claude subscription, you have access. Let's go.

What Claude Design actually is

Claude Design lives at claude.ai/design and is a separate surface from the regular Claude chat. It's part of Anthropic Labs (research preview), powered by Claude Opus 4.7, and shipped publicly in mid-April 2026.

The mental model: you describe what you want in plain language, Claude renders it on an interactive canvas as real HTML/CSS/JS, and you refine it through a mix of chat, inline comments, direct edits, and "tweak knobs" — sliders for things like spacing, color, and corner radius that you can attach to any property of the design.

A few things to know up front:

Everything is code under the hood. Designs are generated as code, not pixels. That's why the handoff to engineering works.
Outputs include slides, landing pages, prototypes, mobile app mockups, and full design systems. It's not just for screens.
Exports are flexible. ZIP, PDF, PPTX, standalone HTML, Canva (via partnership), share URLs (view/comment/edit), and — most importantly — handoff to Claude Code.
It has its own usage limits. As of the research preview, Claude Design's quota is independent of your regular Claude chat usage.

Step 1 — Set up your design system

The single biggest factor in output quality is your design system. Claude Design without a design system gives you generic, AI-flavored output. Claude Design with a real design system gives you something that looks like it belongs to your product.

You have four ways to set one up:

Generate one from scratch by uploading brand assets, style guide snapshots, or even just inspiration images. Claude will extract colors, typography, spacing, and component patterns.
Upload an existing design system as a folder of components, tokens, or a Figma .fig export.
Link a GitHub repo so Claude reads your real components and tokens directly from code.
Pick an open-source design system (shadcn/ui, Material, etc.) as your starting point.

Then, in your organization settings, open the design system, refine it via the Remix chat panel on the left, and flip the Published toggle on. Once published, every new project in that workspace inherits it automatically.

A practical tip: when extracting from brand assets, include real finished work — a live landing page, a marketing site, a real shipped screen. A color palette and a logo aren't enough. Brands have feel, and feel comes from finished work.

Step 2 — Build the prototype

Once your design system is in place, you start a new project and describe what you want. The prompts that work best are specific about scope and structure:

"Design a settings page for a SaaS dashboard with a left sidebar nav (Account, Billing, Notifications, Integrations), a main content panel where each section is expandable, and a sticky save bar at the bottom."

"Map out the flow for a user upgrading from free to paid: dashboard upgrade prompt → plan comparison → payment form → confirmation → updated dashboard with premium features unlocked. Generate each screen in context."

"Build a landing page hero in two variations — one feature-led, one outcome-led — so I can A/B them."

Claude renders the result on the canvas and you start iterating.

Refining: the part where Claude Design earns its keep

Three tools matter here:

Inline comments — click any element and leave a note. "Make this CTA more prominent" attached to the actual button.
Direct edits — change text inline, drag to resize, recolor without going through chat.
The tweaks panel — sliders and toggles for live adjustments. The real superpower: you can ask Claude to add new controls to the panel itself. Want a glow slider? A density toggle? A radius knob? Just say so. Most AI design tools have a fixed property panel; this one lets you grow it.

Once you've got something you like on one screen, ask Claude to "apply this treatment across the full design" and it propagates the changes.

Before you hand anything off, run through edge cases explicitly: empty states, error states, loading states, different data volumes, and responsive variants at 375px / 768px / 1280px. A prompt like "show me how this handles the empty state when the user has no data yet" takes 30 seconds and saves an engineer half a day.

Step 3 — Link your codebase

This is where Claude Design separates itself from every other AI design tool.

In the project, click Import. You get two options:

From GitHub — connect your repository. Claude reads your components, your styling approach (Tailwind, CSS modules, styled-components — it figures it out), your spacing scale, your file structure, and your naming conventions.
From a local directory — drag-and-drop a folder if you can't connect the repo directly.

Once linked, your codebase is part of the project's context. Now your prompts can reference real components:

"Use our ProductCard component for the grid, follow the same layout pattern as the existing SettingsPage, and reuse the useUser hook for the avatar."

The output stops being generic React-flavored mockups and starts looking like something pulled from your repo. That's the whole point — when the prototype is already built with your real patterns, the gap between "prototype" and "shippable code" shrinks dramatically, which is exactly the framing Anthropic uses.

Step 4 — Hand off to Claude Code

Here's the moment that makes the whole pipeline interesting.

When the prototype is in good shape, you hit Share → Handoff to Claude Code. Claude Design generates a handoff bundle: the design files (HTML/CSS/JS), screenshots of each state, and a README that tells the coding agent what stack to target and what conventions to follow.

You have two options for where the bundle goes:

Claude Code Web — fully in the browser, the bundle opens in a Claude Code session that can read it natively.
Local Claude Code — download the bundle, drop it into your repo, and run claude in the directory.

Either way, Claude Code now has:

The design intent (encoded in the HTML/CSS/JS output)
Your codebase context (if you linked it)
The README with explicit stack instructions
The conversation history from Claude Design — so it knows why you made the design decisions you made

That last part matters more than people realize. When you said "we went with tabs instead of a sidebar because users need to see all sections at once," that reasoning carries through. Claude Code doesn't just rebuild the pixels; it preserves the intent.

Tip: write your own handoff README

The default README is fine. A hand-crafted one is the difference between "merged this week" and "rewrite from scratch." A good handoff README spells out:

Target stack (Next.js 16 App Router, TypeScript, Tailwind, shadcn/ui, etc.)
Where new components should live in the file tree
Naming conventions (kebab-case files, PascalCase components, etc.)
Definition of done — accessibility scan passes, renders at 3 breakpoints without horizontal scroll, all interactions work, bundle size delta within budget
Questions Claude Code should ask before coding rather than guessing — "what's the error state?", "what's the loading state?", "what should happen on form validation failure?"

Here's a stripped-down template you can paste into the bundle:

# [Feature] — Claude Code Handoff

## Stack
- Next.js 16 (App Router), TypeScript, Tailwind, shadcn/ui
- Components live in /components/[feature]/
- Use existing Button, Card, Dialog from /components/ui/

## Definition of done
- [ ] Renders at 375 / 768 / 1280px without horizontal scroll
- [ ] All interactions from the prototype work
- [ ] Empty/loading/error states implemented
- [ ] Axe accessibility scan: 0 violations
- [ ] PR includes before/after screenshots

## Ask before implementing
1. What's the error state for failed payments?
2. What happens when the user has 0 items?
3. Should we support `prefers-reduced-motion`?

That five-minute investment is worth more than any prompt-engineering trick.

Step 5 — Wire it to GitHub

Now the loop closes. There are two GitHub connections worth knowing about, and they do different things.

A) Linking your repo into Claude Design (read access)

This is the codebase import we covered in Step 3. Claude Design reads your repo so prototypes use your real components. It's read-only context — Claude Design doesn't push commits.

B) Claude Code GitHub Actions (write access)

This is where Claude Code actually opens PRs in your repo. You install the official Claude GitHub App and a workflow file, and from then on you can mention @claude in any issue or pull request and it picks up the task.

The fastest setup: open your terminal, install Claude Code, and run:

claude
> /install-github-app

This walks you through:

Installing the Claude GitHub app (https://github.com/apps/claude) on your repo. It needs read & write permissions for Contents, Issues, and Pull Requests. You need to be a repo admin.
Adding ANTHROPIC_API_KEY to your repository secrets.
Dropping a claude.yml workflow file into .github/workflows/.

If the auto-installer fails or you'd rather wire it up by hand, the manual setup is documented in the Claude Code GitHub Actions guide. The workflow defaults to Sonnet — if you want Opus 4.7, set model: claude-opus-4-7 in your workflow config.

Once it's installed, the magic moment looks like this:

You (in a GitHub issue): "@claude implement the prototype in design/handoff/settings-page.zip using our existing component library. Match the spec in the README and open a PR against main."

Claude reads the issue, clones the repo, ingests the handoff bundle, writes the code, runs your tests, and opens a PR. You review it like any other PR. If something's off, you comment on the diff and Claude pushes a new commit.

A few setup notes worth taking seriously:

Strip write permissions for review-only setups. If you only want Claude to review PRs, not modify them, give the action read-only access. Some teams cryptographically sign Claude's commits to keep an audit trail.
Set a reasonable timeout. 10–15 minutes is sane. Without it, runaway workflows eat your Actions minutes.
Add a CLAUDE.md at your repo root. This is the equivalent of a project-wide system prompt. Document your conventions, banned patterns, test commands, and lint rules. Claude reads it on every run.

The full loop, end to end

Here's what the workflow looks like on a real day:

Idea. A teammate posts in Slack: "We need a settings page redesign before the demo Friday."
Prototype. You open claude.ai/design, describe the page, iterate for 20 minutes with the tweaks panel until the spacing feels right.
Link the repo. You connect the GitHub repo so Claude uses your real Card, Tabs, and Input components.
Show stakeholders. You share the project URL with comment access. PM leaves three comments inline. You address them in five minutes.
Write the handoff README. Stack, file paths, definition of done, questions to ask.
Hit "Handoff to Claude Code." The bundle drops into a Claude Code Web session — or you download it locally.
Open a GitHub issue. "@claude implement settings page redesign from this bundle." Attach the bundle.
Review the PR. Claude opens it within minutes. You leave inline comments, Claude pushes fixes.
Merge. Done. Same day.

Before this pipeline existed, that's a one-week ticket. With it, it's a one-day ticket — and the design intent doesn't get lost in translation.

Where it breaks (be honest with yourself)

Claude Design isn't magic and it isn't right for everything:

Agencies that bill clients for Figma files. If your deliverable is a .fig file with hand-off-able layers, this isn't your tool yet.
Locked enterprise design systems with a design ops team gatekeeping changes. Claude Design wants to read your system from code, which doesn't fit that governance model.
Pixel-perfect brand work. For a hero image with custom illustration and bespoke type, you still want a designer in Figma and Illustrator.
Taste. Claude can generate ten dashboard variations in ten minutes. It can't tell you which one to ship for your users. That's still your job — and it's the part that's about to become more valuable, not less.

Tips that actually move the needle

A short list, ranked by ROI:

Invest in your design system before anything else. The output is only as good as the input.
Name things clearly during the design conversation. "ProductCard" sticks. "that thing" doesn't.
Document decisions in the chat, not just the design. Reasoning travels with the handoff.
Always generate edge states before handoff. Empty, loading, error, overflow.
Write your own handoff README. Five minutes saves three hours.
Add a CLAUDE.md to your repo. It's the highest-leverage file you can add to a repo right now.
Use the @claude mention in GitHub for the small stuff first. Build trust on tiny refactors before handing it a feature.

The bigger picture

Anthropic is quietly stitching together a knowledge-worker stack: Claude for chat and reasoning, Claude Code for engineering, Claude Cowork for async collaboration, and now Claude Design for visual work. The pattern is the same one Microsoft ran with Office decades ago — adjacent tools, shared substrate, compounding value when you use more than one.

The design-to-code closed loop is the first synergy that's actually visible. It's a bet that the next generation of product teams will own their design system in code, not in a dedicated design tool — and that bet looks increasingly correct.

If you're a builder, this is the workflow worth learning right now. The teams that internalize it will move at a different pace than the teams that don't.

Got questions or want to share your own workflow? I'm at bilelsalem.me.

DEV Community