Creating a Visual Style Guide for Your Extension

Most Chrome extensions look like they were designed by accident. A popup with mismatched font sizes, inconsistent spacing, buttons that change style between views, and colors that seem pulled from different palettes entirely. Users do not consciously notice these problems, but they feel them. An extension that looks inconsistent feels untrustworthy. And in a marketplace where uninstall rates hit 60% in the first week, trust matters more than features.

A visual style guide is the document that prevents this. It is not a luxury reserved for design teams at large companies. Even a solo developer working on a single extension benefits from codifying design decisions. The guide becomes the single source of truth that keeps your popup, options page, content script overlays, and onboarding screens visually coherent.

This post walks through creating a practical style guide for Chrome extensions — not a theoretical design system, but a working reference you will actually use during development.

Why Extensions Need Style Guides More Than Web Apps#

Web applications typically have one interface. Extensions have several. A typical extension might include a popup (400px wide), an options page (full width), content script injections (embedded in unknown pages), a side panel, notification elements, and an onboarding tab. Each of these surfaces has different constraints, different contexts, and different user expectations.

Without a style guide, each surface drifts. You pick a slightly different shade of blue for the side panel because you cannot remember the exact hex code. You use 14px body text in the popup but 16px on the options page because it "felt right" at the time. Six months later, your extension looks like it was built by three different people.

Color Palette Creation#

Your extension needs fewer colors than you think. Most successful extensions operate with a primary color, a secondary color, three to four neutral grays, and semantic colors for success, warning, and error states.

Here is what a well-structured CSS custom properties file looks like for an extension:

/* tokens.css — Extension Design Tokens */
:root {
  /* Primary palette */
  --color-primary-50: #f0f9ff;
  --color-primary-100: #e0f2fe;
  --color-primary-500: #0ea5e9;
  --color-primary-600: #0284c7;
  --color-primary-700: #0369a1;
  --color-primary-900: #0c4a6e;
 
  /* Neutrals (tinted toward primary) */
  --color-neutral-50: #f8fafc;
  --color-neutral-100: #f1f5f9;
  --color-neutral-300: #cbd5e1;
  --color-neutral-500: #64748b;
  --color-neutral-700: #334155;
  --color-neutral-900: #0f172a;
 
  /* Semantic */
  --color-success: #22c55e;
  --color-warning: #f59e0b;
  --color-error: #ef4444;
  --color-info: #3b82f6;
 
  /* Typography */
  --font-family: system-ui, -apple-system, sans-serif;
  --font-size-heading: 1.25rem;
  --font-size-subheading: 0.938rem;
  --font-size-body: 0.875rem;
  --font-size-caption: 0.75rem;
 
  /* Spacing */
  --space-1: 4px;
  --space-2: 8px;
  --space-3: 12px;
  --space-4: 16px;
  --space-6: 24px;
  --space-8: 32px;
 
  /* Borders */
  --radius-sm: 4px;
  --radius-md: 8px;
  --radius-lg: 12px;
  --radius-full: 9999px;
}

Visual Consistency Rules#

Getting the tokens right is half the battle. The other half is applying them consistently. This is where most solo developers fail — they define a palette but then hardcode #333 in a component because it is faster than looking up the token name.

Content scripts deserve special attention. When you inject UI into a host page, that page's CSS can bleed into your elements. A style guide should document how to isolate injected components — usually through Shadow DOM or highly specific selectors with a namespace prefix.

// Content script: creating an isolated UI element
function createIsolatedUI() {
  const host = document.createElement('div');
  host.id = 'my-extension-root';
  const shadow = host.attachShadow({ mode: 'closed' });
 
  // Import your style guide tokens inside the shadow
  const style = document.createElement('style');
  style.textContent = `
    :host {
      --color-primary-500: #0ea5e9;
      --font-family: system-ui, -apple-system, sans-serif;
      --font-size-body: 14px;
      --space-4: 16px;
      all: initial; /* Reset inherited host page styles */
    }
    .panel {
      font-family: var(--font-family);
      font-size: var(--font-size-body);
      padding: var(--space-4);
      background: white;
      border: 1px solid #e2e8f0;
      border-radius: 8px;
    }
  `;
  shadow.appendChild(style);
  return { host, shadow };
}

Choosing the Right Design Tools#

You need a tool to create and maintain your style guide. The choice depends on your workflow and team size.

For solo developers building Chrome extensions, the most practical setup is a CSS custom properties file (your tokens) combined with a Markdown document or Storybook instance showing how tokens combine into components. You do not need Figma unless you are designing complex visual interfaces. Most extension UIs are form-heavy and functional — tokens plus a few documented component patterns cover 90% of cases.

Dark Mode Considerations#

Chrome now supports prefers-color-scheme, and users increasingly expect dark mode. A style guide that only covers light mode is incomplete. But dark mode is not just "swap white for black." It requires deliberate decisions about surface elevation, contrast ratios, and color desaturation.

Key principles for extension dark mode:

The background should not be pure black (#000). Use a dark gray like #1a1a2e or #0f172a instead. Pure black creates too much contrast with text, causing eye strain. Elevation in dark mode is shown through lighter surface colors rather than shadows — a card on a dark background should be slightly lighter than the background, not floating above it with a shadow.

Colors need desaturation. Your primary blue at #0ea5e9 might look great on a white background but becomes harsh and glowing on a dark background. Reduce saturation by 10-20% and increase lightness slightly for dark mode variants.

/* Dark mode tokens */
@media (prefers-color-scheme: dark) {
  :root {
    --color-primary-500: #38bdf8; /* Lighter, less saturated */
    --color-neutral-50: #0f172a;  /* Inverted: darkest neutral is now the bg */
    --color-neutral-100: #1e293b;
    --color-neutral-300: #475569;
    --color-neutral-500: #94a3b8;
    --color-neutral-700: #cbd5e1;
    --color-neutral-900: #f1f5f9; /* Inverted: lightest neutral is now text */
    --color-surface: #1e293b;
    --color-surface-elevated: #334155;
  }
}

Test your dark mode in all extension contexts. The popup, options page, and side panel all respect the system setting. Content script overlays need manual handling since they exist inside the host page's color context.

Style Guide Completeness Checklist#

Before calling your style guide done, verify you have covered every category. Missing one creates a gap where inconsistency will creep in.

Making the Guide a Living Document#

A style guide is only useful if it stays current. The most common failure mode is creating a beautiful style guide document that gets ignored three weeks later because updating it feels like extra work.

The best way to keep a style guide alive is to make the code the guide. Your CSS custom properties file is already a style guide — it documents every color, size, and spacing value. If you use a component library (even a small one with just buttons, inputs, and cards), those components are living documentation. When you change a token value, every component updates automatically.

For extension developers using React or Preact in their popup and options page, consider building a small Storybook that renders each component in every state. This takes an afternoon to set up and saves hours of future debugging when something "looks wrong" and you cannot figure out which component drifted from the standard.

“A design system is not a project. It is a product, serving products.”

The investment in a style guide pays off exponentially if you ever build a second extension. You carry the entire design system forward, and your second extension instantly feels related to the first — creating brand recognition that most indie extension developers never achieve. Users who trust one of your extensions are far more likely to install another if it visually feels like it comes from the same maker.

Start small. Define your tokens. Document your components. Keep it in code. The guide will grow naturally as your extension does, and six months from now you will wonder how you ever built anything without one.