@poupe/theme-builder

Design token management and theme generation system for Material Design 2025 themes with automatic dark mode, CSS variables, and image-based color extraction.

Table of Contents

• Features
• Installation
• Usage
  • Basic Theme Creation
  • CSS Theme Generation
  • Theme from Image
  • Color Manipulation
• API Reference
  • Main Exports
  • Core Utilities
  • Server Utilities
• Color System
• CSS Variables
• Dark Mode
• Integration with Poupe Ecosystem
• Requirements
• License

Features

• 🎨 Material Design 2025 color system with automatic dark themes
• 🌓 Built-in dark mode support with CSS custom properties
• 🖼️ Generate color palettes from images using Material algorithms
• 🔧 Advanced color manipulation utilities (HCT, RGB, HSL, ARGB)
• 📦 Lightweight, tree-shakable API with TypeScript support
• 🧩 CSS variables generation for external customization
• 🎭 Theme scheme variants (vibrant, expressive, content, etc.)
• 🛠️ Server-side utilities for build-time theme generation
• 🎯 Material Design 3 state layer colors for interactive states

Installation

1# npm
2npm install -D @poupe/theme-builder
3
4# yarn
5yarn add -D @poupe/theme-builder
6
7# pnpm
8pnpm add -D @poupe/theme-builder

Usage

Basic Theme Creation

1import { makeTheme } from '@poupe/theme-builder'
2
3// Create Material Design 2025 theme with color roles
4const { dark, light } = makeTheme({
5  primary: '#1976d2',
6  secondary: '#9c27b0',
7  tertiary: '#ff4081',
8}, 'vibrant', 0.0)
9
10// Access color roles
11console.log(light.primary.value)    // Primary color in light theme
12console.log(dark.onPrimary.value)   // Text on primary in dark theme
13
14// Theme with state colors included by default
15console.log(light['primary-hover'])  // Primary hover state
16console.log(dark['on-primary-disabled']) // Disabled text on primary
17
18// Use CSS color-mix() for runtime state color generation
19// Fourth parameter accepts additional theme generation options
20const runtimeTheme = makeTheme({
21  primary: '#1976d2',
22}, 'content', 0.0, { useColorMix: true })

CSS Theme Generation

1import { makeCSSTheme } from '@poupe/theme-builder'
2
3// Generate CSS variables for dark/light themes
4const cssTheme = makeCSSTheme({
5  primary: '#6750A4',
6  secondary: '#958DA5',
7  error: '#B3261E',
8}, {
9  scheme: 'content',
10  contrastLevel: 0.5,
11  prefix: 'md-',
12  darkMode: ['.dark', 'media'],    // Multiple selectors + aliases
13  lightMode: '.light',
14})
15
16// Built-in responsive aliases
17makeCSSTheme(colors, {
18  darkMode: ['dark', 'mobile'],    // Uses media queries
19  lightMode: ['light', 'desktop']  // Now supports arrays too
20})
21
22// Advanced selector configuration
23const advancedTheme = makeCSSTheme(colors, {
24  darkMode: ['mobile', '.dark-mode'],    // Mobile + custom class
25  lightMode: ['desktop', '.light-mode'],  // Desktop + custom class
26})
27
28// Use generated CSS variables
29console.log(cssTheme.vars.primary)   // '--md-primary'
30console.log(cssTheme.styles)         // CSS rule objects

Theme from Image

1import { fromImageElement } from '@poupe/theme-builder'
2
3// Extract color from image element
4async function createImageTheme(imageElement: HTMLImageElement) {
5  const seedColor = await fromImageElement(imageElement)
6
7  const { dark, light } = makeTheme({
8    primary: seedColor.toHex(),
9  }, 'expressive')
10
11  return { dark, light }
12}

Color Manipulation

1import {
2  hct, colord, hexString, makeTonalPalette
3} from '@poupe/theme-builder/core'
4
5// HCT color space (Hue, Chroma, Tone)
6const color = hct('#1976d2')
7const lighter = color.withTone(80)   // Lighter variant
8const muted = color.withChroma(30)   // Lower saturation
9
10// Advanced color utilities
11const c = colord('#1976d2')
12console.log(c.toHsl())               // HSL representation
13console.log(c.lighten(0.2).toHex())  // Lightened color
14
15// Format colors
16console.log(hexString(lighter))      // Convert to hex string
17
18// Create tonal palette with full tone range (0-100)
19const palette = makeTonalPalette('#1976d2')
20console.log(palette.tone(50))        // Medium tone
21console.log(palette.tone(90))        // Light tone
22console.log(palette.tone(10))        // Dark tone
23
24// Harmonize colors to create cohesive palettes
25const primary = hct('#1976d2')
26const harmonized = makeTonalPalette('#9c27b0', primary)

State Layer Colors

Material Design 3 interactive state support:

1import {
2  makeStandardStateVariants,
3  getStateColorMixParams,
4  stateLayerOpacities
5} from '@poupe/theme-builder'
6
7// Generate state variants for theme colors
8const theme = makeTheme({ primary: '#6750A4' })
9const stateColors = makeStandardStateVariants(theme.light)
10
11// Access state colors
12console.log(stateColors['primary-hover'])     // 8% opacity
13console.log(stateColors['primary-focus'])     // 12% opacity
14console.log(stateColors['primary-pressed'])   // 12% opacity
15console.log(stateColors['on-primary-disabled']) // 38% opacity
16
17// Get CSS color-mix parameters for dynamic theming
18const params = getStateColorMixParams('primary', 'hover', '--md-')
19// Returns: {
20//   state: 'hover',
21//   baseColor: '--md-primary',
22//   onColor: '--md-on-primary',
23//   opacityPercent: 8
24// }
25
26// Material Design 3 opacity values
27console.log(stateLayerOpacities.hover)    // 0.08
28console.log(stateLayerOpacities.focus)    // 0.12
29console.log(stateLayerOpacities.pressed)  // 0.12
30console.log(stateLayerOpacities.dragged)  // 0.16
31console.log(stateLayerOpacities.disabled) // 0.12
32console.log(stateLayerOpacities.onDisabled) // 0.38

API Reference

Main Exports

1import {
2  // Theme generation
3  makeTheme,
4  makeCSSTheme,
5
6  // CSS utilities
7  assembleCSSColors,
8  defaultCSSThemeOptions,
9
10  // Image extraction
11  fromImageElement,
12
13  // State layer colors
14  makeStandardStateVariants,
15  makeCustomStateVariants,
16
17  // Color utilities (re-exported from core)
18  hct,
19  colord,
20  hexString,
21  rgbaString,
22} from '@poupe/theme-builder'

Core Utilities

Color manipulation and formatting utilities:

1import {
2  // Color types and creation
3  type Hct,
4  type HexColor,
5  hct,
6  colord,
7
8  // Color formatting
9  hexString,
10  rgbaString,
11
12  // Color conversion
13  argb,
14  rgb,
15
16  // State layer utilities
17  stateLayerOpacities,
18  makeStateLayerColors,
19  makeStateVariants,
20  getStateColorMixParams,
21
22  // CSS utilities (re-exported)
23  formatCSSRules,
24} from '@poupe/theme-builder/core'

Server Utilities

Server-side color processing, validation, and CSS response utilities:

1import {
2  // Parameter processing
3  getColorParam,
4  getThemeSchemeParam,
5
6  // CSS formatting utilities
7  stringifyCSSRulesArray,
8  stringifyCSSRulesArrayStream,
9  stringifyCSSRulesArrayAsStream,
10  stringifyCSSRulesArrayAsResponse,
11  stringifyCSSRulesArrayAsStreamingResponse,
12
13  // Color types (re-exported)
14  type HexColor,
15  hct,
16  colord,
17} from '@poupe/theme-builder/server'
18
19// Convert to CSS string (no trailing newline)
20const cssString = stringifyCSSRulesArray([
21  { '.theme': { '--primary': '#6750A4' } }
22])
23
24// Convert with camelCase to kebab-case normalization
25const normalizedCSS = stringifyCSSRulesArray([
26  { fontSize: '16px', backgroundColor: 'blue' }
27], { normalizeProperties: true })
28// Result: 'font-size: 16px;\nbackground-color: blue;'
29
30// Create ReadableStream (perfect for Cloudflare Workers)
31const stream = stringifyCSSRulesArrayAsStream([
32  { '.theme': { '--primary': '#6750A4' } }
33])
34const response = new Response(stream, {
35  headers: { 'Content-Type': 'text/css' }
36})
37
38// Create Response object with headers
39const response = stringifyCSSRulesArrayAsResponse([
40  { '.theme': { '--primary': '#6750A4' } }
41])
42
43// Create streaming Response for large CSS files
44const streamingResponse = stringifyCSSRulesArrayAsStreamingResponse([
45  // Large array of CSS rules
46])

Color System

Material Design 2025 color roles and theming:

• Primary: Main brand color and variants (primary, primaryDim, onPrimary, primaryContainer, onPrimaryContainer)
• Secondary: Supporting colors (secondary, secondaryDim, onSecondary, secondaryContainer, onSecondaryContainer)
• Tertiary: Accent colors (tertiary, tertiaryDim, onTertiary, tertiaryContainer, onTertiaryContainer)
• Error: Error states (error, onError, errorContainer, onErrorContainer)
• Neutral: Surface and outline colors (surface, onSurface, outline, etc.)

1const { dark, light } = makeTheme({
2  primary: '#6750A4',
3  secondary: '#958DA5',
4  tertiary: '#B58392',
5  neutral: '#938F94',
6  neutralVariant: '#948F94',
7  error: '#B3261E',
8}, 'content', 0.0)
9
10// Access all color roles
11console.log(light.primaryContainer.value)  // Primary container color
12console.log(dark.onSurfaceVariant.value)   // Text on surface variant

CSS Variables

Automatic CSS custom property generation:

1const cssTheme = makeCSSTheme({
2  primary: '#6750A4',
3}, {
4  prefix: 'md-',         // Variable prefix
5  darkMode: '.dark',     // Dark mode selector
6  lightMode: '.light',   // Light mode selector (optional)
7  darkSuffix: '-dark',   // Dark variable suffix
8  lightSuffix: '-light', // Light variable suffix
9})
10
11// Generated variables
12cssTheme.vars.primary            // '--md-primary'
13cssTheme.vars.onPrimary          // '--md-on-primary'
14cssTheme.styles                  // CSS rule objects

Dark Mode

Built-in dark mode support with flexible selectors and aliases:

1// Class-based dark mode (default)
2makeCSSTheme(colors, { darkMode: '.dark' })
3
4// Media query dark mode using built-in alias
5makeCSSTheme(colors, { darkMode: 'media' })
6
7// Multiple selectors
8makeCSSTheme(colors, { darkMode: ['.dark', '.theme-dark'] })
9
10// Built-in responsive aliases
11makeCSSTheme(colors, {
12  darkMode: ['dark', 'mobile'],  // Uses media queries
13  lightMode: 'light'
14})
15
16// Custom selectors
17makeCSSTheme(colors, {
18  darkMode: '[data-theme="dark"]',
19  lightMode: '[data-theme="light"]'
20})
21
22// Disable dark mode
23makeCSSTheme(colors, { darkMode: false })

Built-in Selector Aliases

The theme builder includes convenient aliases for common media queries:

• 'media' or 'dark' → '@media (prefers-color-scheme: dark)'
• 'light' → '@media (prefers-color-scheme: light)'
• 'mobile' → '@media (max-width: 768px)'
• 'tablet' → '@media (min-width: 769px) and (max-width: 1024px)'
• 'desktop' → '@media (min-width: 1025px)'

1// Using aliases for responsive theming
2const cssTheme = makeCSSTheme(colors, {
3  darkMode: ['dark', 'tablet'],    // Dark mode + tablet screens
4  lightMode: ['light', 'desktop'], // Light mode + desktop screens
5})

Integration with Poupe Ecosystem

• @poupe/css - CSS utility library
• @poupe/tailwindcss - TailwindCSS integration
• @poupe/vue - Vue components library
• @poupe/nuxt - Nuxt integration

Requirements

• Node.js >=20.19.1
• TypeScript-friendly environment

License

MIT licensed.