Design Tokens: Customizing Your Visual Identity

Design tokens are the foundation of consistent, maintainable visual design. In the Bookworm Light theme adapter, design tokens allow you to completely transform the look and feel of your site through simple JSON configuration - no CSS editing required.

What Are Design Tokens?

Design tokens are named entities that store visual design attributes. Instead of scattering color codes, font names, and spacing values throughout your codebase, you define them once in a central location and reference them everywhere.

Traditional approach:

.button {
  background-color: #8b5cf6;
  font-family: 'Playfair Display', serif;
  padding: 12px 24px;
}

.header {
  background-color: #8b5cf6;
  font-family: 'Playfair Display', serif;
}

Design token approach:

.button {
  background-color: var(--color-primary);
  font-family: var(--font-heading);
  padding: var(--spacing-3) var(--spacing-6);
}

.header {
  background-color: var(--color-primary);
  font-family: var(--font-heading);
}

With tokens, changing your primary brand color updates every button, link, and accent across your entire site.

Token Configuration in site.json

Your design tokens are defined in the designTokens section of your site.json file:

{
  "designTokens": {
    "colors": {
      "brand": {
        "primary": "#8b5cf6",
        "secondary": "#7c3aed",
        "accent": "#f472b6"
      },
      "background": {
        "page": "#faf5ff",
        "surface": "#ffffff",
        "muted": "#ede9fe"
      },
      "text": {
        "primary": "#1e1b4b",
        "secondary": "#6b7280",
        "link": "#8b5cf6"
      }
    },
    "typography": {
      "fonts": {
        "heading": "'Playfair Display', serif",
        "body": "'Lora', serif"
      }
    },
    "themeMode": {
      "default": "light",
      "allowToggle": true
    }
  }
}

Color System Deep Dive

Brand Colors

Your brand colors define the personality of your site:

Token	Purpose	Example
brand.primary	Main accent color, buttons, links	#8b5cf6 (purple)
brand.secondary	Hover states, gradients	#7c3aed (darker purple)
brand.accent	Highlights, tags, badges	#f472b6 (pink)

Choosing a Primary Color

Your primary color should:

• Reflect your brand identity
• Have sufficient contrast for accessibility
• Work well in both light and dark contexts

Color Relationship Guidelines

• Secondary: Typically 10-20% darker than primary
• Accent: A complementary or analogous color that pops

Background Colors

Background colors create visual hierarchy and depth:

Token	Purpose	Example
background.page	Main page background	#faf5ff (light purple)
background.surface	Cards, panels, elevated elements	#ffffff (white)
background.muted	Subtle backgrounds, code blocks	#ede9fe (lavender)

Creating Depth

Use background colors to create visual layers:

1. Page - The base layer, slightly tinted
2. Surface - Elevated cards and panels
3. Muted - Recessed areas, sidebars

Text Colors

Text colors ensure readability across all contexts:

Token	Purpose	Example
text.primary	Headings, important text	#1e1b4b (dark blue)
text.secondary	Body text, descriptions	#6b7280 (gray)
text.link	Hyperlinks	#8b5cf6 (matches primary)

Contrast Requirements

For WCAG AA accessibility:

• Normal text: 4.5:1 contrast ratio minimum
• Large text (18px+): 3:1 contrast ratio minimum

Typography Configuration

Font Stack Definition

{
  "typography": {
    "fonts": {
      "heading": "'Playfair Display', serif",
      "body": "'Lora', serif"
    }
  }
}

How Fonts Are Applied

The adapter transforms your font configuration into Bookworm Light’s theme.json format:

{
  "fonts": {
    "font_family": {
      "primary": "Lora:wght@400;500;600;700",
      "primary_type": "serif",
      "secondary": "Playfair+Display:wght@400;500;600;700;800",
      "secondary_type": "serif"
    }
  }
}

Font Pairing Best Practices

Classic Combinations

Heading	Body	Style
Playfair Display	Lora	Elegant editorial
Montserrat	Open Sans	Modern clean
Merriweather	Source Sans Pro	Traditional readable
Roboto Slab	Roboto	Contemporary technical

Pairing Principles

1. Contrast: Choose fonts with different personalities
2. Compatibility: Ensure similar x-heights and proportions
3. Hierarchy: Headings should be visually distinct from body
4. Readability: Body fonts must be highly legible at small sizes

Google Fonts Integration

The adapter automatically formats fonts for Google Fonts loading:

<link href="https://fonts.googleapis.com/css2?family=Playfair+Display:wght@400;500;600;700;800&family=Lora:wght@400;500;600;700&display=swap" rel="stylesheet">

Theme Mode Configuration

Light and Dark Mode

{
  "themeMode": {
    "default": "light",
    "allowToggle": true
  }
}

Options:

• default: "light" - Site loads in light mode
• default: "dark" - Site loads in dark mode
• default: "system" - Respects user’s OS preference
• allowToggle: true - Shows a toggle switch in the header

Dark Mode Token Overrides

For advanced dark mode customization, define dark mode specific colors:

{
  "themeMode": {
    "default": "light",
    "allowToggle": true,
    "darkMode": {
      "background": {
        "page": "#111827",
        "surface": "#1f2937"
      },
      "text": {
        "primary": "#f9fafb",
        "secondary": "#9ca3af"
      }
    }
  }
}

Generated Configuration Files

theme.json Output

The adapter generates a complete theme.json file:

{
  "colors": {
    "default": {
      "theme_color": {
        "primary": "#8b5cf6",
        "body": "#faf5ff",
        "border": "#ede9fe",
        "light": "#ede9fe",
        "dark": "#1e1b4b"
      },
      "text_color": {
        "text": "#6b7280",
        "text-dark": "#1e1b4b",
        "text-light": "#6b7280"
      }
    }
  },
  "fonts": {
    "font_family": {
      "primary": "Lora:wght@400;500;600;700",
      "primary_type": "serif",
      "secondary": "Playfair+Display:wght@400;500;600;700;800",
      "secondary_type": "serif"
    },
    "font_size": {
      "base": "16",
      "scale": "1.2"
    }
  }
}

CSS Custom Properties

The adapter also generates CSS overrides:

:root {
  --color-primary: #8b5cf6;
  --color-body: #faf5ff;
  --color-border: #ede9fe;
  --color-light: #ede9fe;
  --color-dark: #1e1b4b;
  --color-text: #6b7280;
  --color-text-dark: #1e1b4b;
  --color-accent: #f472b6;
  --color-secondary: #7c3aed;
  --color-link: #8b5cf6;
}

Real-World Examples

Corporate Blue Theme

{
  "designTokens": {
    "colors": {
      "brand": {
        "primary": "#2563eb",
        "secondary": "#1d4ed8",
        "accent": "#fbbf24"
      },
      "background": {
        "page": "#f8fafc",
        "surface": "#ffffff",
        "muted": "#e2e8f0"
      },
      "text": {
        "primary": "#1e293b",
        "secondary": "#64748b",
        "link": "#2563eb"
      }
    },
    "typography": {
      "fonts": {
        "heading": "'Inter', sans-serif",
        "body": "'Inter', sans-serif"
      }
    }
  }
}

Warm Magazine Theme

{
  "designTokens": {
    "colors": {
      "brand": {
        "primary": "#dc2626",
        "secondary": "#b91c1c",
        "accent": "#f97316"
      },
      "background": {
        "page": "#fffbeb",
        "surface": "#ffffff",
        "muted": "#fef3c7"
      },
      "text": {
        "primary": "#451a03",
        "secondary": "#78350f",
        "link": "#dc2626"
      }
    },
    "typography": {
      "fonts": {
        "heading": "'Libre Baskerville', serif",
        "body": "'Source Serif Pro', serif"
      }
    }
  }
}

Dark Tech Theme

{
  "designTokens": {
    "colors": {
      "brand": {
        "primary": "#22c55e",
        "secondary": "#16a34a",
        "accent": "#06b6d4"
      },
      "background": {
        "page": "#0f172a",
        "surface": "#1e293b",
        "muted": "#334155"
      },
      "text": {
        "primary": "#f1f5f9",
        "secondary": "#94a3b8",
        "link": "#22c55e"
      }
    },
    "typography": {
      "fonts": {
        "heading": "'JetBrains Mono', monospace",
        "body": "'IBM Plex Sans', sans-serif"
      }
    },
    "themeMode": {
      "default": "dark",
      "allowToggle": false
    }
  }
}

Troubleshooting

Colors Not Applying

1. Verify JSON syntax is valid
2. Check that token paths match expected structure
3. Clear browser cache and rebuild
4. Inspect generated theme.json for correct values

Fonts Not Loading

1. Ensure font names exactly match Google Fonts catalog
2. Check for typos in font family strings
3. Verify quotes around multi-word font names
4. Test with simpler fallback fonts first

Dark Mode Issues

1. Verify allowToggle is true if toggle expected
2. Check dark mode color contrast ratios
3. Test in system dark mode to verify detection
4. Inspect CSS custom properties in browser dev tools

Conclusion

Design tokens transform theme customization from a tedious CSS editing task into a simple configuration exercise. By defining your visual identity in site.json, you can:

• Maintain consistent branding across all pages
• Quickly experiment with different color schemes
• Support accessibility requirements systematically
• Enable dark mode with minimal effort

Start with the examples in this guide, then iterate until your design tokens perfectly capture your brand identity.