Design Tokens
A complete reference of all VD design tokens — color, typography, and scale — with naming conventions and usage guidance for Angular, Flutter, and Swift.
Overview
Design tokens are the single source of truth for all visual decisions in the Vroxal Design System. They encode colors, typography, spacing, borders, and radii — each following a consistent naming pattern that makes the intent immediately clear, on every platform.
How Tokens Are Defined, Per Platform
The naming intent is identical everywhere, but the underlying mechanism is not. Angular resolves tokens at runtime in the browser; Flutter and Swift compile them in as native constants.
Angular
Standalone npm package — installed separately from the component library.
- Resolves as
- Plain CSS custom properties, resolved live in the browser at runtime.
- Theme switch
:root[data-theme="dark"]override block swaps values instantly.
Flutter
No separate token package — installing the component package is enough.
- Resolves as
- Compile-time Dart constants (
VdColorScheme,VdSpacing,VdFont…). - Theme switch
VdColorScheme.of(context)resolves a different constant set fromTheme.of(context).brightness.
Swift
No separate token package — adding the VroxalDesign SPM dependency is enough.
- Resolves as
- Private static constants (
Color.vd*,VdSpacing,VdFont…). - Theme switch
Color(light:dark:)resolves the system trait collection automatically.
How to Use Tokens
A minimal card built entirely from tokens — color, spacing, radius, border, and typography — on each platform.
Reference tokens as CSS custom properties
Import the stylesheet once, then reach for var(--vd-...) anywhere in your CSS. Every token — color, spacing, radius, typography — is a plain CSS variable.
styles.css
Copy code
Color Tokens
Semantic color tokens for content (text & icons), backgrounds, and borders. Always prefer these mapped tokens over raw hex values so your UI adapts automatically to theme changes. See the Colors page for the complete palette across every semantic group and variant.
Token Structure
Swatches and the full resolved palette live on the Colors page. Every color token is a Type, a Variant, and (usually) a State — the three-part structure is identical on every platform, only the spelling changes: dash-case on Angular, camelCase on Flutter and Swift. Below is every value each part can take.
content — text & icon colors · background — surface colors · border — outline, divider, ring colors
+ overlay exists only within Background, and only as a Base state
hover — Background only · disabled — Default content/borders only · always-light/always-dark — Default only. All ten exist identically on Angular, Flutter, and Swift.
Valid type, variant and state combination
Not every Variant supports every State — this is what's actually available:
Type | Variant | Available States |
|---|---|---|
content | default | base, secondary, tertiary, disabled, always-light, always-dark |
content | primary, success, error, warning, info, neutral | base, secondary, tertiary, on-base, on-secondary, on-tertiary |
background | default | base, secondary, tertiary, disabled, always-light, always-dark |
background | primary, success, error, warning, info, neutral | base, base-hover, secondary, secondary-hover, tertiary, tertiary-hover |
background | overlay | base |
border | default | base, secondary, tertiary, disabled |
border | primary, success, error, warning, info, neutral | base, secondary, tertiary |
styles.css
Copy code
Token Tiers
Color tokens resolve through three tiers — Root → Brand → Mapped — on every platform; only the naming syntax differs (dash-case on Angular, camelCase on Flutter and Swift). See the Colors page for the full root palette — this page focuses on the Mapped tier, which is what component code actually consumes.
Blue Glow · 500
Raw hex value — the purest form, one step above nothing.
Primary · 500
The semantic scale — aliases a Root color.
content · primary · base
background · primary · base
What component code actually consumes.
Rebranding the product's primary color happens at the Brand tier — see the Theming page for the full walkthrough.
Dark Mode
Every mapped color token adapts to light/dark automatically — Angular via a :root[data-theme='dark'] override block, Flutter via VdColorScheme.of(context) reading Theme.of(context).brightness, and Swift via Color(light:dark:) resolving the system trait collection. No manual branching is required on any platform.
Typography Tokens
Typography tokens are exposed as CSS utility classes on Angular, and as VdFont constants on Flutter and Swift. Prefer semantic HTML elements (h1–h6, p, label) on Angular — they inherit the correct styles automatically. See the Typography page for utility-class usage guidance and font-family details.
Token Structure
A different, simpler shape than color — just two parts, no extra prefix or State: a Tier and a Size. Angular exposes these as CSS utility classes; Flutter and Swift expose them as VdFont constants.
display — hero/page headings · headline — section structure · title — component titles · body — reading content · label — UI/control text
display/headline/title: large/medium/small only · body: adds extra-large & extra-small · label: adds extra-small only (no extra-large) · body-medium also has an -italic modifier
Valid tier and size combinations
Not every tier supports every size — body is the only tier with all five:
Tier | Extra Large | Large | Medium | Small | Extra Small |
|---|---|---|---|---|---|
display | — | ✓ | ✓ | ✓ | — |
headline | — | ✓ | ✓ | ✓ | — |
title | — | ✓ | ✓ | ✓ | — |
body | ✓ | ✓ | ✓ (+ italic) | ✓ | ✓ |
label | — | ✓ | ✓ | ✓ | ✓ |
Rebranding the product's typeface works the same way — see the Theming page for the full walkthrough.
card.html
Copy code
Scale Tokens
Spacing, border width, border radius, and icon size tokens establish a consistent visual rhythm. Never hardcode numeric sizes — always use scale tokens. See the Scale page for detailed usage guidance.
Token Structure
Two parts, no Variant or State — every scale token is a Type and a Value. Angular exposes these as CSS custom properties; Flutter and Swift expose them as VdSpacing / VdRadius / VdBorderWidth / VdIconSize constants. Value's vocabulary depends entirely on Type:
Valid type and value combinations
Each Type has its own Value vocabulary — this is what's available:
Type | Available Values |
|---|---|
spacing | 0, 50, 100 … 3000, negative50 … negative600 |
border-width | none, sm, md, lg, xl |
border-radius | none, xs, sm, md, lg, xl, xxl, xxxl, full |
icon-size | xs, sm, md, lg, xl |
card.css
Copy code
Breakpoint Tokens
Used by Angular's responsive typography and layout utilities. Flutter and Swift have no equivalent breakpoint tokens today.
Name | Token | Notes |
|---|---|---|
Mobile | --vd-device-min-width-mobile | 0px and up |
Tablet | --vd-device-min-width-tablet | 768px and up |
Desktop | --vd-device-min-width-desktop | 1200px and up |
Best Practices
Practical rules for consuming tokens consistently, on every platform.
Core Principles
- Always use design tokens — never hardcode hex values, pixel/point sizes, or raw numbers, on any platform.
- Apply tokens semantically: choose based on intent, not visual appearance.
- Use mapped color tokens (not root or brand tier) in application code — they are theme-aware and adapt automatically between light and dark mode.
- Prefer semantic HTML for typography where it exists — Angular inherits the correct styles automatically from
h1–h6,p, andlabel. Flutter and Swift have no such inheritance layer, so referencingVdFontdirectly is the normal way to apply typography there, not a fallback. - Component defaults win — a
Vd*component already applies the correct tokens internally. Reach for a token directly only when building custom UI.
Priority Order
Identical intent on every platform: prefer what the component already gives you.
Priority order
Copy code
Do's and Don'ts
Do
do.css
Copy code
Don't
dont.css
Copy code