Design Tokens & Theming

Overview

Our design system implements a thoughtfully structured token architecture that follows modern best practices with Tailwind v4’s theme variables. This system provides the foundation for consistent, maintainable styling across the application.

Core Philosophy: Canvas vs. Paint

Our token system is built on a simple but powerful metaphor:

• Canvas Tokens (primary, secondary, tertiary): Foundational background tokens for large page sections and component backgrounds
• Paint Tokens (brand, action, accent): Accent tokens for deliberate highlights, interactive elements, and brand expression

Token Architecture

Two-Tiered System

1. Core Tokens (Tier 1)

   • Raw color values with descriptive names
   • Single source of truth for all color values
   • Pattern: --core-{color}-{variant}
   • Example: --core-orange-aperol: oklch(0.66 0.22 34);

2. Semantic Tokens (Tier 2)

   • Map core tokens to specific CSS properties and UI purposes
   • Generate comprehensive Tailwind utilities automatically
   • Pattern: --{property}-color-{semantic}-{level}
   • Example: --background-color-action: var(--core-orange-rose);

Mode Framework

Modes control the theme of entire regions:

• Brand Modes (khonsu): Page-wide visual identity
• Compound Modes (header, footer, critical): Regional theme overrides within brand modes

Quick Usage Guide

Basic Token Usage

<!-- Surface tokens for structural elements -->
<div class="bg-primary text-primary border-primary">
  <!-- Accent tokens for highlights -->
  <button class="bg-action text-action">Call to Action</button>
</div>

CSS Components

.btn-primary {
  @apply bg-action text-action rounded-md px-4 py-2;
}

Mode Application

<section data-mode="footer">
  <!-- Surface tokens are automatically redefined within this mode -->
  <div class="bg-primary text-primary">Footer content</div>
</section>

Complete Documentation

📖 For comprehensive documentation, examples, and implementation details, visit:

Design Tokens Strategy - Storybook

The Storybook documentation includes:

• Detailed token hierarchy and naming conventions
• Complete color palettes and semantic mappings
• Advanced mode composition patterns
• Step-by-step implementation workflows
• Typography token system
• Accessibility relationships
• File organization structure