CLAUDE.md Templates for Web Projects

What is CLAUDE.md?

A CLAUDE.md file in your project root gives AI coding assistants persistent context about your project conventions. Claude Code reads it automatically. Other tools (Codex, Cursor, Windsurf) support similar files — see Tool Compatibility below.

Minimal Starter

For small Tailwind projects. Copy and adapt:

# Project Instructions

## Stack
- Tailwind CSS v4 (Vite plugin, CSS-first config)
- Semantic HTML, mobile-first, accessible
- No JavaScript frameworks unless explicitly needed

## Design Rules
- 8px spacing grid (Tailwind: gap-2, p-4, py-16, etc.)
- Max 2 font families, prefer system fonts or Inter
- One primary color + one accent, defined as CSS custom properties
- Border radius: rounded-lg for cards, rounded-md for buttons
- Shadows: shadow-sm to shadow-lg max, never shadow-2xl

## Code Style
- HTML: semantic tags (section, article, nav, aside, figure)
- CSS: Tailwind utilities only, no custom CSS unless unavoidable
- Accessibility: alt text, aria-labels, focus-visible states, skip links
- Responsive: mobile-first, test at 375px / 768px / 1280px

## Don't
- Don't use dark: classes — use CSS custom properties for theming
- Don't add JavaScript for layout or styling
- Don't use px values — use Tailwind's spacing scale
- Don't nest more than 3 levels of divs without semantic meaning

Full Web Project Template

For larger projects with design system integration:

# Project — CLAUDE.md

## Stack
- Astro v6 + Tailwind CSS v4 (Vite plugin)
- Svelte 5 for interactive islands (runes: $state, $derived, $props)
- Biome for linting/formatting
- Static output, deployed to Cloudflare Pages

## Design System
- Webspire tokens: import webspire-tokens.css + webspire-components.css
- Colors via --ws-color-* custom properties (surface, text, primary, accent, border)
- Dark mode handled centrally in tokens — never use dark: Tailwind classes
- Component tokens: --ws-{family}-{role} (e.g. --ws-hero-bg, --ws-cta-action-bg)

## Spacing & Layout
- 8px grid: only use multiples (p-2, p-4, p-6, p-8, py-12, py-16, py-24)
- Container: max-w-7xl mx-auto px-4 sm:px-6 lg:px-8
- Section vertical rhythm: py-16 (mobile) → py-24 (desktop)
- Card padding: p-6 → p-8

## Typography
- Font: Inter, -apple-system, system-ui, sans-serif
- Scale: Minor Third (1.2) — text-sm, text-base, text-lg, text-xl, text-2xl, text-3xl
- Headlines: font-bold, tracking-tight, line-height 1.1-1.25
- Body: text-base, leading-relaxed (1.625), max-w-prose (65ch)

## Components
- Every UI component = HTML-first (Tailwind-only, no framework code)
- Root element gets ws-{family} class
- Colors only via var(--ws-{family}-{role})
- Responsive, accessible, SSR-safe

## Quality
- All text passes WCAG AA contrast (4.5:1)
- Every interactive element has visible focus state
- Images have alt text, decorative images have alt=""
- Forms have labels, not just placeholders
- No console errors, no layout shifts

## Don't
- Don't create internal Astro components for UI elements — use pattern families
- Don't hardcode colors — use tokens
- Don't use JavaScript for layout/styling
- Don't add dependencies without asking
- Don't use @apply — write Tailwind utilities directly

E-Commerce Project Template

# E-Commerce Project — CLAUDE.md

## Stack
- Next.js 15 + Tailwind CSS v4
- Server Components by default, Client Components only for interactivity

## Design Rules
- Clean, product-focused design (Apple Store / Shopify aesthetic)
- Product images are hero content — large, uncluttered
- CTA buttons: high-contrast, rounded-lg, font-semibold
- Trust signals visible (ratings, reviews, shipping info) near purchase buttons
- Pricing: large, bold, never ambiguous

## Color Tokens
- --color-surface: #ffffff (product cards, main bg)
- --color-text: #0f172a
- --color-primary: #18181b (buttons — dark, confident)
- --color-accent: #059669 (success, in-stock, deals)
- --color-danger: #dc2626 (errors, out-of-stock)

## Patterns
- Product grids: 2-col mobile, 3-col tablet, 4-col desktop
- Cart: sticky summary on desktop, bottom sheet on mobile
- Checkout: single-column, max-w-lg, progressive disclosure
- Reviews: star ratings with bar breakdown

## Performance
- Images: next/image with sizes prop, lazy loading below fold
- Fonts: preloaded, font-display: swap
- No layout shifts on product cards (fixed aspect ratios)

Tool Compatibility

| File | Tool | How it’s loaded | |------|------|----------------| | CLAUDE.md | Claude Code | Auto-loaded from project root + ~/.claude/CLAUDE.md | | CLAUDE.md | Claude (chat) | Paste as context or attach as file | | AGENTS.md | Codex (OpenAI) | Auto-loaded from project root | | .cursorrules | Cursor | Auto-loaded from project root | | .windsurfrules | Windsurf | Auto-loaded from project root | These templates work in all AI coding tools — only the filename differs. See the AI Tool Comparison guide for the full compatibility matrix and setup instructions.

Checklist

• [ ] CLAUDE.md in project root
• [ ] Stack and framework versions documented
• [ ] Design tokens / color system defined
• [ ] Spacing and typography rules specified
• [ ] “Don’t” section with clear anti-patterns
• [ ] Quality requirements (a11y, performance) listed
• [ ] Copied to AGENTS.md / .cursorrules if using multiple tools