@beam-ui/design-tokens

v2.1.0

Published

a month ago

A collection of design decisions and other artifacts for the Beam UI Design System

0High
0Medium
0Low

leo_alekseev

jordang-tatari

tatarian

design-tokens design-system tokens css-variables style-dictionary beam-ui

Beam UI Design Tokens

A centralized collection of design decisions and other artifacts for the Beam UI Design System.

Overview

Design tokens are the visual design atoms — specifically, they are named entities that store various design decisions. This package provides these tokens in multiple formats for consistent use across applications.

Installation

Option 1: npm/yarn

For applications with a build process:

npm install @beam-ui/design-tokens
# or
yarn add @beam-ui/design-tokens

Option 2: CDN via UNPKG or jsDelivr (Zero Configuration)

For server-side rendered HTML, static sites, or environments where build process is not available.

The package is available via CDN with all token formats accessible directly - no build process needed! (Works with both UNPKG and jsDelivr.)

Loading CSS Variables:

<!-- Import all token layers (recommended) -->
<link rel="stylesheet" href="https://unpkg.com/@beam-ui/design-tokens@latest/build/globals/variables.css">
<link rel="stylesheet" href="https://unpkg.com/@beam-ui/design-tokens@latest/build/base/variables.css">
<link rel="stylesheet" href="https://unpkg.com/@beam-ui/design-tokens@latest/build/semantic/variables.css">

<!-- or using jsDelivr -->
<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/@beam-ui/design-tokens@latest/build/globals/variables.css">
<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/@beam-ui/design-tokens@latest/build/base/variables.css">
<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/@beam-ui/design-tokens@latest/build/semantic/variables.css">

Loading JavaScript Tokens:

<script type="module">
  import { colorGrayBlack, spacingMedium } from 'https://unpkg.com/@beam-ui/design-tokens@latest/build/base/tokens.es6.js';
  // or
  import { buttonPrimaryBackground } from 'https://cdn.jsdelivr.net/npm/@beam-ui/design-tokens@latest/build/semantic/tokens.es6.js';
</script>

💡 Use Cases for CDN:

Server-side templating (PHP, Ruby, Python, etc.)
Static HTML sites without build tools
Quick prototypes and demos
CodePen/JSFiddle examples
Documentation and tutorials

⚡ Performance Benefits:

Zero configuration - no build process required
Direct access to all token formats (CSS, JS, JSON)
Selective loading - load only the token layers you need
Minified and optimized by the CDN

⚠️ For Production: Pin to a specific version instead of using @latest:

<!-- CSS Variables with pinned version -->
<link rel="stylesheet" href="https://unpkg.com/@beam-ui/[email protected]/build/globals/variables.css">
<link rel="stylesheet" href="https://unpkg.com/@beam-ui/[email protected]/build/base/variables.css">
<link rel="stylesheet" href="https://unpkg.com/@beam-ui/[email protected]/build/semantic/variables.css">

<!-- JavaScript with pinned version -->
<script type="module">
  import { colorGrayBlack } from 'https://unpkg.com/@beam-ui/[email protected]/build/base/tokens.es6.js';
  // or
  import { colorGrayBlack } from 'https://cdn.jsdelivr.net/npm/@beam-ui/[email protected]/build/base/tokens.es6.js';
</script>

Available Output Formats

All tokens are available in three formats:

CSS Variables (variables.css) - CSS custom properties
JavaScript ES6 (tokens.es6.js) - ES6 module exports
JSON (tokens.json) - Nested JSON structure

Token Layers

Tokens are organized in three layers:

build/globals/ - Global tokens (breakpoints, accessibility, etc.)
build/base/ - Default base tokens (colors, fonts, spacing, etc.)
build/semantic/ - Default semantic tokens (buttons, typography, etc.)

Brand-specific tokens can be found at build/{brand}/base/ and build/{brand}/semantic/ if custom brands exist.

Usage

Using CSS Variables

Important: Semantic Tokens Require Base and Global Tokens

Semantic CSS tokens reference base and global tokens using CSS custom properties (var()), which means you must import all token files in the correct order for semantic tokens to work correctly.

Recommended Import Order

/* Import in this order: */
@import '@beam-ui/design-tokens/build/globals/variables.css';
@import '@beam-ui/design-tokens/build/base/variables.css';
@import '@beam-ui/design-tokens/build/semantic/variables.css';

Or in your HTML (with npm):

<link rel="stylesheet" href="node_modules/@beam-ui/design-tokens/build/globals/variables.css">
<link rel="stylesheet" href="node_modules/@beam-ui/design-tokens/build/base/variables.css">
<link rel="stylesheet" href="node_modules/@beam-ui/design-tokens/build/semantic/variables.css">

Or in your HTML (with CDN):

<link rel="stylesheet" href="https://unpkg.com/@beam-ui/[email protected]/build/globals/variables.css">
<link rel="stylesheet" href="https://unpkg.com/@beam-ui/[email protected]/build/base/variables.css">
<link rel="stylesheet" href="https://unpkg.com/@beam-ui/[email protected]/build/semantic/variables.css">

Why All Three Files Are Required

Tokens use var() references to maintain relationships across all layers:

/* 1. Global tokens define shared values */
:root {
  --breakpoint-medium: 768px;
  --a11y-min-touch-target: 40px;
}

/* 2. Base tokens define the actual brand values */
:root {
  --color-gray-black: hsl(0, 0%, 0%);
  --color-gray-white: hsl(0, 0%, 100%);
  --color-transparent: hsla(0, 0%, 0%, 0);
  --font-size-medium: 1.6rem;
}

/* 3. Semantic tokens reference base and global tokens */
:root {
  --button-primary-background: var(--color-gray-black);
  --button-primary-text: var(--color-gray-white);
  --button-tertiary-border: var(--color-transparent);
  --button-primary-font-size: var(--font-size-medium);
  --button-size-sm-min-width: var(--a11y-min-touch-target);
}

Benefits of This Approach

Single source of truth - Update base token values and all semantic tokens automatically reflect the change
Smaller file sizes - References are more efficient than duplicated values
Runtime flexibility - Override base tokens to theme entire components
Maintainability - Clear relationships between foundation and application layers

Using Only Base Tokens

If you only need base tokens (colors, spacing, fonts) without semantic tokens, you can import just the base and global files:

@import '@beam-ui/design-tokens/build/globals/variables.css';
@import '@beam-ui/design-tokens/build/base/variables.css';

.custom-button {
  background-color: var(--color-gray-black);
  padding: var(--spacing-medium);
  font-size: var(--font-size-medium);
  min-height: var(--a11y-min-touch-target);
}

Note: Base tokens may reference global tokens (like accessibility values), so it's recommended to include globals even when not using semantic tokens.

Using JavaScript/TypeScript Tokens

JavaScript and JSON formats output resolved values, so semantic tokens can be used independently:

// Semantic tokens contain resolved values
import { buttonPrimaryBackground, buttonPrimaryText } from '@beam-ui/design-tokens/build/semantic/tokens.es6.js';

const button = {
  backgroundColor: buttonPrimaryBackground, // "hsl(0, 0%, 0%)"
  color: buttonPrimaryText // "hsl(0, 0%, 100%)"
};

Importing Base Tokens

import { colorGrayBlack, fontSizeMedium, spacingLarge } from '@beam-ui/design-tokens/build/base/tokens.es6.js';

const styles = {
  color: colorGrayBlack, // "hsl(0, 0%, 0%)"
  fontSize: fontSizeMedium, // "1.6rem"
  padding: spacingLarge // "2.4rem"
};

Importing Global Tokens

import { breakpointMedium, a11yMinTouchTarget } from '@beam-ui/design-tokens/build/globals/tokens.es6.js';

const config = {
  breakpoint: breakpointMedium, // "768px"
  minTouchSize: a11yMinTouchTarget // "40px"
};

Using JSON Tokens

JSON format provides a nested structure:

import tokens from '@beam-ui/design-tokens/build/semantic/tokens.json';

console.log(tokens.button.primary.background); // "hsl(0, 0%, 0%)"
console.log(tokens.color.background.primary); // "hsl(0, 0%, 100%)"

npm vs CDN: When to Use Each

| Method | Best For | Setup | Performance | |--------|----------|-------|-------------| | npm + Bundler | Apps with build tools (React, Vue, etc.) | Bundler handles imports | Smaller final bundle (tree-shaking) | | CDN | Server-side templates, static sites | Zero config - direct file loading | No build process needed |

Token Reference

Global Tokens

Breakpoints

breakpoint-small, breakpoint-medium, breakpoint-large, breakpoint-x-large

Accessibility

a11y-min-touch-target - Minimum touch target size for interactive elements

Base Tokens

Colors

Brand colors: color-tatari-red, color-tatari-blue, etc.
Gray scale: color-gray-black, color-gray-800 through color-gray-50, color-gray-white
Color palettes: color-red-*, color-blue-*, color-green-*, etc. (100-700 scales)
Special: color-transparent, color-overlay-dark, color-overlay-light

Typography

Font families: font-family-inter, font-family-favorit, font-family-body, font-family-display
Font weights: font-weight-normal (400), font-weight-medium (500)
Font sizes: font-size-x-small through font-size-xxxx-large
Line heights: font-line-height-tight through font-line-height-loose
Letter spacing: font-letter-spacing-x-small through font-letter-spacing-x-large

Spacing

spacing-xx-small through spacing-xxx-large

Borders

Border radius: border-radius-xx-small through border-radius-xxx-large, border-radius-circle
Border width: border-width-thin, border-width-medium

Semantic Tokens

Button Tokens

Variants: button-primary-*, button-secondary-*, button-tertiary-*
Danger states: button-danger-primary-*, button-danger-secondary-*
States: -background, -background-hover, -background-active, -background-disabled
Text: -text, -text-hover, -text-active, -text-disabled
Border: -border, -border-hover, -border-active, -border-disabled
Sizes: button-size-sm-*, button-size-md-*, button-size-lg-*

Input Tokens

Dimensions: input-height, input-padding-inline, input-border-radius, input-border-width, input-border-width-focus
Typography: input-font-size, input-line-height
Transition: input-transition
Background: input-background, -hover, -error, -warning, -success, -focus, -readonly, -disabled
Border (color): input-border, -hover, -error, -warning, -success, -focus, -readonly, -disabled
Text: input-text, input-text-placeholder, input-text-disabled
Icon: input-icon-size, input-icon-color, input-icon-color-disabled, input-icon-gap
Label: input-label-font-size, input-label-color, input-label-gap
Message: input-message-font-size, input-message-gap, input-message-color-default, -error, -warning, -success

Color Tokens

Background: color-background-primary, color-background-secondary, etc.
Surface: color-surface-primary, color-surface-hover, etc.
Border: color-border-primary, color-border-focus, color-border-readonly, etc.
Text: color-text-primary, color-text-link, etc.
Icon: color-icon-primary, color-icon-interactive, etc.
Interactive states: color-interactive-primary-default, etc.
Status colors: color-status-success-base, color-status-error-base, etc.
Brand colors: color-brand-primary-base, color-brand-secondary-base, etc.

Typography Tokens

Display: typography-display-100-* through typography-display-500-*
Headings: typography-heading-100-* through typography-heading-500-*
Body text: typography-body-large-*, typography-body-base-*, typography-body-small-* (each with default and medium variants)
Label: typography-label-base-*
Caption: typography-caption-*
Overline: typography-overline-*
Properties: -font-family, -font-weight, -font-size, -line-height, -letter-spacing, -color, -inverse

Focus Ring Tokens

focus-ring-width - Width of the focus ring outline
focus-ring-offset - Distance between element and focus ring
focus-ring-color - Color of the focus ring
focus-ring-transition - Animation for focus ring appearance

Examples

Using Focus Ring Tokens for Accessibility (CSS)

/* Import all required token files */
@import '@beam-ui/design-tokens/build/globals/variables.css';
@import '@beam-ui/design-tokens/build/base/variables.css';
@import '@beam-ui/design-tokens/build/semantic/variables.css';

.interactive-element {
  /* Remove default browser focus outline */
  outline: none;
}

.interactive-element:focus-visible {
  /* Apply design system focus ring */
  outline: var(--focus-ring-width) solid var(--focus-ring-color);
  outline-offset: var(--focus-ring-offset);

  @media (prefers-reduced-motion: no-preference) {
    transition: var(--focus-ring-transition);
  }
}

Complete Button Component (CSS)

/* Import all required token files */
@import '@beam-ui/design-tokens/build/globals/variables.css';
@import '@beam-ui/design-tokens/build/base/variables.css';
@import '@beam-ui/design-tokens/build/semantic/variables.css';

.button-primary {
  background-color: var(--button-primary-background);
  color: var(--button-primary-text);
  border: var(--button-primary-border-width) solid var(--button-primary-border);
  border-radius: var(--button-primary-border-radius);
  font-size: var(--button-primary-font-size);
  line-height: var(--button-primary-line-height);
  padding-inline: var(--button-size-md-padding-inline);
  padding-block: var(--button-size-md-padding-block);
  min-width: var(--button-size-md-min-width);
}

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

React Component with TypeScript

import {
  buttonPrimaryBackground,
  buttonPrimaryText,
  buttonPrimaryBorderRadius,
  buttonSizeMdPaddingInline,
  buttonSizeMdPaddingBlock
} from '@beam-ui/design-tokens/build/semantic/tokens.es6.js';

interface ButtonProps {
  children: React.ReactNode;
}

export const Button: React.FC<ButtonProps> = ({ children }) => {
  return (
    <button
      style={{
        backgroundColor: buttonPrimaryBackground,
        color: buttonPrimaryText,
        borderRadius: buttonPrimaryBorderRadius,
        paddingInline: buttonSizeMdPaddingInline,
        paddingBlock: buttonSizeMdPaddingBlock
      }}
    >
      {children}
    </button>
  );
};

License

MIT License - see LICENSE file for details