What are design tokens?

Design tokens are the single source of truth for visual decisions, covering color, typography, spacing, borders, shadows, motion, and z-index.

How do I switch themes?

Theme switching is done by applying a root-level attribute (e.g., data-theme) and overriding token values in theme files; tokens are consumed via CSS variables and can be stored in localStorage for persistence.

Is RTL and accessibility supported?

Yes. RTL is enabled through CSS logical properties, and accessibility is supported with WCAG contrast guidance, high-contrast themes, and reduced motion options.

theming-components

Scanned

npx machina-cli add skill ancoleman/ai-design-components/theming-components --openclaw

Files (1)

SKILL.md

9.0 KB

Design Tokens & Theming System

Comprehensive design token system providing the foundational styling architecture for all component skills, enabling brand customization, theme switching, RTL support, and consistent visual design.

Overview

Design tokens are the single source of truth for all visual design decisions. This skill provides:

Complete Token Taxonomy: 7 core categories (color, typography, spacing, borders, shadows, motion, z-index)
Theme Switching: Light/dark mode, high-contrast, custom brand themes
RTL/i18n Support: CSS logical properties for automatic right-to-left language support
Multi-Platform Export: CSS variables, SCSS, iOS Swift, Android XML, JavaScript
Component Integration: Skill chaining architecture for consistent styling across all components

Critical Architectural Principle:

Component Skills (Behavior + Structure) → Use tokens for ALL visual styling
Design Tokens (Styling Variables)       → Define colors, spacing, typography
Theme Files (Token Overrides)           → Light, dark, brand-specific values

Quick Start

Using Tokens in Components

Step 1: Reference tokens in your component:

.button {
  background-color: var(--button-bg-primary);
  color: var(--button-text-primary);
  padding-inline: var(--button-padding-inline);
  padding-block: var(--button-padding-block);
  border-radius: var(--button-border-radius);
  transition: var(--transition-fast);
}

Step 2: Themes automatically apply:

<!-- Light theme -->
<html data-theme="light">
  <button class="button">Primary Button</button>
</html>

<!-- Dark theme (same component, different appearance) -->
<html data-theme="dark">
  <button class="button">Primary Button</button>
</html>

No code changes needed - theme switching is automatic!

Basic Theme Switching

function setTheme(themeName) {
  document.documentElement.setAttribute('data-theme', themeName);
  localStorage.setItem('theme', themeName);
}

function toggleTheme() {
  const current = document.documentElement.getAttribute('data-theme');
  setTheme(current === 'dark' ? 'light' : 'dark');
}

// Load saved theme on page load
setTheme(localStorage.getItem('theme') || 'light');

Token Taxonomy (7 Core Categories)

1. Color Tokens

3-tier hierarchy: Primitive → Semantic → Component

/* Primitive (9-shade scales) */
--color-blue-500: #3B82F6;

/* Semantic (purpose-based) */
--color-primary: var(--color-blue-500);
--color-success: var(--color-green-500);
--color-error: var(--color-red-500);

/* Component-specific */
--button-bg-primary: var(--color-primary);

Complete color system: See references/color-system.md

2. Spacing Tokens

4px base scale:

--space-1: 4px;   --space-2: 8px;   --space-4: 16px;
--space-6: 24px;  --space-8: 32px;  --space-12: 48px;

/* Semantic */
--spacing-sm: var(--space-2);   /* 8px */
--spacing-md: var(--space-4);   /* 16px */
--spacing-lg: var(--space-6);   /* 24px */

3. Typography Tokens

--font-sans: 'Inter', -apple-system, sans-serif;
--font-mono: 'Fira Code', monospace;

--font-size-sm: 14px;
--font-size-base: 16px;
--font-size-lg: 18px;

--font-weight-normal: 400;
--font-weight-semibold: 600;
--font-weight-bold: 700;

4. Border & Radius Tokens

--border-width-thin: 1px;
--border-width-medium: 2px;

--radius-sm: 4px;
--radius-md: 8px;
--radius-lg: 12px;
--radius-full: 9999px;

5. Shadow Tokens

--shadow-sm: 0 2px 4px rgba(0, 0, 0, 0.07);
--shadow-md: 0 4px 8px rgba(0, 0, 0, 0.1);
--shadow-lg: 0 8px 16px rgba(0, 0, 0, 0.12);

--shadow-focus-primary: 0 0 0 3px rgba(59, 130, 246, 0.3);

6. Motion Tokens

--duration-fast: 150ms;
--duration-normal: 200ms;

--ease-out: cubic-bezier(0, 0, 0.2, 1);
--transition-fast: all var(--duration-fast) var(--ease-out);

Reduced motion support:

@media (prefers-reduced-motion: reduce) {
  :root { --transition-fast: none; }
}

7. Z-Index Tokens

--z-dropdown: 1000;
--z-modal-backdrop: 1040;
--z-modal: 1050;
--z-tooltip: 1070;

Theme Architecture

Light/Dark Themes

/* themes/light.css */
:root {
  --color-primary: #3B82F6;
  --color-background: #FFFFFF;
  --color-text-primary: #1F2937;
}

/* themes/dark.css */
:root[data-theme="dark"] {
  --color-primary: #60A5FA;
  --color-background: #111827;
  --color-text-primary: #F9FAFB;
}

Custom Brand Theme

:root[data-theme="my-brand"] {
  --color-primary: #FF6B35;
  --font-sans: 'Poppins', sans-serif;
  --radius-md: 12px;
}

Complete theme guide: See references/theme-switching.md

CSS Logical Properties (RTL Support)

Use logical properties for automatic RTL language support:

Physical (Avoid)	Logical (Use)
`margin-left`	`margin-inline-start`
`padding-right`	`padding-inline-end`
`text-align: left`	`text-align: start`

/* Correct - auto-flips in RTL */
.button {
  padding-inline: var(--button-padding-inline);
  margin-inline-start: var(--spacing-sm);
}

Complete RTL guide: See references/logical-properties.md

Component Integration

All component skills use this naming convention:

--{component}-{property}-{variant?}-{state?}

Examples:

--button-bg-primary
--button-bg-primary-hover
--input-border-color-focus
--chart-color-1

Components use tokens for ALL styling:

.button {
  background-color: var(--button-bg-primary);
  border-radius: var(--button-border-radius);
}

Theme changes automatically update all components.

Complete integration guide: See references/component-integration.md

Accessibility

WCAG 2.1 AA Compliance

Normal text: 4.5:1 contrast minimum
Large text (18px+): 3:1 minimum
UI components: 3:1 minimum

High-Contrast Theme

:root[data-theme="high-contrast"] {
  --color-primary: #0000FF;
  --color-text-primary: #000000;
  /* 7:1 contrast (WCAG AAA) */
}

Reduced Motion

@media (prefers-reduced-motion: reduce) {
  :root {
    --duration-fast: 0ms;
    --transition-fast: none;
  }
}

Complete accessibility guide: See references/accessibility-tokens.md

Platform Exports (Style Dictionary)

Transform tokens to any platform:

JSON Tokens → Style Dictionary → CSS Variables
                               → iOS Swift
                               → Android XML
                               → JavaScript

npm run build-tokens

Complete setup guide: See references/style-dictionary-setup.md

W3C Token Format

{
  "color": {
    "primary": {
      "$value": "#3B82F6",
      "$type": "color"
    }
  }
}

Scripts

# Generate color scale from base color
python scripts/generate_color_scale.py --base "#3B82F6"

# Validate token structure
python scripts/validate_tokens.py

# Check WCAG contrast ratios
python scripts/validate_contrast.py

# Build all platforms
npm run build-tokens

References

Core Systems:

references/color-system.md - Complete color scales and semantics
references/typography-system.md - Type scales and fonts
references/spacing-system.md - Spacing scale and rhythm

Implementation:

references/theme-switching.md - Light/dark mode, custom themes
references/component-integration.md - How skills use tokens
references/logical-properties.md - RTL support patterns

Tools & Accessibility:

references/style-dictionary-setup.md - Multi-platform build
references/accessibility-tokens.md - WCAG compliance

Key Takeaways

Design tokens are the foundation - All visual styling flows from tokens
3-level hierarchy - Primitive → Semantic → Component tokens
7 core categories - Color, spacing, typography, borders, shadows, motion, z-index
Theme switching built-in - Light, dark, high-contrast, custom brands
RTL support automatic - CSS logical properties enable right-to-left languages
Accessibility first - WCAG compliance, reduced motion, high contrast
Referenced by all skills - Every component skill uses design tokens

Progressive disclosure: This SKILL.md provides overview and quick start. Detailed documentation in references/ directory.

Skill chaining architecture: See SKILL_CHAINING_ARCHITECTURE.md

Source

git clone https://github.com/ancoleman/ai-design-components/blob/main/skills/theming-components/SKILL.mdView on GitHub

Overview

Design tokens act as the single source of truth for visual design decisions. This skill delivers a complete token taxonomy (color, typography, spacing, borders, shadows, motion, z-index), plus theme switching, RTL support, and accessibility considerations to ensure consistent, customizable UI across all components.

How This Skill Works

Tokens are defined as centralized variables and exposed as CSS custom properties (and platform exports). Theme files override token values for light, dark, or brand-specific themes, and components consume tokens via standardized CSS variables, enabling consistent styling across the entire system. RTL support uses CSS logical properties, and accessibility features (contrast, reduced motion) are baked into token decisions and theme options.

When to Use It

When theming components or implementing light/dark mode across an app
When creating brand styles or customizing visual design consistently
When enforcing a shared design system for multiple components
When enabling RTL/i18n support across languages
When exporting tokens for CSS, SCSS, iOS, Android, or JavaScript integration

Quick Start

Step 1: Define tokens for color, typography, spacing, borders, shadows, motion, and z-index, establishing primitive, semantic, and component-specific layers
Step 2: Create theme files (e.g., light, dark, brand) and implement theme switching via a root data-theme attribute and CSS variable overrides
Step 3: Consume tokens in components using var(--token-name) and set up multi-platform exports (CSS variables, SCSS, iOS, Android, JS)

Best Practices

Define a complete token taxonomy (color, typography, spacing, borders, shadows, motion, z-index) before implementing components
Prefer CSS variables for runtime theme switching and easy overrides
Centralize theme overrides in dedicated theme files (light, dark, brand) and apply via a data-theme attribute or theme provider
Incorporate accessibility from the start: WCAG contrast, high-contrast themes, and reduced motion tokens
Test RTL scenarios using CSS logical properties and verify cross-language rendering

Example Use Cases

Implementing a dashboard with light/dark modes and a high-contrast option for accessibility
Creating brand-specific themes across a product family with shared tokens
Enforcing consistent typography, spacing, and color across all widgets
Adding RTL support for Arabic and Hebrew interfaces using CSS logical properties
Exporting tokens to CSS variables, SCSS, iOS Swift, Android XML, and JavaScript for multi-platform apps

Frequently Asked Questions

Add this skill to your agents