Style Guide Framework

A battle-tested framework for documenting design decisions so your website stops looking like it has multiple personality disorder

The Hospital Gown Problem

Why Style Guides Are Your Secret Weapon

The Five Pillars of Any Effective Style Guide

1. Brand Foundation

2. Visual Language

• Primary colors (1-2 max for brand identity)

• Secondary colors (2-3 for supporting elements)

• UI colors (success green, error red, warning yellow)

• Neutral grays (at least 5 shades from near-black to near-white)

• Hex code (#2B5CE6)

• RGB values for digital (43, 92, 230)

• When to use it ("Primary buttons, major headings")

• When NOT to use it ("Never for body text")

• Small: 13px (captions, timestamps)

• Body: 16px (all paragraph text)

• Large: 20px (intro paragraphs)

• H3: 25px (section headers)

• H2: 31px (page sections)

• H1: 39px (page titles)

font-family: 'Your Brand Font', 'Helvetica Neue', Arial, sans-serif;

• xs: 4px (tight internal spacing)

• sm: 8px (between related items)

• md: 16px (default spacing)

• lg: 32px (between sections)

• xl: 48px (major breaks)

• xxl: 64px (hero sections)

3. Component Library

• Primary: For main actions ("Buy Now," "Sign Up")

• Secondary: For alternate paths ("Learn More," "Cancel")

• Text: For tertiary actions ("Skip," "Maybe Later")

• Default: How it looks at rest

• Hover: Color/shadow change on mouseover

• Active: Appearance while being clicked

• Disabled: When action isn't available

• Input fields (text, email, password)

• Dropdowns and selects

• Checkboxes and radio buttons

• Error states and messages

• Success confirmations

• Helper text formatting

• Image placement (top, left, or no image)

• Heading hierarchy within cards

• Body text limitations (3 lines max before truncation)

• CTA button placement

• Shadow or border treatment

• Primary nav styling and behavior

• Mobile menu treatment

• Breadcrumbs format

• Footer link organization

• Active state indicators

4. Pattern Documentation

• Skeleton screens for content areas

• Spinner styles and placement

• Progress bars for multi-step processes

• Error states if loading fails

• Friendly messaging (not "No results")

• Helpful next actions

• Illustration or icon if appropriate

• Success messages (green, top of screen, auto-dismiss after 5 seconds)

• Error messages (red, inline with problem area, persist until resolved)

• Warning messages (yellow, contextual placement)

• Information messages (blue, non-intrusive)

5. Usage Guidelines

• DO: Use primary blue for one CTA per screen

• DON'T: Use primary blue for links in body text

• Minimum contrast ratios (4.5:1 for normal text)

• Focus indicator styles

• Alt text guidelines

• Heading hierarchy rules

• Button text (verb + noun: "Download Report" not "Click Here")

• Error messages (what went wrong + how to fix it)

• Placeholder text (examples, not instructions)

• Microcopy tone (helpful, not clever)

Your Implementation Checklist

Week 1: Foundation and Audit

1. Brand voice description - Write three adjectives that describe how you sound, with a "but not" qualifier for each. Example: "Expert but not condescending, friendly but not unprofessional, direct but not harsh."

2. Core principles - Three beliefs that guide every decision. Make them specific to your business, not generic. "We believe small businesses deserve enterprise-level insights" beats "We value quality."

3. User mindset - One paragraph describing your typical user's emotional state when they arrive. Are they frustrated? Excited? Skeptical? Time-pressed? This context shapes every design decision.

• Colors that appear in your logo (these are non-negotiable)

• Colors that appear most frequently

• Colors that have poor contrast (test with WebAIM)

• 1-2 primary brand colors

• 2-3 secondary colors

• 3-4 grays

• UI states (error red, success green, warning yellow)

Week 2: Build Your Guide

1. Cover page - Guide version, last updated date, contact person

2. Brand foundation - Voice, principles, user context

3. Visual language - Colors, typography, spacing, all with specific values

4. Components - Each component with visual example and code/settings

5. Patterns - Interaction behaviors and states

6. Guidelines - Do's/don'ts, accessibility, writing

• Visual example (screenshot or live demo)

• Technical specifications (exact values)

• When to use / when not to use

• Implementation notes

• All colors as swatches with hex codes

• All heading levels with actual text

• All button types in all states

• Form fields with labels and error states

• Cards with real content

• Loading and empty states

<!-- Primary Button -->
<button class="btn btn-primary">
  Button Text
</button>

<!-- CSS -->
.btn-primary {
  background: #2B5CE6;
  color: white;
  padding: 12px 24px;
  border-radius: 4px;
  font-weight: 600;
  /* etc */
}

• Font: Helvetica Neue

• Size: 16px

• Color: #2B5CE6

• Padding: 12px vertical, 24px horizontal

Week 3: Implement and Enforce

1. Replace all colors with your documented palette

2. Standardize all typography to your scale

3. Rebuild buttons using your component patterns

4. Fix spacing to match your system

• Are all colors from the palette?

• Do all fonts match the scale?

• Are components being reused correctly?

• Is spacing consistent?

• Show them the pattern library

• Explain the color system

• Demonstrate component reuse

• Share the code snippets

• Color hex codes

• Font sizes

• Button classes/settings

• Spacing values

Ongoing Maintenance

• Checking if any unauthorized elements have crept in

• Updating documentation if you've added new components

• Testing color contrast if you've made any changes

• Verifying that your pattern library matches production

• Increment the version number (1.0, 1.1, etc.)

• Document what changed in a changelog

• Notify anyone who builds on your site

• Update the pattern library to match

Version 1.2 (March 2024)
- Added focus states to all form inputs
- Darkened primary blue from #2B5CE6 to #1E4FD8 for better contrast
- Introduced new "ghost" button variant for tertiary actions

Common Style Guide Disasters (And How to Avoid Them)

The ROI of Style Guide Discipline

Your Next 72 Hours

1. Screenshot your homepage. Circle every different color, font size, and button style. Count them. If you have more than 10 of anything, you need this guide.

2. Pick your primary brand color. Just one. Test it for contrast. If it fails, darken it until it passes. This is now your reference point for everything else.

3. Document your first component. Start with buttons. Decide on three types. Build them. Use them everywhere. Don't create any new buttons until these three can't solve your problem.