Project Context Checklist (CLAUDE.md Starter)

A fill-in-the-blanks CLAUDE.md starter for design projects. Covers non-negotiables, anti-patterns, vocabulary, and file conventions in under 60 lines. Drop it at the root of any project to give Claude Code the context it needs to work without re-explaining.

All Templates

What this is

A paste-ready CLAUDE.md starter for any design-heavy project. It gives Claude Code the project context it needs so you do not re-explain your design system, brand voice, or ban list every time.

This is the companion template to the Context Is the Product guide. Install it, fill in the blanks, and commit it to your repo.

How to install

Step 1: At the root of your project

touch CLAUDE.md
open CLAUDE.md

Step 2: Paste the starter below

Copy the full block under “The full CLAUDE.md starter” into the file.

Step 3: Fill in the [brackets]

Replace every [BRACKETED] placeholder with real project information. Do not ship with placeholders.

Step 4: Commit it

git add CLAUDE.md && git commit -m "Add CLAUDE.md project context"

Claude Code automatically reads this file when invoked in the project root.

The full CLAUDE.md starter

# [PROJECT NAME]

## What this project is

[One sentence that describes what this product does and who it is for. Example:
"A billing tool for small consulting firms that replaces spreadsheet-based invoicing."]

Built with [STACK, e.g. Next.js 14, Tailwind 3, shadcn/ui, Supabase].

---

## Non-negotiables (never substitute)

### Brand
- Primary color: [#HEXVALUE]
- Accent color: [#HEXVALUE]
- Background default: [#HEXVALUE]
- Foreground default: [#HEXVALUE]

### Typography
- Heading font: [FONT NAME]
- Body font: [FONT NAME]
- Mono font: [FONT NAME]
- Minimum body size: [16px recommended]

### Spacing and shape
- Border radius: [8px cards / 6px inputs / 999px pills — adjust to your scale]
- Shadow cap: [shadow-md recommended, avoid shadow-xl and above]
- Grid: [12-column / 8pt baseline / describe yours]

### Motion
- Micro-interactions: [under 200ms]
- Entrance animations: [under 300ms]
- Never use: [list any banned effects, e.g. parallax on scroll, bounce, scale-on-hover]

---

## Anti-patterns (never output)

- Gradient backgrounds on hero or cards. Solid fills only.
- "Get started", "Learn more", "Submit", "Continue" as CTA copy.
  Name the action instead.
- Emojis in H1 or H2 headings.
- Decorative motion on scroll.
- Stacked adjectives in marketing copy ("powerful, simple, intelligent").
- Buzzwords: revolutionize, seamless, unlock, empower, leverage, frictionless,
  game-changing, next-gen, cutting-edge.
- AI-generic hero layouts (centered headline + vague 3D object).
- Any shadow above shadow-md.
- Glassmorphism or frosted-glass overlays.

[Add your own anti-patterns as you find them. See
https://www.aidesign.dev/guides/ai-anti-patterns-gallery for common ones.]

---

## Vocabulary

- We say "[PREFERRED TERM]", not "[COMMON ALTERNATIVE]".
  Example: "customer", not "user".
- Product feature names:
  - [FEATURE A] (never "[WRONG NAME]")
  - [FEATURE B]
- Internal areas:
  - [AREA NAME] for the admin surface (never "admin panel" or "backend")

---

## Voice and copy rules

- Sentences under 20 words when possible.
- Specific over clever. No teasing headlines.
- Buttons name the action.
- Error messages tell the user what happened and what to do next.
- No exclamation marks in product UI.
- First person plural ("we") for brand voice, first person singular ("I") for
  customer actions ("I agree", "I understand").

[Link to a fuller brand voice doc if you have one, e.g. docs/brand-voice.md.]

---

## File and code conventions

- Components in [PATH, e.g. src/components/] as [.tsx / .jsx / .vue].
- Styles with [Tailwind / CSS modules / vanilla-extract]. Never inline `style`.
- One component per file. Default exports unless the file has multiple
  related named exports.
- Icons from [LIBRARY NAME]. Do not mix libraries.
- Images in [PATH]. Optimized (webp or avif) at build time.
- Tests in [PATH]. Every new component gets a snapshot test.

---

## Accessibility floor

- WCAG 2.2 AA is the floor. Anything below is a bug.
- Contrast: 4.5:1 text, 3:1 UI and large text, 3:1 focus indicators.
- Target size: 44x44 touch minimum. 24x24 pointer minimum with spacing.
- Every interactive element keyboard-reachable with visible focus.
- No color-only information. Always paired with a label, icon, or pattern.

---

## Before you ship

Run these review skills on any customer-facing screen:

- `/ux-review` (see https://www.aidesign.dev/templates/ux-review-agent-starter)
- `/review-a11y` (see the Multi-lens Review Pack)
- `/anti-pattern-check` (see the Anti-Pattern Check Skill)

For high-stakes screens, dispatch the full 4-lane parallel review.

---

## Linked docs

[If you have them, link them. If not, delete this section for now.]

- Design system: ./docs/design-system.md
- Brand voice: ./docs/brand-voice.md
- Accessibility standards: ./docs/accessibility.md
- Component guidelines: ./docs/component-guidelines.md

---

## Session defaults

When producing any UI in this project:

1. Respect the non-negotiables above.
2. Do not invent new tokens (colors, spacing, shadows).
3. Use existing components from the component library if they exist.
4. Return concise output. No preamble, no summary unless asked.
5. If uncertain about a design decision, ask me before producing the output.

Filling-in-the-blanks guide

This is the fastest way to fill out the starter. Give yourself 15 minutes.

Minute 1–3: Identity

  • Project name and one-sentence description
  • Stack (frameworks and major libraries)

Minute 4–6: Brand tokens

  • Pull the exact hex values for primary, accent, background, foreground
  • Pull the font names
  • Confirm your border-radius and shadow caps

Minute 7–9: Anti-patterns

  • Add 3–5 project-specific anti-patterns you keep fixing
  • Keep the generic ones already in the starter

Minute 10–12: Vocabulary and voice

  • List 3–5 vocabulary choices your team has made
  • Add 2–3 voice rules that matter most

Minute 13–15: File conventions

  • Where components live
  • Styling approach
  • Icon library
  • Image location

Save. Commit. Done.

How to maintain it

Weekly

Add any rule you had to re-explain in chat more than once.

Biweekly

Delete dead rules. If Claude never breaks a rule anymore, you can assume it’s internalized and remove the line to keep the file lean.

Monthly

Read the file end-to-end. Ask: “If a new designer joined today, would this tell them what good looks like here?” If no, tighten.

Keep the file under 100 lines. If you need more, move it to linked docs and reference from here.

Signals you got it right

  • You notice Claude’s output starts matching your brand without you pasting colors every time.
  • The amount of back-and-forth during design tasks drops noticeably.
  • New team members (human or agent) produce consistent output on their first try.
  • You stop needing to say “and also remember to…” at the end of every prompt.

What this pairs with