How to keep UI consistent across Claude Code sessions

To keep UI consistent across Claude Code sessions, put every design decision that must last into a file Claude Code loads automatically, not into the conversation. Each session starts with a fresh context window. What carries over is CLAUDE.md (your instructions), auto memory (notes Claude keeps) and whatever files the new session reads. This guide covers how each of those behaves, what survives compaction and resuming, and a simple routine for starting and ending a UI session.

What carries over, and what doesn’t

Claude Code’s memory documentation describes two mechanisms that load at the start of every session:

• CLAUDE.md files: instructions you write. Project, user or organisation scope.
• Auto memory: notes Claude writes itself from your corrections and preferences, per repository.

Everything else, including corrections you gave in chat, the reference you pasted and the reasoning behind a layout, belongs to one conversation. A new session doesn’t see it. If the second session builds a slightly different card, it’s usually because the first session’s decisions never left the chat.

1. Put lasting design rules in CLAUDE.md

The project-root CLAUDE.md is the most reliable place for design rules: it loads in every session and, according to Claude Code’s context window guide, is re-injected from disk after compaction. Keep it short. The docs suggest under 200 lines per file, because longer files reduce adherence.

## UI
- Tokens live in src/app/globals.css. Use them; no arbitrary values.
- Reuse components in src/components/ui before creating new ones.
- Reference screen for density and type: src/app/(app)/settings/page.tsx
- Secondary text: one weight lighter, same size. Never smaller than 13px.
- Check UI changes in the browser at 1440 and 390 before finishing.

## Compaction
When compacting, preserve design decisions made in this session and
the list of components created or changed.

The last section uses a technique from Claude Code’s best practices: instructions in CLAUDE.md can tell compaction what to keep. What goes in the UI section is covered in detail in CLAUDE.md for UI design.

2. Know which rules survive compaction

Rules in .claude/rules/ with paths: frontmatter load only when Claude works with matching files. That saves context, but the context window guide notes a catch: they load into the conversation, so compaction summarises them away until a matching file is touched again. If a design rule must hold for the whole session, keep it unscoped or in the project-root CLAUDE.md.

3. Treat auto memory as Claude’s notes, not your rules

Auto memory is on by default in local sessions. Claude saves what it learns to ~/.claude/projects/<project>/memory/, shared across worktrees of the same repository, and the first 200 lines (or 25KB) of its MEMORY.md index load at the start of each session. It’s useful for things Claude picks up as you work.

For design decisions, be deliberate. Saying “remember that cards never have shadows” saves it to auto memory, on your machine only. Saying “add this to CLAUDE.md” puts it in the file your teammates’ sessions read too. Run /memory now and then to review what Claude has saved and move anything that’s really a project rule.

4. Check what actually loaded

When a session ignores a rule, first check it was there. /context lists the memory files that loaded at launch, and /memory opens them. A rule that isn’t listed can’t be followed.

5. Resume when the work continues; clear when it doesn’t

Claude Code saves sessions locally, so you can pick a task up later with its history intact. The sessions documentation lists the entry points:

claude --continue          # most recent session in this directory
claude --resume            # pick from a list
claude -n settings-redesign   # name a new session
claude --resume settings-redesign

Inside a session, /rename names it and /resume switches to another. Name UI sessions after the surface you’re working on, so the next session on that surface can pick up the same thread.

Resuming isn’t always better. The best practices suggest /clear between unrelated tasks, and starting fresh after correcting the same issue more than twice, because the context is cluttered with failed attempts. A clean session with the rule written into CLAUDE.md beats a long one that holds it only in chat.

6. End each session with a handoff

Before you close a UI session, ask Claude to write down what changed and why. This isn’t a Claude Code feature; it’s a habit that turns one session’s decisions into the next session’s context.

Before we finish: add any design decision we made this session that
should apply elsewhere to CLAUDE.md under "UI", as one line each.
Then append a short entry to docs/design/log.md: what changed, which
components were added or modified, and anything left unfinished.

7. Start each session the same way

A consistent opening prompt makes the new session look at the product before it builds, instead of re-deriving the design from whichever file it reads first.

We're continuing UI work on the billing pages. Read docs/design/log.md
and the reference screen named in CLAUDE.md. List the rules you'll
follow and the existing components you'll reuse, then wait for me
before changing anything.

8. Compare against the product, not the prompt

The final check is visual. Ask Claude to open the new screen next to an existing one and list differences in spacing, type and components. A screen can match its prompt and still not match the product. For a repeatable version, see visual testing with Claude Code and Playwright.

Parallel sessions

If you run several sessions at once in worktrees, they share the repository’s CLAUDE.md and auto memory, but each has its own conversation. A decision made in one worktree’s chat doesn’t reach the others until it’s in a file and that file is merged. Branches and previews for this way of working are covered in a Claude Code workflow for designers.

Direction that lives outside the session

CLAUDE.md is the right home for rules about one codebase. References and the reasons behind a direction are harder to keep there, and they’re often shared across products. Attuna holds that part: in Attuna, in private beta, a project keeps its brief, rules to prefer or avoid, and annotated references, and Claude Code reads it over MCP at the start of each task. Rules an agent suggests wait for your approval, so the direction only changes when you decide it should.