Colors
Reference color palettes and semantic tokens with practical usage guidance for consistent UI theming.
Overview
The VD color system is built on a comprehensive palette of colors organized by semantic meaning. Colors are theme-aware and adapt automatically between light and dark modes while maintaining accessibility standards.
Color System Tiers
The color architecture is organized into three distinct tiers:
Root Colors
Root colors contain color definitions in their purest form. In this tier, color tokens are mapped directly to raw hex values.
Brand Colors
Brand colors map semantic color tokens to root colors. Different brands can configure distinct root colors for the same semantic token.
Mapped Colors
Mapped colors are the theme-aware tokens used directly in application UI. These tokens adapt automatically based on the active theme.
Not all colors are available from mapped variables. Colors that do not depend on dark and light mode, like opaque colors (black and white scales), are available from brand tokens.
Root Color Palettes
Raw, pure hex color definitions that form the base tier of the color system.
BlueGlow
Grey
Green
Red
Orange
Blue
Opaque White
Opaque Black
Opaque Neutral
Brand Color Palettes
Brand colors map semantic tokens to root colors. Palettes can vary based on the selected brand configuration in the top navigation.
Primary
Error
Success
Warning
Info
Neutral
White
Black
Utilities
Mapped Color Palettes
Theme-aware color tokens mapped to brand tokens for UI rendering. These tokens automatically adapt between light and dark modes.
Content
Default
Primary
Success
Error
Warning
Info
Neutral
Background
Default
Primary
Success
Error
Warning
Info
Neutral
Overlay
Border
Default
Primary
Success
Neutral
Error
Warning
Info
Usage Guidelines
How to implement color tokens and switch themes in application code.
Basic Color Implementation
Apply color tokens using CSS custom properties:
colors-usage.css
Copy code
Theme Switching
Toggle between light and dark themes by setting the data-theme attribute on the root HTML element. All semantic colors adjust automatically.
theme-switching.html
Copy code
Best Practices
Follow these rules and conventions to maintain consistent, accessible, and theme-safe color usage.
General Rules
- All colors must be applied using VD tokens — never hardcode hex, RGB, or HSL values in CSS, HTML, or component templates.
- Apply colors semantically, reflecting status, state, or purpose (e.g., use
errortokens for errors, not a raw red). - Differentiate usage across text, background, border, and icon categories — each has its own dedicated set of tokens.
- Always prefer mapped tokens over brand or root tokens in application code, as they are theme-aware.
Token Naming Convention
All mapped color tokens follow a consistent naming pattern:
token-pattern
Copy code
Content Colors
Use --vd-color-content-{semantic}-{variant} tokens for both text and icons. Available semantics: default, primary, success, error, warning, info, neutral. Each offers base, secondary, and tertiary variants. The default semantic also includes a disabled variant.
Use -on-* tokens (e.g., --vd-color-content-primary-on-base) when placing content on colored backgrounds to ensure proper contrast.
Background Colors
Use --vd-color-background-{semantic}-{variant} tokens for surfaces and containers. Each semantic (primary, success, error, warning, info, neutral) provides base, secondary, and tertiary variants plus corresponding *-hover states. Use --vd-color-background-overlay-default for modals, tooltips, and overlay backdrops.
Border Colors
Use --vd-color-border-{semantic}-{variant} tokens for all borders and outlines. Each semantic provides base, secondary, and tertiary variants. The default semantic also includes a disabled variant for inactive UI elements.
White & Black Tokens
For opaque color scales, use --vd-color-white-100 through --vd-color-white-1000 and --vd-color-black-100 through --vd-color-black-1000. These are available from brand tokens only (not mapped), as they do not change between light and dark themes. Never use raw hex codes.
Do's and Don'ts
Do
do.css
Copy code
Don't
dont.css
Copy code