Showing Posts From

Css

Design Tokens: Customizing Your Visual Identity

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 Examplebrand.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 contextsColor Relationship GuidelinesSecondary: Typically 10-20% darker than primary Accent: A complementary or analogous color that popsBackground Colors Background colors create visual hierarchy and depth:Token Purpose Examplebackground.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:Page - The base layer, slightly tinted Surface - Elevated cards and panels Muted - Recessed areas, sidebarsText Colors Text colors ensure readability across all contexts:Token Purpose Exampletext.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 minimumTypography 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 CombinationsHeading Body StylePlayfair Display Lora Elegant editorialMontserrat Open Sans Modern cleanMerriweather Source Sans Pro Traditional readableRoboto Slab Roboto Contemporary technicalPairing PrinciplesContrast: Choose fonts with different personalities Compatibility: Ensure similar x-heights and proportions Hierarchy: Headings should be visually distinct from body Readability: Body fonts must be highly legible at small sizesGoogle 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 headerDark 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 ApplyingVerify JSON syntax is valid Check that token paths match expected structure Clear browser cache and rebuild Inspect generated theme.json for correct valuesFonts Not LoadingEnsure font names exactly match Google Fonts catalog Check for typos in font family strings Verify quotes around multi-word font names Test with simpler fallback fonts firstDark Mode IssuesVerify allowToggle is true if toggle expected Check dark mode color contrast ratios Test in system dark mode to verify detection Inspect CSS custom properties in browser dev toolsConclusion 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 effortStart with the examples in this guide, then iterate until your design tokens perfectly capture your brand identity.