Use design tokens

Jangle UI tokens provide a stable vocabulary for building product interfaces. They are available as CSS custom properties, typed JavaScript references, and machine-readable JSON.

What you can use

Consumers have one supported token catalog. Every token exported by @jangle-ui/tokens is public and available to use. Browse it by the job you need to do: Color, Typography, Spacing, Size, Radius, Border and Focus Width, Opacity, Elevation, or Motion.

Most names describe a reusable purpose, such as color.content.high, radius.medium, or motion.transition.enter. Space and Size are public coordinate families:

• use space.* for whitespace;
• use size.* for occupied dimensions; and
• prefer a purpose-named token whenever one already describes the job.

Jangle's base/reference values and private theme aliases are not exported. The References column in Storybook shows how a public token is authored for traceability; it does not make that private name part of the installable API. Internal tooling may classify public tokens by how they are constructed, but consumers do not need to learn another token tier before using them.

Released components select from these tokens through their documented recipes. Component-specific customization tokens will be added only when a released component needs a stable customization point.

Install and load the default theme

pnpm add @jangle-ui/tokens

Import the generated stylesheet once at the application boundary:

import '@jangle-ui/tokens/tokens.css';

Then use the supported CSS properties:

.product-panel {
  padding: var(--jangle-space-200);
  border: var(--jangle-border-width-default) solid var(--jangle-color-border-subtle);
  border-radius: var(--jangle-radius-medium);
  background: var(--jangle-color-surface-neutral-primary);
  color: var(--jangle-color-content-high);
}

Typed consumers can use token() instead of writing a custom property name by hand:

import { token } from '@jangle-ui/tokens';

const panelColor = token('color.surface.neutral.primary');

Spacing and sizing

space.* and size.* deliberately share one coordinate system but have different jobs:

• use space.* for gap, padding, margin, inset, and layout separation;
• use size.* for icon boxes, avatars, control frames, targets, and other occupied width or height;
• do not use space.* to size an object or size.* to create whitespace.

These coordinates do not promise that space.200 always means “card padding” or size.500 always means “button height.” Released component recipes select from these families for their own named sizes, and future components will do the same. Shared layout relationships will be added only after repeated product evidence proves them.

Typography

Use complete typography roles. The package helper combines a role and its Normal or Strong expression into a framework-neutral style object and supplies a resilient web fallback stack:

import { typographyStyle } from '@jangle-ui/tokens';

const heading = typographyStyle('heading.medium', 'strong');

Inter is the preferred default family, but the token package does not force a font download. Applications are responsible for loading Inter or mapping the typography family to a compatible product font.

Configure a theme

Jangle ships with an opinionated default theme. Applications that need another supported Brand, Neutral, Surface, Shape, or Appearance combination can generate deterministic CSS with the package compiler:

import { writeFile } from 'node:fs/promises';
import { createThemeCss } from '@jangle-ui/tokens/compiler';

const css = await createThemeCss({
  brand: 'indigo',
  neutral: 'achromatic',
  surface: 'layered',
  shape: 'balanced',
  appearance: 'system',
});

await writeFile('.jangle/theme.css', css);

Use data-jangle-appearance="light" or data-jangle-appearance="dark" on the document root or a themed subtree when the application owns the runtime appearance choice.

Current boundary

The token package supports custom interface work, but the absence of a Jangle component or layout recipe is meaningful. Button and Icon own their documented named-size recipes. Responsive page gutters, a shared density model, general cross-component size meanings, and component-specific customization tokens are not yet public contracts. Outside a released recipe, use the public coordinate families deliberately and keep application-specific decisions in application-owned tokens rather than inventing new Jangle meanings.