Design Tokens

Tessera UI uses a three-tier token architecture implemented as CSS custom properties. All tokens use the --ts- prefix and cross Shadow DOM boundaries via CSS inheritance, making theming work automatically in all components.

Never use raw values in component CSS — always reference tokens.

Architecture

Tier	Prefix	Purpose	Example
1. Reference	`--ts-ref-*`	Raw palette values	`--ts-ref-primary-600: #1a73e8`
2. Semantic	`--ts-*`	Role-based aliases	`--ts-color-interactive-primary: var(--ts-ref-primary-600)`
3. Component	`--ts-{component}-*`	Per-component overrides	`--ts-button-radius: var(--ts-shape-interactive)`

How the tiers connect

Tier 1 (Reference)          Tier 2 (Semantic)                 Tier 3 (Component)
--ts-ref-primary-600   ←──  --ts-color-interactive-primary  ←──  --ts-button-bg
#1a73e8                     var(--ts-ref-primary-600)             var(--ts-color-interactive-primary)

Reference tokens hold raw hex/rem values. They never change between themes.
Semantic tokens map reference tokens to roles (text, background, border, interactive). Dark mode remaps these.
Component tokens are defined on each component’s :host and default to semantic tokens. Consumers override these for customization.

DTCG JSON Format

The token values defined in src/theme/tokens.css are also available as W3C Design Tokens Community Group (DTCG) JSON files in the src/tokens/ directory (when generated). These JSON files follow the DTCG specification and can be consumed by tools like Style Dictionary, Figma Token Studio, and other design-to-code pipelines.

Customization Examples

Override a single component

ts-button {
  --ts-button-radius: 9999px;     /* Pill buttons */
  --ts-button-font-weight: 700;   /* Bolder text */
}

Override the entire system — primary

:root {
  --ts-color-interactive-primary: #e63946;
  --ts-color-interactive-primary-hover: #c1121f;
}

Override the entire system — secondary

:root {
  --ts-color-interactive-secondary: #0077b6;
  --ts-color-interactive-secondary-hover: #005f8a;
}

Component Token Reference

Each component exposes a curated set of tokens:

Component	Tokens
`ts-button`	`--ts-button-radius`, `--ts-button-font-weight`, `--ts-button-focus-ring`
`ts-input`	`--ts-input-bg`, `--ts-input-color`, `--ts-input-border-color`, `--ts-input-radius`, `--ts-input-focus-ring`
`ts-card`	`--ts-card-bg`, `--ts-card-radius`, `--ts-card-border-color`
`ts-modal`	`--ts-modal-bg`, `--ts-modal-overlay-bg`, `--ts-modal-radius`, `--ts-modal-shadow`
`ts-alert`	`--ts-alert-radius`, `--ts-alert-font-size`
`ts-toggle`	`--ts-toggle-track-bg`, `--ts-toggle-track-bg-checked`, `--ts-toggle-thumb-bg`, `--ts-toggle-focus-ring`
`ts-badge`	`--ts-badge-radius`, `--ts-badge-font-weight`
`ts-tooltip`	`--ts-tooltip-bg`, `--ts-tooltip-color`, `--ts-tooltip-radius`
`ts-icon`	`--ts-icon-size`, `--ts-icon-color`
`ts-container`	`--ts-container-padding`

Semantic Token Categories

For detailed documentation on each category, see the Design Language section:

Color — Text roles, backgrounds, borders, interactive states, feedback colors
Typography — Font families, size scale, weights, line heights
Layout — Spacing scale (comfortable default)
Elevation — Shadow scale, z-index levels
Shapes — Border radius scale
Motion — Transition durations, easing curves

Quick Reference

Colors — Semantic Roles

Token	Usage
`--ts-color-text-primary`	Primary body text
`--ts-color-text-secondary`	Supporting text
`--ts-color-text-tertiary`	Placeholder, hints
`--ts-color-bg-surface`	Page/component background
`--ts-color-bg-elevated`	Cards, modals
`--ts-color-bg-overlay`	Modal overlay
`--ts-color-border-default`	Standard borders
`--ts-color-border-subtle`	Dividers
`--ts-color-interactive-primary`	Primary interactive color
`--ts-color-interactive-secondary`	Secondary interactive color
`--ts-color-interactive-danger`	Danger interactive color
`--ts-color-focus-ring`	Focus ring color

Spacing

Token	Value
`--ts-spacing-1`	`0.375rem` (6px)
`--ts-spacing-2`	`0.625rem` (10px)
`--ts-spacing-3`	`1rem` (16px)
`--ts-spacing-4`	`1.25rem` (20px)
`--ts-spacing-5`	`1.5rem` (24px)
`--ts-spacing-6`	`2rem` (32px)
`--ts-spacing-8`	`2.5rem` (40px)
`--ts-spacing-10`	`3rem` (48px)
`--ts-spacing-12`	`4rem` (64px)
`--ts-spacing-16`	`5rem` (80px)

Radius

Token	Value
`--ts-radius-none`	`0`
`--ts-radius-sm`	`0.375rem` (6px)
`--ts-radius-md`	`0.75rem` (12px)
`--ts-radius-lg`	`1rem` (16px)
`--ts-radius-xl`	`1.75rem` (28px)
`--ts-radius-full`	`9999px`

Shadows

Token	Usage
`--ts-shadow-xs`	Subtle — inset elements
`--ts-shadow-sm`	Cards at rest, toggle thumbs
`--ts-shadow-md`	Hovered cards, elevated panels
`--ts-shadow-lg`	Dropdowns, hovered interactive cards
`--ts-shadow-xl`	Modals, full-screen overlays

Transitions

Token	Value
`--ts-transition-fast`	`160ms` — micro-interactions
`--ts-transition-normal`	`240ms` — state transitions
`--ts-transition-slow`	`360ms` — layout shifts

Density Modes

Tessera UI supports three density modes that remap spacing and font-size tokens. Apply via data-density on any ancestor:

<div data-density="compact">
  <!-- Tighter spacing for data-dense layouts -->
</div>

Mode	Attribute	Spacing Effect	Best For
Compact	`data-density="compact"`	Spacing reduced ~25-50%	Data tables, admin panels
Comfortable	(default)	Standard spacing	General-purpose UI
Spacious	`data-density="spacious"`	Spacing increased ~25-50%	Marketing, onboarding

Density affects --ts-spacing-*, --ts-font-size-*, --ts-touch-target-min, and --ts-grid-gutter. See Layout for the full comparison table.

Dark Mode

Activate dark mode by adding data-theme="dark" to any ancestor:

<html data-theme="dark">
  <!-- All components automatically adapt -->
</html>

Reference tokens (Tier 1) never change. Dark mode works by remapping semantic tokens (Tier 2) to different values. Component tokens (Tier 3) inherit the changes automatically through the var() chain.