The Token System

Semantic color mapping that makes themes intelligent and adaptable.

Understanding Design Tokens

Design tokens are the secret to creating themes that are both powerful and maintainable. Instead of hard-coding specific colors throughout your theme, tokens create a semantic layer that describes the purpose of each color. This abstraction might seem like extra complexity at first, but it's what enables professional-grade themes that can adapt to different contexts without manual updates.

Think of tokens as meaningful names for design decisions. Rather than saying "make this border #E5E5E5," you say "make this border use border-color." The token system then determines what border-color means in different contexts—it might be gray-200 in light mode, gray-700 in dark mode, or even adapt based on the visual type or emphasis level. This semantic approach is why you can switch between radically different visual styles with a single click.

Power UI's token system goes beyond simple color mapping. It understands the relationships between different UI elements and ensures they work harmoniously together. When you change your neutral palette from cool gray to warm gray, every token that references those shades updates automatically while maintaining proper contrast ratios and visual hierarchy. This systematic approach eliminates the tedious work of manually updating hundreds of color properties across dozens of visual types.

Why We Use a Token System

Theme-Wide Consistency

Power BI themes contain hundreds of color properties spread across different visual types. Without tokens, maintaining consistency is nearly impossible. Imagine manually ensuring that every border across tables, charts, cards, and slicers uses the exact same shade of gray. With tokens, you define "border-color" once, and it's automatically applied everywhere borders appear. Change the token definition, and every border updates instantly.

Instant Mode Switching

Light and dark modes aren't just about inverting colors—they require thoughtful adjustments to maintain readability and visual hierarchy. Tokens make this possible by mapping to different color values based on the active mode. A token like "text-primary" might map to gray-900 in light mode for dark text on light backgrounds, but switch to gray-100 in dark mode for light text on dark backgrounds. This intelligent mapping ensures your reports look professional in any lighting condition.

Brand Flexibility

Organizations often need themes for different contexts—executive dashboards might use sophisticated blue-grays, while customer-facing reports use warmer, friendlier tones. With tokens, you can create these variations by simply swapping the underlying palettes. The semantic structure remains the same, ensuring that primary buttons, headers, and key metrics maintain their visual importance regardless of the color scheme.

Future-Proof Design

As Power BI evolves and adds new visual types or properties, a token-based theme can adapt without starting from scratch. New properties can reference existing tokens, automatically inheriting your design decisions. This forward compatibility means your investment in theme design continues to pay dividends as the platform grows.

How Tokens Work: Visual Examples

Basic Token Mapping

Token: border-color

Palette Color

gray-300

Applied To

  • • Table borders
  • • Card outlines
  • • Visual dividers
  • • Input fields

Mode-Aware Token Behavior

Light Mode

background
white
text-primary
gray-900
border-color
gray-300

Dark Mode

background
gray-900
text-primary
gray-100
border-color
gray-700

Token Inheritance & Relationships

When you change your base palette...

Cool Gray

Warm Gray

All tokens automatically update...

surface-1
border-subtle
text-secondary

Common Token Categories

Power UI organizes tokens into logical categories that map to how designers think about visual hierarchy. Understanding these categories helps you customize themes effectively and create your own token mappings when needed.

Surface Tokens

Define the layering system for backgrounds and cards

surface-canvas
surface-1
surface-2
surface-3

Text Hierarchy Tokens

Establish clear content hierarchy through text colors

text-primaryPrimary content and headers
text-secondarySupporting content and labels
text-tertiarySubtle hints and metadata
text-disabledInactive or unavailable content

Interactive State Tokens

Provide consistent feedback for user interactions

Standard States

  • hover-overlay - Subtle hover indication
  • active-overlay - Pressed/active state
  • selected-border - Selection emphasis

Focus States

  • focus-ring - Keyboard focus indicator
  • focus-background - Focused item background

Light & Dark Mode with Tokens

The token system is what makes instant mode switching possible. Each token knows how to adapt its color value based on the current mode, ensuring your reports maintain readability and visual hierarchy whether viewed in a bright office or on a dashboard in a dimly lit operations center.

How Mode Switching Works

  1. 1

    Toggle Theme Mode

    Click the theme mode toggle in the Foundation panel

  2. 2

    Tokens Recalculate

    Each token updates its color value based on the new mode

  3. 3

    Theme Updates Globally

    All visuals instantly reflect the new color mappings

Important: The exported Power BI theme file will contain the color values for the currently active mode. Power BI itself doesn't support dynamic mode switching—you'll need to export separate theme files for light and dark modes if you need both.

Customizing Token Mappings

While Power UI provides intelligent default token mappings, you have full control to customize how tokens map to colors. This flexibility lets you create unique visual treatments while maintaining the benefits of the token system.

Advanced Token Features

  • •
    Visual-Specific Tokens: Different visuals can use different token mappings. For example, tables might use subtle borders while cards use stronger ones.
  • •
    Conditional Tokens: Tokens can adapt based on context, such as using higher contrast for small text or reducing contrast for large background areas.
  • •
    Brand Tokens: Create custom tokens for brand-specific elements that remain consistent regardless of theme variations.

Token System Best Practices

Respect the Semantic Layer

The power of tokens comes from their semantic meaning. When customizing token mappings, maintain the intended purpose—don't map text-primary to a light color just because you prefer it. Instead, adjust your palette or create new tokens that better express your design intent while preserving the logical structure.

Test Across Contexts

Tokens affect multiple visual types and properties. When adjusting a token mapping, preview your changes across different visuals—tables, charts, cards, and slicers. What works beautifully for one visual type might create problems in another. The preview panel is your best friend for catching these issues early.

Document Custom Tokens

If you create custom tokens or significantly modify default mappings, document these changes. Future theme maintainers (including yourself) will appreciate understanding why certain tokens map to unexpected colors. This documentation is especially important for team environments where multiple people might work with the theme.

Next: Typography

Learn how to configure fonts and text styling to complete your professional theme.

Continue to Typography →