Github

Design Tokens

A complete reference of all VD design tokens — color, typography, and scale — with naming conventions and usage guidance.

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.

Token Naming Convention

All VD tokens follow a structured naming pattern based on their category, type, variant, and optional state:

token-structure.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.

Content Colors

Use content tokens for text and icon colors. Each semantic level provides base, secondary, and tertiary variants.

Default
Primary
Success
Error
Warning
Info
Neutral
Semantic Purpose
Base
Secondary
Tertiary
Notes
Default
--vd-color-content-default-base
--vd-color-content-default-secondary
--vd-color-content-default-tertiary
Regular UI text and icons
Primary
--vd-color-content-primary-base
--vd-color-content-primary-secondary
--vd-color-content-primary-tertiary
Brand emphasis
Success
--vd-color-content-success-base
--vd-color-content-success-secondary
--vd-color-content-success-tertiary
Positive feedback
Error
--vd-color-content-error-base
--vd-color-content-error-secondary
--vd-color-content-error-tertiary
Negative/error feedback
Warning
--vd-color-content-warning-base
--vd-color-content-warning-secondary
--vd-color-content-warning-tertiary
Warning messages
Info
--vd-color-content-info-base
--vd-color-content-info-secondary
--vd-color-content-info-tertiary
Informational messages
Neutral
--vd-color-content-neutral-base
--vd-color-content-neutral-secondary
--vd-color-content-neutral-tertiary
Subtle or secondary content

Background Colors

Use background tokens for surface, container, and overlay colors.

Default
Primary
Success
Error
Warning
Info
Neutral
Overlay
Semantic Purpose
Base
Secondary
Tertiary
Notes
Default
--vd-color-background-default-base
--vd-color-background-default-secondary
--vd-color-background-default-tertiary
General surfaces
Primary
--vd-color-background-primary-base
--vd-color-background-primary-secondary
--vd-color-background-primary-tertiary
Buttons, highlights
Success
--vd-color-background-success-base
--vd-color-background-success-secondary
--vd-color-background-success-tertiary
Positive UI feedback
Error
--vd-color-background-error-base
--vd-color-background-error-secondary
--vd-color-background-error-tertiary
Error/critical states
Warning
--vd-color-background-warning-base
--vd-color-background-warning-secondary
--vd-color-background-warning-tertiary
Warnings
Info
--vd-color-background-info-base
--vd-color-background-info-secondary
--vd-color-background-info-tertiary
Info messages
Neutral
--vd-color-background-neutral-base
--vd-color-background-neutral-secondary
--vd-color-background-neutral-tertiary
Default UI backgrounds
Overlay
--vd-color-background-overlay-base
N/A
N/A
Modals, tooltips, overlays

Border Colors

Use border tokens for all outline, divider, and ring colors.

Default
Primary
Success
Error
Warning
Info
Neutral
Semantic Purpose
Base
Secondary
Tertiary
Notes
Default
--vd-color-border-default-base
--vd-color-border-default-secondary
--vd-color-border-default-tertiary
General borders
Primary
--vd-color-border-primary-base
--vd-color-border-primary-secondary
--vd-color-border-primary-tertiary
Highlighted controls
Success
--vd-color-border-success-base
--vd-color-border-success-secondary
--vd-color-border-success-tertiary
Positive feedback
Error
--vd-color-border-error-base
--vd-color-border-error-secondary
--vd-color-border-error-tertiary
Error states
Warning
--vd-color-border-warning-base
--vd-color-border-warning-secondary
--vd-color-border-warning-tertiary
Warnings
Info
--vd-color-border-info-base
--vd-color-border-info-secondary
--vd-color-border-info-tertiary
Info messages
Neutral
--vd-color-border-neutral-base
--vd-color-border-neutral-secondary
--vd-color-border-neutral-tertiary
Default borders

Applying Color Tokens

Apply tokens for text, backgrounds, and borders using CSS custom properties:

color-usage.css

Copy code

Typography Tokens

Typography tokens are exposed as CSS utility classes. Prefer semantic HTML elements (h1–h6, p, label) which inherit the correct styles automatically. Use utility classes only when semantic HTML is insufficient.

Type Scale

Live preview of every typography level with its utility class:

.display-largePage hero heading (h1)
The quick brown fox
.display-mediumSection hero (h2)
The quick brown fox
.display-smallSection heading (h3)
The quick brown fox
.headline-largeMajor subsection (h4)
The quick brown fox
.headline-mediumSubsection (h5)
The quick brown fox
.headline-smallMinor heading (h6)
The quick brown fox
.title-largeCards, panels
The quick brown fox
.title-mediumGrouped content
The quick brown fox
.title-smallCompact headers
The quick brown fox
.body-extra-largeEmphasis reading
The quick brown fox
.body-largeComfortable reading
The quick brown fox
.body-mediumDefault paragraph (p)
The quick brown fox
.body-smallSecondary text
The quick brown fox
.body-extra-smallMetadata
The quick brown fox
.label-largeStrong UI labels
The quick brown fox
.label-mediumDefault UI text (button, label, a)
The quick brown fox
.label-smallCompact UI
The quick brown fox
.label-extra-smallDense UI
The quick brown fox

All Typography Tokens

Name
Token
Notes
display-large
.display-large
Page hero heading (h1)
display-medium
.display-medium
Section hero (h2)
display-small
.display-small
Section heading (h3)
headline-large
.headline-large
Major subsection (h4)
headline-medium
.headline-medium
Subsection (h5)
headline-small
.headline-small
Minor heading (h6)
title-large
.title-large
Cards, panels
title-medium
.title-medium
Grouped content
title-small
.title-small
Compact headers
body-extra-large
.body-extra-large
Emphasis reading

Usage

typography-usage.html

Copy code

Scale Tokens

Spacing, border width, and border radius tokens establish a consistent visual rhythm. Never hardcode numeric sizes — always use scale tokens.

Spacing

Spacing tokens for padding, margin, and gap:

--vd-scale-spacing-0No spacing
--vd-scale-spacing-50Extra-tight spacing
--vd-scale-spacing-100Very tight spacing
--vd-scale-spacing-200Tight spacing
--vd-scale-spacing-300Small spacing
--vd-scale-spacing-400Medium spacing
--vd-scale-spacing-600Large spacing
--vd-scale-spacing-800Extra-large spacing
--vd-scale-spacing-1000Massive spacing
--vd-scale-spacing-1200Layout padding
--vd-scale-spacing-1600Section separation
--vd-scale-spacing-1800Section/gutter spacing
--vd-scale-spacing-2400Major layout spacing
--vd-scale-spacing-3000Extreme spacing
Name
Token
Notes
0
--vd-scale-spacing-0
No spacing
50
--vd-scale-spacing-50
Extra-tight spacing
100
--vd-scale-spacing-100
Very tight spacing
200
--vd-scale-spacing-200
Tight spacing
300
--vd-scale-spacing-300
Small spacing
400
--vd-scale-spacing-400
Medium spacing
600
--vd-scale-spacing-600
Large spacing
800
--vd-scale-spacing-800
Extra-large spacing
1000
--vd-scale-spacing-1000
Massive spacing
1200
--vd-scale-spacing-1200
Layout padding

Border Width

Standardised border widths:

None

--vd-scale-border-width-none

Small

--vd-scale-border-width-sm

Medium

--vd-scale-border-width-md

Large

--vd-scale-border-width-lg

Extra Large

--vd-scale-border-width-xl

Name
Token
Notes
None
--vd-scale-border-width-none
No border
Small
--vd-scale-border-width-sm
Minor separators, outlines
Medium
--vd-scale-border-width-md
Standard component borders
Large
--vd-scale-border-width-lg
Emphasis borders
Extra Large
--vd-scale-border-width-xl
Strong emphasis, highlights

Border Radius

Corner radius tokens for components and containers:

None

--vd-scale-border-radius-none

XS

--vd-scale-border-radius-xs

SM

--vd-scale-border-radius-sm

MD

--vd-scale-border-radius-md

LG

--vd-scale-border-radius-lg

XL

--vd-scale-border-radius-xl

XXL

--vd-scale-border-radius-xxl

XXXL

--vd-scale-border-radius-xxxl

Full

--vd-scale-border-radius-full

Name
Token
Notes
None
--vd-scale-border-radius-none
Sharp corners
XS
--vd-scale-border-radius-xs
Very subtle rounding
SM
--vd-scale-border-radius-sm
Slight rounding
MD
--vd-scale-border-radius-md
Standard rounding
LG
--vd-scale-border-radius-lg
Rounded components, cards
XL
--vd-scale-border-radius-xl
Prominent rounding
XXL
--vd-scale-border-radius-xxl
Modal/dialog rounding
XXXL
--vd-scale-border-radius-xxxl
Hero/UI accent rounding
Full
--vd-scale-border-radius-full
Fully circular (avatars, badges)

Applying Scale Tokens

scale-usage.css

Copy code

Best Practices

Core Principles

  • Always use design tokens — never hardcode hex values, pixel sizes, or raw numbers.
  • Apply tokens semantically: choose based on intent, not visual appearance.
  • Use mapped color tokens (not brand or root) in application code — they are theme-aware.
  • Typography tokens are inherited via semantic HTML; utility classes are a last resort.

Do's and Don'ts

do.css

Copy code

dont.css

Copy code