Theme Factory Studio

Comprehensive design system theming toolkit that generates, manages, and applies consistent color themes, dark/light modes, typography scales, and spacing systems across web applications.

When to Use This Skill

Choose Theme Factory when:

• Building a design system with consistent theming across components
• Implementing dark mode / light mode toggle functionality
• Generating accessible color palettes from brand colors
• Creating CSS custom property-based theme systems
• Migrating from hardcoded colors to a centralized theme

Consider alternatives when:

• Using a design tool like Figma for visual design
• Need full component library — use Material UI, Chakra, or Shadcn
• Need email templates — email clients don't support CSS custom properties

Quick Start

Copy
# Activate theme factory
claude skill activate smart-theme-factory-studio

# Generate a theme from brand color
claude "Generate a complete dark/light theme system from brand color #6366f1"

# Create a design token system
claude "Create a design token system with colors, typography, and spacing"

Example Theme Generation

Copy
// Theme definition with CSS custom properties
const lightTheme = {
  colors: {
    primary: { 50: '#eef2ff', 100: '#e0e7ff', 500: '#6366f1', 600: '#4f46e5', 900: '#312e81' },
    neutral: { 50: '#fafafa', 100: '#f5f5f5', 500: '#737373', 800: '#262626', 900: '#171717' },
    success: '#22c55e',
    warning: '#f59e0b',
    error: '#ef4444',
    background: '#ffffff',
    surface: '#f8fafc',
    text: { primary: '#0f172a', secondary: '#475569', muted: '#94a3b8' },
    border: '#e2e8f0',
  },
  typography: {
    fontFamily: { sans: 'Inter, system-ui, sans-serif', mono: 'JetBrains Mono, monospace' },
    fontSize: { xs: '0.75rem', sm: '0.875rem', base: '1rem', lg: '1.125rem', xl: '1.25rem', '2xl': '1.5rem', '3xl': '1.875rem', '4xl': '2.25rem' },
    lineHeight: { tight: '1.25', base: '1.5', relaxed: '1.75' },
  },
  spacing: { 0: '0', 1: '0.25rem', 2: '0.5rem', 3: '0.75rem', 4: '1rem', 6: '1.5rem', 8: '2rem', 12: '3rem', 16: '4rem' },
  radii: { sm: '0.25rem', md: '0.375rem', lg: '0.5rem', xl: '0.75rem', full: '9999px' },
  shadows: {
    sm: '0 1px 2px rgba(0,0,0,0.05)',
    md: '0 4px 6px -1px rgba(0,0,0,0.1)',
    lg: '0 10px 15px -3px rgba(0,0,0,0.1)',
  },
};

// Dark theme variant
const darkTheme = {
  ...lightTheme,
  colors: {
    ...lightTheme.colors,
    background: '#0f172a',
    surface: '#1e293b',
    text: { primary: '#f1f5f9', secondary: '#94a3b8', muted: '#64748b' },
    border: '#334155',
  },
};

Core Concepts

Theme Architecture

Layer	Contents	Example
Design Tokens	Primitive values (colors, sizes, fonts)	--color-blue-500: #3b82f6
Semantic Tokens	Purpose-driven references to primitives	--color-primary: var(--color-blue-500)
Component Tokens	Component-specific overrides	--button-bg: var(--color-primary)
Theme Modes	Light/dark/high-contrast variants	[data-theme="dark"] selectors

Color System Generation

Step	Process	Output
Base Color	Start with brand primary color	Single hex value
Scale Generation	Generate 50-950 shade scale using HSL	10 shade values
Semantic Mapping	Map shades to purposes (bg, text, border)	Semantic tokens
Contrast Check	Verify WCAG AA/AAA contrast ratios	Accessible pairs
Dark Inversion	Adjust scales for dark backgrounds	Dark mode palette
Accent Colors	Generate complementary/analogous accents	Additional palettes

Copy
/* CSS Custom Properties theme system */
:root {
  /* Primitive tokens */
  --color-indigo-50: #eef2ff;
  --color-indigo-500: #6366f1;
  --color-indigo-600: #4f46e5;
  --color-slate-50: #f8fafc;
  --color-slate-900: #0f172a;

  /* Semantic tokens (light mode default) */
  --color-bg: var(--color-slate-50);
  --color-text: var(--color-slate-900);
  --color-primary: var(--color-indigo-500);
  --color-primary-hover: var(--color-indigo-600);
  --color-border: #e2e8f0;
  --color-surface: #ffffff;

  /* Typography */
  --font-sans: 'Inter', system-ui, sans-serif;
  --font-mono: 'JetBrains Mono', monospace;
  --text-sm: 0.875rem;
  --text-base: 1rem;
  --text-lg: 1.125rem;

  /* Spacing */
  --space-1: 0.25rem;
  --space-2: 0.5rem;
  --space-4: 1rem;
  --space-8: 2rem;

  /* Radius */
  --radius-md: 0.375rem;
  --radius-lg: 0.5rem;
}

[data-theme="dark"] {
  --color-bg: var(--color-slate-900);
  --color-text: var(--color-slate-50);
  --color-border: #334155;
  --color-surface: #1e293b;
}

/* Component usage */
.button {
  background: var(--color-primary);
  color: white;
  padding: var(--space-2) var(--space-4);
  border-radius: var(--radius-md);
  font-family: var(--font-sans);
  font-size: var(--text-sm);
}

Configuration

Parameter	Description	Default
brand_color	Primary brand color (hex)	Required
color_mode	Generate: light, dark, or both	both
contrast_level	WCAG level: AA or AAA	AA
type_scale	Typography ratio: minor_third, major_third, perfect_fourth	major_third
spacing_base	Base spacing unit in rem	0.25
output_format	CSS, SCSS, JSON, Tailwind config	css
include_components	Generate component-level tokens	false

Best Practices

1. Use semantic token names, not descriptive color names — Name tokens by purpose (--color-primary, --color-danger) not by appearance (--color-blue, --color-red). This allows theme switching without renaming variables and keeps the design system flexible.

2. Generate full color scales from a single brand color — Use HSL manipulation to create a complete 50-950 scale from one input color. Adjust lightness linearly while slightly shifting saturation to maintain perceptual uniformity across the scale.

3. Test color contrast at every semantic pairing — Every text-on-background combination must meet WCAG AA (4.5:1 for normal text, 3:1 for large text). Automate contrast checking in your build process and fail on violations.

4. Implement theme switching with CSS custom properties, not class swapping — CSS custom properties cascade naturally and require changing only one attribute (data-theme="dark") to switch the entire theme. This is more efficient than toggling dozens of utility classes.

5. Include a system-preference-aware default — Use prefers-color-scheme media query to default to the user's OS preference, but allow manual override that persists in localStorage. This respects user preferences while giving explicit control.

Common Issues

Dark mode colors look washed out or lack contrast. Don't simply invert light mode colors. Dark mode needs its own carefully calibrated palette where primary colors are slightly brighter, text colors use 85-95% white (not pure white), and surfaces use graduated dark grays rather than pure black.

Theme switch causes a flash of unstyled content (FOUC). Load the theme preference from localStorage in a blocking <script> tag in <head> before any CSS loads. This sets the data-theme attribute synchronously, preventing the brief flash of the default theme.

Design tokens become inconsistent as the system grows. Establish governance rules: all new colors must map to an existing semantic token or justify a new one. Regular token audits identify unused, redundant, or off-system values. Use a token linter that flags hardcoded colors in component CSS.