wabtec-internal-volt-foundations

v1.4.0

Published

a month ago

Volt foundations library

0High
0Medium
0Low

@volt/volt-foundations

The design token foundation layer of the Volt Design System (VDS). This library defines and distributes the visual grammar — colors, typography, spacing, elevation, radius, opacity, and border thickness — consumed by every Volt component library.

volt-foundations is not a component library. It ships no UI components. Its output is a compiled CSS file (CSS custom properties) and a compiled SCSS file (Sass variables, mixins, and functions) that downstream libraries (volt-basic-components, volt-extended-components, volt-dataviz) use as their single source of design truth.

Overview

Every visual property in the Volt Design System traces back to a token defined in this library. The build process compiles SCSS source into two distribution artifacts:

| Artifact | Path | Purpose | |---|---|---| | volt-foundations.css | dist/volt-foundations/volt-foundations.css | CSS custom properties registered on :root body. Consumed at runtime — works inside Web Component shadow DOM via CSS inheritance. | | volt-foundations.scss | dist/volt-foundations/volt-foundations.scss | Concatenated SCSS: Sass variables, mixins (font-style, themedCssVars), and palette maps. Consumed at build time by downstream SCSS. | | Icons | dist/assets/icons/ | 202 SVG icons shipped with the design system. | | Fonts | dist/assets/fonts/ | Roboto Flex variable font. | | JSON Tokens | dist/assets/json/ | Design token exports for Figma synchronization. |

How it fits in the VDS ecosystem

@volt/volt-foundations
        │
        ├── volt-basic-components      (direct dependency — v1.39.0)
        │         │
        │         └── volt-extended-components   (transitive dependency)
        │
        └── volt-dataviz               (direct dependency — v1.37.1)

Installation

Prerequisites
You must be connected to the Wabtec corporate VPN to reach the private npm registry.
Node.js ≥ 18 and either npm or yarn are required.

1. Create or update your `.npmrc` file

In the root of your project (next to package.json), create a .npmrc file with the following line so npm/yarn resolves @volt scoped packages from the Wabtec GitLab registry:

@volt:registry=https://gitlab.corp.wabtec.com/api/v4/packages/npm/

Note: This line tells your package manager to use the Wabtec GitLab package registry only for packages in the @volt scope. All other packages continue to resolve from the public npm registry.

2. Install the package

# npm
npm install @volt/volt-foundations --save

# yarn
yarn add @volt/volt-foundations

3. Verify the installed files

After installation you should see the following structure under node_modules/@volt/volt-foundations/dist/:

dist/
├── volt-foundations/
│   ├── volt-foundations.css    ← import this for runtime CSS custom properties
│   └── volt-foundations.scss   ← import this for build-time Sass access
├── assets/
│   ├── fonts/                  ← Roboto Flex variable font
│   ├── icons/                  ← 202 SVG icons
│   └── json/                   ← Figma token exports
└── types/                      ← TypeScript definitions

Quick Start

The minimal setup requires loading the compiled CSS so that all CSS custom properties are registered on :root body before any component renders.

Vanilla HTML

<!DOCTYPE html>
<html lang="en">
  <head>
    <meta charset="UTF-8" />
    <!-- 1. Load the foundations token stylesheet -->
    <link
      rel="stylesheet"
      href="node_modules/@volt/volt-foundations/dist/volt-foundations/volt-foundations.css"
    />
    <style>
      /* 2. Use tokens immediately — no extra imports needed */
      .card {
        background-color: var(--surface-medium);
        border: 1px solid var(--color-border-low);
        border-radius: var(--radius-medium);
        padding: var(--spacing-05);
        color: var(--color-text-high);
        font-family: 'Roboto Flex', sans-serif;
      }
    </style>
  </head>
  <body>
    <div class="card">Hello, Volt Design System</div>
  </body>
</html>

JavaScript / Bundler (Webpack, Vite, etc.)

// main.js / main.ts
import '@volt/volt-foundations/dist/volt-foundations/volt-foundations.css';

// styles.scss — for Sass build-time access to variables and mixins
@import '~@volt/volt-foundations/dist/volt-foundations/volt-foundations';

// Or with the modern @use syntax (recommended)
@use '~@volt/volt-foundations/dist/volt-foundations/volt-foundations' as foundations;

Features

Design Tokens as CSS Custom Properties — All tokens are registered as native CSS custom properties, making them available everywhere: plain HTML, Angular, React, Vue, and inside Web Component shadow DOM without any special configuration.
Dual Distribution (CSS + SCSS) — Ships both a compiled CSS file (for runtime) and a Sass file (for build-time mixin and variable access).
Light and Dark Theme Support — A full light/dark theme system is built in. Tokens automatically switch when a .theme-dark class is applied to any ancestor element.
Typography System — A font-style() SCSS mixin covers four type scales (display, headline, title, body) with up to 5 size variants each, all backed by CSS custom properties.
Color Palettes — Six brand palettes (brand, green, yellow, red, grey, orange) with 11–14 tonal steps each, plus semantic color tokens for backgrounds, borders, icons, text, and interactions in both themes.
Data Visualization Palettes — Categorical (12 colors), sequential (5 palettes × 16 shades), and diverging (3 palettes × 16 shades) palettes optimized for chart and graph use.
Spacing Scale — 22-step spacing system (00–21) from 0rem to 5rem in 0.125rem (2px) increments.
Elevation System — 11 z-index layers and 7 shadow definitions for consistent depth and layering across components.
Border Radius Tokens — Five radius options: sharp, medium, large, pill, and circle.
Roboto Flex Variable Font — Bundled font with full weight and width axes support.
202 SVG Icons — A comprehensive icon set covering UI and industry-specific (rail/transport) use cases.
Figma Token Sync — JSON token exports in dist/assets/json/ keep Figma design files and code in sync.

Usage Examples

CSS Custom Properties (runtime)

Once volt-foundations.css is loaded, all tokens are available via var() in any stylesheet — including inside Web Component shadow DOM, where CSS custom properties inherit across shadow boundaries automatically.

/* Colors */
.button-primary {
  background-color: var(--color-background-brand-default);
  color: var(--color-text-high);
  border: 1px solid var(--color-border-brand);
}

.button-primary:hover {
  background-color: var(--color-background-brand-hover);
}

/* Spacing */
.form-field {
  padding: var(--spacing-03) var(--spacing-04);  /* 0.5rem 0.75rem */
  margin-bottom: var(--spacing-05);              /* 1rem */
  gap: var(--spacing-02);                        /* 0.25rem */
}

/* Border radius */
.chip {
  border-radius: var(--radius-pill);
}

.avatar {
  border-radius: var(--radius-circle);
}

/* Elevation */
.dropdown-panel {
  z-index: var(--elevation-layer-03);
  box-shadow: var(--elevation-shadow-02);
}

/* Surfaces */
.card {
  background-color: var(--surface-medium);
  border: 1px solid var(--color-border-low);
  border-radius: var(--radius-medium);
}

SCSS Variables and Mixins (build time)

Import the .scss distribution to access Sass variables, palette maps, and utility functions at compile time.

@import '~@volt/volt-foundations/dist/volt-foundations/volt-foundations';

// Access palette maps directly in Sass
.my-component {
  // Brand palette — use map.get($brand, 500) or map.get($brand, main)
  color: map.get($brand, main);        // #007DBA
  border-color: map.get($brand, 300);  // #66B1D5

  // Green palette
  background-color: map.get($green, 50);  // #F2F7E8
}

// Static color variables
.overlay {
  background-color: $black-lower;   // rgba(0,0,0,0.16)
}

.inverse-text {
  color: $white;  // #ffffff
}

Typography Mixin

The font-style() mixin applies the complete typographic style (font-size, font-weight, line-height, letter-spacing) for any scale and size combination. It emits CSS custom property references — not hardcoded values — so the result remains theme-aware.

@import '~@volt/volt-foundations/dist/volt-foundations/volt-foundations';

// Signature: font-style($level, $size, $weight: "")
// $level  → display | headline | title | body
// $size   → large | medium | small | extra-small | 2x-small (availability depends on $level)
// $weight → optional override: font-light | font-semibold | font-bold

.page-title {
  @include font-style(headline, large);
  // Outputs: font-size 2rem / font-weight 600 / line-height 2.5rem
}

.section-label {
  @include font-style(title, medium);
  // Outputs: font-size 1rem / font-weight 600 / line-height 1.5rem
}

.body-copy {
  @include font-style(body, medium);
  // Outputs: font-size 0.875rem / font-weight 300 / line-height 1.25rem
}

.helper-text {
  @include font-style(body, small);
  // Outputs: font-size 0.75rem / font-weight 300 / line-height 1rem
}

// Override font weight independently
.emphasis {
  @include font-style(body, medium, font-semibold);
}

Available utility typography CSS classes (generated automatically, usable in HTML):

<!-- Applied directly in markup without SCSS -->
<h1 class="vds-font-headline-large">Page Headline</h1>
<p class="vds-font-body-medium">Body paragraph copy</p>
<span class="vds-font-title-small">Card label</span>

Theming (Light / Dark)

The default theme is light. To switch a section of the UI to dark mode, apply .theme-dark to any ancestor element. All semantic color tokens (text, background, border, icon, surface) resolve to their dark-theme values automatically within that scope.

<!-- Light theme (default) — no class needed -->
<div class="card">Light card</div>

<!-- Dark theme — apply to any ancestor -->
<div class="theme-dark">
  <div class="card">Dark card</div>
  <nav class="sidebar">Dark sidebar</nav>
</div>

/* Semantic tokens that switch automatically between themes */
.card {
  background-color: var(--surface-medium);       /* light: #F5F6F6  |  dark: #1F2831 */
  color: var(--color-text-high);                 /* light: #041821  |  dark: #F5F6F6 */
  border-color: var(--color-border-low);         /* light: rgba(4,24,33,0.32)  |  dark variant */
}

Web components with shadow DOM automatically inherit the active theme's CSS custom properties because CSS custom properties cross shadow boundaries through standard CSS inheritance. No additional configuration is required inside the shadow root.

Using in a Stencil Component Library

This is the recommended integration pattern for Stencil-based component libraries (matches the setup used by volt-basic-components and volt-extended-components).

stencil.config.ts:

import { Config } from '@stencil/core';
import { sass } from '@stencil/sass';

export const config: Config = {
  globalStyle: 'src/styles/style.scss',
  plugins: [
    sass({
      injectGlobalPaths: [
        // Registers all CSS custom properties in every component's compiled output
        './node_modules/@volt/volt-foundations/dist/volt-foundations/volt-foundations.css',
        // Makes Sass variables and mixins available in every component .scss file
        // without needing a per-file @import
        './node_modules/@volt/volt-foundations/dist/volt-foundations/volt-foundations.scss',
      ]
    })
  ],
  outputTargets: [
    {
      type: 'dist',
      copy: [
        // Ship fonts and icons alongside the component library
        {
          src: '../node_modules/@volt/volt-foundations/dist/assets',
          dest: '../assets'
        }
      ]
    }
  ]
};

src/styles/style.scss (global entry):

@use '~@volt/volt-foundations/dist/volt-foundations/volt-foundations' as foundations;

Any component my-component.scss — no import needed, everything is globally injected:

:host {
  display: block;

  .my-component__container {
    padding: var(--spacing-04);
    border-radius: var(--radius-medium);
    background: var(--surface-medium);
    border: 1px solid var(--color-border-low);
  }

  .my-component__label {
    @include font-style(title, medium);
    color: var(--color-text-high);
  }

  .my-component__helper {
    @include font-style(body, small);
    color: var(--color-text-medium);
    margin-top: var(--spacing-02);
  }
}

Token Reference

Spacing

22-step scale in 0.125rem (2px) increments. All steps are available as CSS custom properties.

| Token | Value | |---|---| | --spacing-00 | 0rem | | --spacing-01 | 0.125rem (2px) | | --spacing-02 | 0.25rem (4px) | | --spacing-03 | 0.5rem (8px) | | --spacing-04 | 0.75rem (12px) | | --spacing-05 | 1rem (16px) | | --spacing-06 | 1.25rem (20px) | | --spacing-07 | 1.5rem (24px) | | --spacing-08 | 1.75rem (28px) | | --spacing-09 | 2rem (32px) | | --spacing-10 | 2.25rem (36px) | | --spacing-11 | 2.5rem (40px) | | --spacing-12 | 2.75rem (44px) | | --spacing-13 | 3rem (48px) | | --spacing-17 | 4rem (64px) | | --spacing-21 | 5rem (80px) |

Radius

| Token | Value | Use case | |---|---|---| | --radius-sharp | 0 | No rounding (data tables, code blocks) | | --radius-medium | 0.25rem (4px) | Default for inputs, cards, dropdowns | | --radius-large | 0.5rem (8px) | Dialogs, panels | | --radius-pill | 4rem | Chips, badges, pill buttons | | --radius-circle | 50% | Avatars, icon buttons |

Elevation

Z-index layers:

| Token | z-index | Typical use | |---|---|---| | --elevation-layer-00 | 0 | Default document flow | | --elevation-layer-01 | 1 | Slightly raised elements | | --elevation-layer-02 | 3 | Dropdowns, tooltips | | --elevation-layer-03 | 6 | Modals backdrop | | --elevation-layer-04 | 8 | Modals content | | --elevation-layer-06 | 16 | Notifications, toasts | | --elevation-layer-08 | 24 | Top navigation | | --elevation-layer-10 | 32 | Maximum priority overlays |

Box shadows:

| Token | Use case | |---|---| | --elevation-shadow-00 | No shadow | | --elevation-shadow-01 | Subtle card lift | | --elevation-shadow-02 | Dropdown panels, popovers | | --elevation-shadow-03 | Drawers, sidepanels | | --elevation-shadow-05 | Dialogs | | --elevation-shadow-08 | Full-screen overlays | | --elevation-shadow-17 | Highest emphasis modals |

Typography Styles

| Scale | Sizes | Font weight | Line height | |---|---|---|---| | display | large (56px), medium (44px), small (36px) | 300 (Light) | 64 / 52 / 44px | | headline | large (32px), medium (28px), small (24px) | 600 (Semibold) | 40 / 36 / 32px | | title | large (20px), medium (16px), small (14px), extra-small (12px), 2x-small (10px) | 600 (Semibold) | 28 / 24 / 20 / 16 / 12px | | body | large (16px), medium (14px), small (12px) | 300 (Light) | 24 / 20 / 16px |

Font weight override tokens:

| Token | Weight | |---|---| | font-light | 300 | | font-semibold | 600 | | font-bold | 800 |

Assets

Icons

202 SVG icons available at dist/assets/icons/. Covers general UI (arrows, actions, navigation) and industry-specific icons (rail, transport, engineering). Used by vds-icon component via the name prop.

<!-- When consuming via volt-basic-components -->
<vds-icon name="Bell"></vds-icon>
<vds-icon name="Arrow-right"></vds-icon>
<vds-icon name="Analytics"></vds-icon>

Fonts

The Roboto Flex variable font is bundled at dist/assets/fonts/Roboto_Flex/. It supports a full continuous weight axis (100–1000) and width axis (25%–151%), allowing fine-grained typographic control with a single font file.

JSON Tokens

dist/assets/json/ contains token exports compatible with Figma Token Studio:

Light.tokens.json — all light-theme token values
Dark.tokens.json — all dark-theme token values

Documentation

| Resource | Description | |---|---| | This README | Library overview, installation, and usage | | CHANGELOG.md | Version history and release notes | | dist/assets/json/ | Machine-readable token definitions for tooling integration | | volt-basic-components | Component library built on top of these foundations | | Zeroheight (internal) | Full design system documentation with visual token reference |

Semantic color token naming convention

Tokens follow the pattern --{category}-{role}-{state}:

--color-background-brand-default    → category: background, role: brand, state: default
--color-border-danger               → category: border, role: danger
--color-text-medium                 → category: text, role: medium (hierarchy)
--color-icon-disabled               → category: icon, role: disabled
--surface-medium                    → surface layer, medium elevation
--elevation-shadow-02               → shadow at elevation level 02
--spacing-05                        → spacing step 05

Local Development

Prerequisites

Node.js ≥ 18
Yarn (classic)
Wabtec VPN connection
.npmrc configured (see Installation)

Setup

# Clone the repository (internal GitLab)
git clone <repository-url>
cd volt-foundations

# Install dependencies
yarn install

Available scripts

# Start development server with watch mode
yarn start

# Build for production (generates dist/ and copies SCSS)
yarn build

# Build optimized production bundle
yarn build:prod

# Run unit tests
yarn test

# Run tests in watch mode
yarn test.watch

Build output

Running yarn build executes two steps:

stencil build --docs — compiles SCSS tokens into dist/volt-foundations/volt-foundations.css and JavaScript entry points
yarn copy:scss — concatenates all token SCSS source files into dist/volt-foundations/volt-foundations.scss, stripping internal @use imports so the file can be consumed stand-alone

The compiled dist/ folder is what gets published to the Wabtec GitLab npm registry.