Skip to content
Sign in

BlogClaude Code

A Claude Code workflow for designers: branches, previews and review

By Attuna · · 4 min read

The workflow that works best for designers building with Claude Code is the one engineers already trust: one branch per change, a preview deployment for every branch, a review before anything reaches production, and small steps throughout. Claude Code makes each of those easy, including running several changes in parallel with worktrees. This guide sets out the loop, the commands, and where design judgement fits in it.

It assumes you’ve installed Claude Code and used it on a project. If not, start with Claude Code for designers.

The loop

  1. Start a branch for one change.
  2. Brief it, plan it, build it in small steps.
  3. Check it locally in the browser.
  4. Push for a preview deployment and review it at real sizes.
  5. Open a pull request with screenshots; get a review.
  6. Merge; capture anything you learned as a rule.

1. One branch per change

A branch is a safe copy of the product where you can experiment without affecting anyone else. Ask Claude to create one before starting, named after the change:

Prompt
Create a branch called design/billing-empty-state from main,
then show me the plan for the change before editing anything.

Keeping one change per branch makes review easy and makes it painless to throw away an experiment that didn’t work.

2. Parallel work with worktrees

To work on two things at once, such as a new screen and a polish pass, each needs its own files. Claude Code’s worktree support creates an isolated checkout on its own branch:

Terminal
claude --worktree billing-empty-state

By default the worktree is created under .claude/worktrees/ at the repository root, on a new branch. Run the command again with another name in a second terminal for a second, independent session. The desktop app can also run each session in its own worktree. Each worktree is a fresh checkout, so it needs its dependencies installed, and local files such as .env can be copied in with a .worktreeinclude file.

3. Build in small, checked steps

  • Plan first (Shift+Tab into plan mode) for anything touching several files.
  • One concern per step: layout, then states, then responsive, then polish.
  • Ask for screenshots after each step at the widths you care about.
  • Commit after each step that works, so there’s always a known-good point to return to.

The prompts for each step are in Claude Code UI prompts.

4. Preview deployments

A local check shows the change on your machine. A preview deployment shows it on a real URL anyone on the team can open, on any device. If your project is on Vercel, the environments documentation says preview deployments are created by default when you push a commit to a branch that isn’t your production branch, or open a pull request, and each gets its own URL. Other hosts offer similar previews.

Prompt
Commit the work with a clear message and push the branch.
Then open a pull request that describes the change and includes
screenshots at 1440 and 390 for each state.

Review on the preview, not just locally: on your phone, with real data where possible, at sizes your laptop doesn’t show.

5. Design review before merge

The pull request is where design judgement belongs in this workflow. Review the screens, not just the diff:

  • Does it do the job in the brief?
  • Is the hierarchy right, and does it match the rest of the product?
  • Do the empty, loading and error states feel as designed as the main one?
  • Does it hold up on a phone, with a keyboard, with long content?

Make the mechanical checks automatic so review time goes on judgement. A Playwright visual test and a token check in CI catch regressions and stray values before a person looks.

6. Merge, then make it stick

After merge, ask what you corrected during the change and turn repeat corrections into rules. That’s what stops the next branch making the same mistakes:

Prompt
List the corrections I made on this branch more than once. Propose a
one-line rule for each and where it belongs: CLAUDE.md, a path rule
in .claude/rules/, or our principles doc.

Working alongside engineers

  • Agree the boundary. Which areas designers change directly, and which go through an engineer.
  • Use the same review. Designer branches go through the same pull request process as everyone else’s.
  • Share instructions. One AGENTS.md or CLAUDE.md for everyone, so every agent follows the same rules.

For how this loop fits a full design process from references to shipped UI, see the design engineering workflow.

Start each branch with direction

Branches, previews and reviews keep changes safe. They don’t tell the agent what the change should look like. Attuna, in private beta, holds that direction per project: references, rules to prefer and avoid, and preferences, which Claude Code reads over MCP at the start of a task.

Sources