@via-ds/tokens

Design tokens for the via-ds design system.

Installation

pnpm add @via-ds/tokens

Usage

CSS Custom Properties

Import the token CSS tokens

@import '@via-ds/tokens/fonts.css';
@import '@via-ds/tokens/tokens.css';

Use the tokens as CSS custom properties:

.button {
  background-color: var(--color-light-background-primary);
  color: var(--color-light-text-primary);
  padding: var(--space-200);
  font: var(--typography-body);
}

JavaScript / TypeScript

Import tokens directly in JS/TS:

import lightTokens from '@via-ds/tokens/light.tokens';
import spacingTokens from '@via-ds/tokens/spacing.tokens';

// Access token values
const bgColor = lightTokens.color.background.primary.$value; // "#ffffff"

Token Naming

Primitive Tokens

Primitive tokens are the base color palette without theme prefixes:

--color-gray-light3
--color-blue-base
--color-green-dark1

Semantic Color Tokens (Light/Dark)

Semantic tokens include the theme name in their CSS variable:

--color-light-background-primary
--color-light-text-secondary
--color-dark-background-primary
--color-dark-text-secondary

Spacing Tokens

Spacing tokens follow a numeric scale:

--space-100  /* 4px */
--space-200  /* 8px */
--space-400  /* 16px */

Font Tokens

Font family tokens define the typefaces:

--font-family-body       /* Euclid Circular A */
--font-family-serif      /* MongoDB Value Serif */
--font-family-monospace  /* Source Code Pro */

Font size tokens define the type scale:

--font-size-small     /* 11px */
--font-size-base      /* 13px */
--font-size-heading1  /* 48px */

Typography Tokens

Typography tokens are shorthand font values combining weight, size, line-height, and family:

--typography-heading1  /* 400 48px/1.33em serif */
--typography-body      /* 400 13px/1.5em body */
--typography-code      /* 400 13px/1.5em monospace */

Use typography tokens with the CSS font shorthand property:

.heading {
  font: var(--typography-heading1);
}

Tailwind v4

Import the Via theme to generate utility classes from all Via tokens:

@import 'tailwindcss';
@import '@via-ds/tokens/tailwind.css';

This registers all tokens with Tailwind's @theme directive. Utility classes are generated automatically based on the variable namespace:

<button class="bg-green-base text-black p-400 rounded-200 font-body">
  Hello Via!
</button>

<div
  class="bg-dark-background-primary text-dark-text-primary border border-dark-border-primary rounded-300 p-400"
>
  Dark mode card
</div>

| Token category | CSS variable | Example classes | | ------------------ | ---------------------------- | -------------------------------------------------------- | | Colors (primitive) | --color-green-base | bg-green-base, text-green-base, border-green-base | | Colors (semantic) | --color-light-text-primary | text-light-text-primary, bg-light-background-primary | | Spacing | --spacing-400 | p-400, px-200, m-600, gap-300 | | Border radius | --radius-200 | rounded-200, rounded-300 | | Font family | --font-body | font-body, font-serif, font-monospace | | Font size | --text-heading1 | text-heading1, text-base, text-small | | Shadow | --shadow-light-default | shadow-light-default | | Duration | --duration-default | duration-default, duration-faster |

Note: Color semantic tokens include the theme name (light/dark). Use Tailwind's dark: variant to apply dark-mode tokens when the user's system preference is dark:

<div
  class="bg-light-background-primary text-light-text-primary
            dark:bg-dark-background-primary dark:text-dark-text-primary
            border border-light-border-primary dark:border-dark-border-primary
            rounded-300 p-400"
>
  Adaptive card
</div>

Build Process

To rebuild tokens after modifying source files:

pnpm build

The build uses Style Dictionary to transform DTCG-format tokens in src/ into CSS and JavaScript output in dist/.