design-memory

Design Memory Persistence

Maintains a persistent design-memory.md file that captures UI/UX decisions made during design-screen sessions, UI reviews, and polish passes. Prevents re-asking questions already answered in prior conversations.

Design Memory File Location

.claude/design-memory.md (project root, not inside skills)

Read Protocol

At the start of any UI-related task:

1. Check if .claude/design-memory.md exists.
2. If it exists, read it in full before producing any UI code or feedback.
3. Apply stored decisions to the current task without asking the user to re-confirm them.
4. If a stored decision conflicts with something the user is now requesting, surface the conflict and ask which to keep.

"UI-related task" includes: building views, polish passes, design-screen sessions, UI reviews, colour or typography changes, layout work, and any task that touches SwiftUI view code.

Write Protocol

Write to design memory when:

• A /design-screen session completes and produced actionable decisions.
• Significant design decisions are made during any UI work (new pattern, colour choice, interaction convention).
• The user explicitly says "remember this" or "save this decision" about a design choice.

Do NOT write speculatively. Only persist decisions that were confirmed or demonstrated through implementation.

Memory File Structure

When creating or updating .claude/design-memory.md, use this structure:

# Project Design Memory

> Auto-generated by design-memory skill. Updated: YYYY-MM-DD

## Brand & Tone
- [brand adjectives, visual personality decisions]

## Layout Preferences
- [density, container choices, spacing conventions]

## Typography Decisions
- [hierarchy approach, custom text style preferences]

## Colour Decisions
- [palette usage patterns, per-feature accent colours, chart colours]

## Interaction Patterns
- [sheet detents, haptic patterns, animation style, swipe actions]

## Component Preferences
- [empty states, loading patterns, error handling, card styling]

## Feature-Specific Decisions
- [per-feature decisions that should persist]

Update Rules

• Never delete existing entries without user confirmation.
• Append new decisions; do not overwrite existing ones.
• Add a datestamp (YYYY-MM-DD) to each new entry.
• If a new decision conflicts with an existing one, ask the user which to keep before writing.
• Keep the file concise — decisions only, not rationale essays.
• Target under 100 lines to stay readable. If approaching the limit, ask the user which older entries can be pruned.

Bootstrapping

If no design-memory.md exists and the user starts a design task:

1. Note that no design memory exists yet.
2. Run the Design Context Interview below before producing any design work.
3. After the interview, create design-memory.md with the answers.

Design Context Interview

When no design memory exists, you MUST gather this context before doing any design work. Do not infer these answers from the codebase — code tells you what was built, not who it's for or what it should feel like.

Ask these questions (skip any already answered in the conversation):

1. Who uses this? What's their context when using it? What job are they trying to get done?
2. How should it feel? Pick 3 words that describe the brand personality. (e.g., calm/precise/trustworthy, or bold/playful/energetic)
3. What should it NOT feel like? Any anti-references — apps or aesthetics to explicitly avoid?
4. Visual direction? Minimal, bold, elegant, warm, clinical, organic? Light mode, dark mode, or both?
5. Any existing brand constraints? Colours, typography, or patterns that are non-negotiable?

Synthesise the answers into the Brand & Tone and Layout Preferences sections of design-memory.md. Keep it tight — decisions only, not rationale essays.

If the user declines the interview or says "just build it," note that no design context was gathered and proceed with sensible defaults. Do not block the user.

Integration with Other Skills

These skills should interact with design memory:

Skill	Interaction
/design-screen	Writes to design memory after synthesis completes
/ui-polish	Reads design memory before auditing
/ux-polish	Reads design memory before auditing
/review-ui	Reads design memory as review context
Any UI view work	Reads design memory before producing code

Anti-Rationalization

Excuse	Reality
"I don't need to check design memory"	You do. Consistency requires it.
"This is a small UI change"	Small changes that break consistency are worse than large consistent ones.
"The user will tell me if it's wrong"	The user shouldn't have to repeat themselves. Read the memory.

Gotchas

• Stale entries: Design memory reflects what was true when it was written. If the codebase has since diverged, trust what you observe now and update the memory.
• Conflicting entries: If two entries contradict each other, the one with the later date wins. But always ask the user rather than silently picking one.
• Over-writing: Don't save every tiny decision. Save patterns and conventions, not one-off choices. "We use .medium sheet detents for creation flows" is good. "This one button is blue" is not.
• Memory bloat: If the file exceeds ~100 lines, it's too long. Offer to prune older entries that are now redundant or superseded.
• First-session bootstrapping: Don't create design-memory.md on the first UI task just because the skill says to check for it. Only create it after meaningful decisions have been made that are worth persisting.