Creating Your Design System

What You'll Learn

A design system is a set of rules that ensure consistency across your entire site. It defines which fonts to use, which colors are allowed, how much space goes between elements, and what patterns are forbidden.

Why Design Systems Matter

The Chaos Without a System:

• Headlines are 32px on one page, 36px on another
• The green is slightly different shade each time
• Buttons have inconsistent spacing
• The site feels "off" but you can't pinpoint why

How Design Systems Create Consistency:

• Every H2 heading is exactly text-3xl md:text-4xl
• Brand green is always #3a4c40
• Section padding is always py-24 md:py-32
• Claude Code knows the rules and follows them

Why This Matters Even More with AI:

LLMs are notorious for generating generic, "safe" interfaces—the kind of bland, universally acceptable designs you've seen on countless template websites. Without explicit design constraints, Claude Code will default to safe choices: standard blue buttons, predictable layouts, and the same patterns every other AI-generated site uses.

Your design system is what transforms AI output from "looks like every other website" to "unmistakably yours." It's the difference between a forgettable template and a site that actually reflects your brand's personality.

Decisions You Must Make

Typography Decisions

Fonts communicate personality:

• Serif fonts (like Georgia): Traditional, trustworthy, premium
• Sans-serif fonts (like Helvetica): Modern, clean, accessible

Color Decisions

Most sites need:

• Primary color: Your main brand color (used for headers, CTAs)
• Secondary color: Complements the primary (used for accents)
• Neutral palette: Grays for text, borders, backgrounds

Accessibility requirement: Text must meet WCAG AA contrast (4.5:1 for normal text).

Spacing Decisions

Charter Oak uses a 4px base:

4px, 8px, 12px, 16px, 24px, 32px, 48px, 64px, 96px, 128px

Deliverable: Choose Typography

Purpose: Select fonts that match your brand personality.

Expert Role: Typography Specialist and Brand Designer

Tools to Use: WebSearch (research font pairings), Context7 MCP

Expected Output

• 2-3 font pairing recommendations
• Explanation of why each works

Prompt Template

Act as a typography specialist and brand designer. Help me choose
fonts for my website. My brand personality is
[describe: professional, friendly, bold, elegant, etc.].

I need:
1. A display font for headlines (used sparingly)
2. A body font for paragraphs and UI

Show me 2-3 combinations and explain why they work together.
Consider Google Fonts since they're free and easy to load.

Deliverable: Create Color Palette

Purpose: Define a complete, accessible color system.

Expert Role: Brand Color Specialist with Accessibility Expertise

Tools to Use: File system (edit tailwind.config.ts)

Recommended Resource: Coolors.co is an excellent tool for exploring and generating color palettes. You can start with your brand color, lock it, and generate complementary colors. Export the hex codes and bring them to Claude Code.

Expected Output

• Complete color palette with semantic names
• WCAG AA compliant combinations

Prompt Template

Act as a brand color specialist with accessibility expertise.
Create a color palette for my brand. My primary brand color is
[hex code or description like "forest green"].

I need:
1. Primary color with light and dark variants
2. A neutral gray scale (for text and backgrounds)
3. Semantic colors (success, warning, error, info)
4. All colors should meet WCAG AA contrast requirements

Explain each color's purpose and add them to tailwind.config.ts.

Deliverable: Implement Complete Design System

Purpose: Create all design tokens and documentation.

Expert Role: Design Systems Engineer

Tools to Use: File system (write/edit multiple files)

Expected Output

• Updated tailwind.config.ts with all tokens
• New globals.css with CSS custom properties
• New docs/design-system.md with documentation
• Updated CLAUDE.md with design rules

Prompt Template

Act as a design systems engineer. Implement my complete design system:

**Typography:**
- Display font: [Font name] for headlines
- Body font: [Font name] for everything else
- Use the type scale we defined

**Colors:**
- Primary brand: [hex code]
- Text primary: #1a1a1a
- Text secondary: #555555
- Background: #ffffff
- Background alt: #f5f5f3

**Spacing:**
- 4px base unit
- Section padding: py-24 md:py-32 (default)
- Container max-width: 1000px (content), 1200px (wide)

**Animation:**
- 600ms duration, ease-out timing
- Scroll-triggered reveals starting at 75% viewport
- Respect prefers-reduced-motion

Update tailwind.config.ts with all these tokens.
Create globals.css with CSS custom properties.
Create design-system.md documenting everything.
Update CLAUDE.md with design system rules.