Design tokens

Shadow tokens provide consistent elevation across components. Each shadow is tuned for a specific UI context. Click any swatch to copy its Tailwind class.

The type system uses Instrument Sans with custom OpenType feature settings. All sizes bundle font-size, line-height, and letter-spacing into a single Tailwind class.

<h1 className="text-display font-medium">Page title</h1>
<p className="text-body-long text-secondary">Description text with comfortable reading line height.</p>
<span className="text-body-sm text-tertiary">Caption</span>

Two weights are defined as custom values to align with Instrument Sans optical weight:

The default font-feature-settings are applied globally: 'ss01' (rounded dots), 'ss03' (alternate y), 'ss12' (alternate currency), 'ss09' (alternate Q), 'kern'.

Link tokens and utilities handle external and internal link styling with built-in hover states.

Styles an element as an external link using color-link (blue-500). On hover, the color shifts to color-link-hover and an underline appears.

<a href="https://wander.com" className="text-link">
  Visit Wander
</a>

Styles an element as an internal link using the primary text color. On hover, an underline appears. Use this for in-app navigation where blue link styling is not appropriate.

<a href="/docs/components/button" className="text-link-internal">
  Button component
</a>

18 easing curves across three families. Use with the ease-* utility class for transitions and animations.

<div className="transition-transform duration-300 ease-out-cubic hover:scale-105">
  Smooth scale on hover
</div>

<div className="transition-opacity duration-500 ease-in-out-quart">
  Fade with quartic easing
</div>

A t-shirt scale for layout rhythm — section padding, vertical stacks, content gaps. Namespaced under layout- so it doesn't shadow Tailwind's container scale (max-w-2xl etc. continue to work as expected). Use with any spacing utility: p-layout-md, gap-layout-2xl, my-layout-7xl.

For finer-grained spacing, Tailwind's numeric scale (p-1, p-2, …) remains available.

Responsive breakpoints for use with Tailwind responsive prefixes (sm:, md:, etc.).

The md breakpoint (744px) remains the viewport threshold used by useIsDesktop and useIsMobile in the shared utils. Core components that opt into container-driven desktop/mobile presentation use the lg breakpoint (65rem / 1040px) so embedded previews switch from their available width.

Required for the WanderOS website, layering a product-specific set of spacing and radius tokens on top of the core stylesheet. Distributed as a separate import so consumers outside of WanderOS websites are unaffected.

import '@wandercom/design-system-tokens/tailwind.css';
import '@wandercom/design-system-tokens/websites.css';

Intent-named spacing for section padding, content gaps, and card padding. Each aliases the layout scale, so changes to a base step propagate everywhere. Available as p-*, m-*, gap-*, etc.

Primitive stops for use with rounded-* utilities.

Semantic aliases that map to the primitive scale per UI context. Prefer these over the primitives when the use is intent-driven.

Tokens are sourced from packages/tokens/src/websites.tokens.json and compiled into dist/websites.css during build:design-system.

Beyond standard Tailwind, the token stylesheet provides compound utilities that wire up interactive states automatically.

Applies background, text color, hover, and focus-visible states for a button variant in one class.

<button className="bg-button-primary rounded-lg px-4 py-2">Primary</button>
<button className="bg-button-checkout rounded-lg px-4 py-2">Book now</button>

Available variants: primary, secondary, outline, ghost, destructive, checkout, disabled, slider-thumb.

Semantic border colors for badge variants. Each token encodes the correct color and alpha for light and dark modes, removing the need for manual opacity modifiers.

<Badge variant="neutral">Default</Badge>
<Badge variant="success">Active</Badge>
<Badge variant="error">Failed</Badge>
<Badge variant="warning">Pending</Badge>
<Badge variant="info">Verified</Badge>

Focus ring tokens using a double box-shadow (inner surface ring + outer accent ring).

<button className="focus-visible:shadow-focus rounded-lg">Focusable</button>
<button className="focus-visible:shadow-focus-destructive rounded-lg">Destructive focus</button>

Expands the tap target to a minimum 44x44px hit area using a pseudo-element overlay, without changing visual size.

<button className="touch-hitbox">
  <SmallIcon />
</button>

Control scrollbar appearance using native CSS scrollbar properties.

<div className="scrollbar-thin overflow-y-auto">Thin scrollbar</div>
<div className="scrollbar-none overflow-y-auto">Hidden scrollbar</div>

pnpm add @wandercom/design-system-tokens

See the installation guide for authentication setup.

Import tokens in your application:

import '@wandercom/design-system-tokens/tailwind.css';

For WanderOS product projects, also import the WanderOS tokens to pick up its spacing and radius tokens:

import '@wandercom/design-system-tokens/websites.css';

Tokens are available as Tailwind classes:

<h1 className="text-display font-medium">Welcome to Wander</h1>

<div className="bg-surface-primary text-primary">
  Content with design tokens
</div>

<a href="/properties" className="text-link-internal">
  Browse properties
</a>

<button className="bg-button-checkout focus-visible:shadow-focus rounded-lg px-4 py-2">
  Book now
</button>

<div className="shadow-dropdown rounded-xl border-overlay-primary bg-surface-dropdown p-2">
  Dropdown menu content
</div>

<div className="transition-transform duration-300 ease-out-cubic hover:scale-105">
  Animated element
</div>

A self-contained color system built on OKLCh perceptual color space with WCAG contrast compliance. Given three seed colors, the engine generates full scales, resolves ~55 semantic tokens per background context, and exports to CSS or JSON.

pnpm add @wandercom/design-system-tokens

import {
  generateScales,
  resolveRoleTokens,
  generateExportCSS,
  type SeedColors,
} from '@wandercom/design-system-tokens/color-engine';

The entire palette derives from three hex seed colors:

import type { SeedColors } from '@wandercom/design-system-tokens/color-engine';

const seeds: SeedColors = {
  brand: '#1a1a2e',           // dominant brand hue (placed at scale stop 500)
  accentPrimary: '#e94560',   // action/CTA color
  accentSecondary: '#0f3460', // supporting variety color
};

generateScales produces a 9-stop scale (50, 100, 200, 300, 500, 700, 800, 900, 950) for each seed, preserving hue and scaling chroma proportionally.

import { generateScales } from '@wandercom/design-system-tokens/color-engine';

const scales = generateScales(seeds);

scales.brand[500];          // seed color
scales.accentPrimary[50];   // lightest accent stop

For a single color, use generateScale:

import { generateScale } from '@wandercom/design-system-tokens/color-engine';

const brandScale = generateScale('#1a1a2e');

11 named palettes are available as starting points:

import { PRESETS } from '@wandercom/design-system-tokens/color-engine';

const seeds = PRESETS['Ocean Calm'];
const scales = generateScales(seeds);

Available presets: Classic Persian, Pink Navy, Mauve Garden, Wander, Electric Clash, Ocean Calm, Sunset Warmth, Forest Dew, Coral Reef, Signal Pop, Heritage.

Given a background context, the engine resolves a full set of semantic tokens (surfaces, text, buttons, borders, semantic colors) with WCAG-compliant contrast ratios.

import { resolveRoleTokens, type BackgroundRole } from '@wandercom/design-system-tokens/color-engine';

const { background, foreground, tokens } = resolveRoleTokens('theme-base', scales);

tokens.text.primary;           // WCAG AA against background
tokens.surface.secondary;      // slightly offset surface
tokens.button.background;      // CTA button fill
tokens.border.primary;         // default border
tokens.semantic.error;         // error color for the mode

BackgroundRole is a union of all supported contexts:

For page layout sections (optionally with background images) and navigation bars:

import {
  resolveSectionTokens,
  resolveNavTokens,
  type SectionConfig,
} from '@wandercom/design-system-tokens/color-engine';

const hero: SectionConfig = { role: 'theme-dark', img: true };

const section = resolveSectionTokens(hero, scales);
section.background;            // hex background
section.effectiveBackground;   // after image overlay blending
section.tokens.text.primary;   // collapsed to single level when img is present

const nav = resolveNavTokens(hero, scales);
nav.background;                // "transparent" for hero overlap
nav.backgroundBlur;            // frosted-glass tint
nav.ctaBackground;             // CTA button fill
nav.isTransparent;             // true when nav overlays hero

Low-level color functions for conversion, contrast checking, and manipulation:

import {
  hexToOklch,
  oklchToHex,
  contrastRatio,
  ensureContrast,
  mixColors,
  alphaBlend,
  getLuminance,
  WCAG_AA,
} from '@wandercom/design-system-tokens/color-engine';

hexToOklch('#e94560');                          // { L, C, h } in OKLCh
oklchToHex(0.7, 0.15, 25);                     // hex with gamut clamping
contrastRatio('#ffffff', '#1a1a2e');             // WCAG 2.x ratio [1, 21]
ensureContrast('#888888', '#ffffff', WCAG_AA);  // adjusted hex meeting 4.5:1
mixColors('#ff0000', '#0000ff', 50);            // linear sRGB interpolation
alphaBlend('#000000', '#ffffff', 0.5);          // composite at alpha

Generate CSS custom properties or structured JSON for external consumers:

import { generateExportCSS, generateExportJSON } from '@wandercom/design-system-tokens/color-engine';

// CSS with [data-theme="..."] attribute selectors per background role
const css = generateExportCSS(scales);

// Structured JSON with seeds, primitives (scale stops), and modes (semantic tokens)
const json = generateExportJSON(seeds, scales);

The CSS output uses data-theme attribute selectors, mapping semantic tokens to CSS custom properties (e.g., --color-primary, --color-surface-secondary).

WCAG contrast thresholds are exported for use in custom validation:

import {
  WCAG_AA,              // 4.5 — normal-size text
  WCAG_AA_LARGE,        // 3   — large text / UI elements
  WCAG_AAA,             // 7   — enhanced contrast
  WCAG_TEXT_SECONDARY,  // 5.5 — secondary text
  WCAG_TEXT_MUTED,      // 3.5 — muted/placeholder text
} from '@wandercom/design-system-tokens/color-engine';

• Installation guide - Set up tokens in your project
• Web components - React components using tokens