# Tokens (tokens)

> Cream, ink, and vermilion palette, Geist font stacks and tab-name metrics, radii, the shared ink outline weight, surface shadows and borders, stage safe areas, and a CSS variables string.

- Entry: component
- Category: Foundations
- Preview capabilities: none (still preview)
- Runtime: React
- Needs Remotion: no
- QA page: https://jbm-ui.bns.studio/c/tokens
- JSON: https://jbm-ui.bns.studio/catalog/tokens.json
- Registry item: https://jbm-ui.bns.studio/r/tokens.json (source code in files[].content)

## Install

```sh
npx shadcn@latest add @jbm/tokens
```

## Required setup

1. Add the `@jbm` registry to components.json (keep any entries already there):

   ```json
   {
     "registries": {
       "@jbm": "https://jbm-ui.bns.studio/r/{name}.json"
     }
   }
   ```

2. Map `@/*` to `./src/*` in tsconfig.json `compilerOptions.paths`, so `@/jbm/…` imports resolve to src/jbm/.

## Files

Each file's source code is in the registry item JSON (https://jbm-ui.bns.studio/r/tokens.json, files[].content).

| Source path | Installs to | Import |
| --- | --- | --- |
| `registry/jbm/lib/tokens.ts` | `src/jbm/lib/tokens.ts` | `@/jbm/lib/tokens` |

## API

### `color` (constant)

Two-colour palette as hex strings: bg (cream canvas), card (raised surface), ink (text), dim (muted text), line (rules and borders), accent (vermilion, the one accent), accent2 (annotations), soft (emphasis on dark), dimOnDark (cream at 62% for muted text on ink), codeBg, and codeGreen.

### `font` (constant)

Font stacks for sans and mono: the host's --font-sans / --font-mono CSS variable when set (for example by next/font), else Geist and Geist Mono, then system fallbacks.

### `sansWidth` (function)

Estimated advance width of a line set in Geist 800 (tab names) or Geist 400 italic (sublabels), from a built-in per-glyph table measured in the browser, so layouts that size tabs match before fonts load and in Remotion. Accented letters measure as their base letter; other non-ASCII glyphs as an average. Kerning is ignored, so it errs slightly wide.

| Parameter | Type | Default | Description |
| --- | --- | --- | --- |
| `text` | `string` | required | The line. |
| `size` | `number` | required | Font size in the units you want back. |
| `italic` | `boolean` | `false` | true for Geist 400 italic; default false (Geist 800). |

Returns: Width in the same units as size.

### `radius` (constant)

Corner radii in pixels: chip 14, code 12, card 28, pill 10.

### `stroke` (constant)

The shared ink outline, `stroke.outline`, in stage px: 3 (3px on a 1080 stage). Every desk, paper, and thread object (Hand, Folder, Cajon, FileCabinet, Escritorio, DeskTop, DeskProp, Bandeja, ToolCaddy, Document, Paper, Tear, Register, Slip, Hilo, VideoPrint, PunchedTag) draws its outline at this weight, so a composed scene reads as one line weight.

### `outlineIn` (function)

The shared outline converted to a local unit system, for art whose viewBox or transform scales against the stage (Hand's 30-unit viewBox at 180 px, a scaled DeskProp group).

| Parameter | Type | Default | Description |
| --- | --- | --- | --- |
| `unitsPerPx` | `number` | `1` | Local units per stage px; default 1. Non-finite or non-positive values count as 1. |

Returns: stroke.outline × unitsPerPx, in local units.

### `shadowLayers` (constant)

The surface recipes split into inset (edge light), contact, and ambient box-shadow layers for `card` and `cardDark`. Use it to compose or inspect individual layers; see docs/surface-depth.md.

### `shadow` (constant)

Complete box-shadow strings `card` and `cardDark`, joined from shadowLayers (inset, contact, then ambient). Used by Card, StatCard, and CodeCard.

### `surfaceBorder` (constant)

1px ink-tinted border shorthands `card` (12% ink) and `cardDark` (65% ink) that pair with the matching shadow.

### `stage` (constant)

Stage size and safe area per orientation, in stage pixels: landscape 1920×1080 with 120 side padding, top 90, content bottom 920; vertical 1080×1920 with 72 side padding, top 100, content bottom 1440. Captions live below `bottom`.

### `Orientation` (type)

The keys of `stage`: "landscape" or "vertical".

### `cssVars` (constant)

A `:root{…}` CSS string defining --jbm-bg, --jbm-card, --jbm-ink, --jbm-dim, --jbm-line, --jbm-accent, --jbm-accent2, and --jbm-soft for Tailwind or shadcn consumers. It omits dimOnDark, codeBg, and codeGreen.

## Stage

n/a: Token values only; nothing renders. The gallery shows the color entries as swatches.

## Examples

### Inline styles from tokens

```tsx
import { color, font } from "@/jbm/lib/tokens"

<div style={{ color: color.ink, background: color.bg, fontFamily: font.sans }} />
```

### Keep content inside the safe area

```tsx
import { stage, type Orientation } from "@/jbm/lib/tokens"

const o: Orientation = "vertical"
const { w, pad, top, bottom } = stage[o]
const contentWidth = w - pad * 2 // 936 stage px in vertical
const contentHeight = bottom - top // 1340 stage px in vertical
```

### CSS variables for Tailwind

```tsx
import { cssVars } from "@/jbm/lib/tokens"

<style>{cssVars}</style>
// or paste the string into globals.css and use var(--jbm-accent)
```

## QA

- Check each swatch against the cream, ink, and vermilion palette; the accent stays the only saturated color.
- After changing shadowLayers, compare light and dark Card, StatCard, and CodeCard; shadow.card must still equal the joined card layers for existing consumers.
- When adding a color, decide whether cssVars should expose it; today it exports eight of the eleven colors.
- Verify text using dim or dimOnDark keeps readable contrast on its background.

## Docs

- [Surface depth guide](https://jbm-ui.bns.studio/docs/surface-depth.md)

## Related

Installed by: 67 items (see https://jbm-ui.bns.studio/catalog.json).

## More

- [llms.txt](https://jbm-ui.bns.studio/llms.txt): index of every item
- [catalog.json](https://jbm-ui.bns.studio/catalog.json): every item as JSON
- [Agent contract](https://jbm-ui.bns.studio/docs/agent-contract.md): what each field means
