# 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:

```bash
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:**

```html
<!-- 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:**

```html
<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`:

```html
<!-- CSS Variables with pinned version -->
<link rel="stylesheet" href="https://unpkg.com/@beam-ui/design-tokens@2.2.0/build/globals/variables.css">
<link rel="stylesheet" href="https://unpkg.com/@beam-ui/design-tokens@2.2.0/build/base/variables.css">
<link rel="stylesheet" href="https://unpkg.com/@beam-ui/design-tokens@2.2.0/build/semantic/variables.css">

<!-- JavaScript with pinned version -->
<script type="module">
  import { colorGrayBlack } from 'https://unpkg.com/@beam-ui/design-tokens@2.2.0/build/base/tokens.es6.js';
  // or
  import { colorGrayBlack } from 'https://cdn.jsdelivr.net/npm/@beam-ui/design-tokens@2.2.0/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

```css
/* 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):
```html
<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):
```html
<link rel="stylesheet" href="https://unpkg.com/@beam-ui/design-tokens@2.2.0/build/globals/variables.css">
<link rel="stylesheet" href="https://unpkg.com/@beam-ui/design-tokens@2.2.0/build/base/variables.css">
<link rel="stylesheet" href="https://unpkg.com/@beam-ui/design-tokens@2.2.0/build/semantic/variables.css">
```

#### Why All Three Files Are Required

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

```css
/* 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:

```css
@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:

```javascript
// 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

```javascript
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

```javascript
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:

```javascript
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`

**Shadows**
- `shadow-50` through `shadow-600` — Subtle ambient shadows for cards, popovers, and surface depth (uniform black at 6% alpha). `shadow-50` uses a sub-pixel (`0.5px`) blur for a "barely-there" hint and may render inconsistently on low-DPR displays — choose `shadow-100` if a guaranteed-visible step is required.

**Elevation**
- `elevation-100` through `elevation-300` — Stronger composite shadows for raised surfaces such as modals, drawers, and floating panels (graduated alpha for stacked depth)

#### Shadow & Elevation Usage Notes

Shadow and elevation tokens are **decorative**, not boundary-forming. Their alpha values (0.04–0.14) sit well below the WCAG 1.4.11 (Non-text Contrast) 3:1 threshold. If a surface's existence as an interactive element must be perceivable (form fields, focusable cards, popovers that overlap critical content), pair the shadow with an explicit `border` or background contrast — don't rely on the shadow alone.

`box-shadow` is **stripped in Windows High Contrast Mode** (`forced-colors: active`). Surfaces whose boundary depends on shadow lose all visual separation in that mode. Pair shadow usage with a transparent border that becomes a system color under forced-colors:

```css
.card {
  background-color: var(--color-surface-primary);
  box-shadow: var(--shadow-200);
  border: 0.1rem solid transparent;
}

@media (forced-colors: active) {
  .card {
    border-color: CanvasText;
  }
}

.modal {
  background-color: var(--color-surface-primary);
  box-shadow: var(--elevation-300);
  border: 0.1rem solid transparent;
}

@media (forced-colors: active) {
  .modal {
    border-color: CanvasText;
  }
}
```

### 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)

```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)

```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

```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](./LICENSE) file for details