Token Flow – Tori Bryan

Open on 21st.dev Read the post on X

Built a theme-aware token visualizer for my design system case studies, inspired by @ShadcnSpace "Integration Card" 😁 21st.dev/@iamtoribryan/…

Tori Bryan@iamtoribryan

bg-primaryPrimary actions, headings

text-successResolved, healthy, within threshold

border-borderHairlines and inputs

Features

One row per color, three chips wired left to right: the raw value, the primitive that names it, and the semantic utility that uses it.
A pulse travels along every wire, staggered per row, so the plate reads as a flow rather than a table.
Rows that carry a dark value swap to it when the theme changes, and the chips that change scramble for a second on the way. Nothing plays on first load, whichever theme it loads in.
Follows the document's dark class by default. Hosts that own the theme can pin it with theme.
Stacks vertically below sm, with the wires turning to run top to bottom.

Installation

pnpm dlx @21st-dev/cli add @iamtoribryan/token-flow

Usage

import { TokenFlow } from "@/components/ui/token-flow"
import type { TokenRow } from "@/components/ui/token-flow"

const rows: TokenRow[] = [
  {
    base: "oklch(0.141 0.005 285.823)",
    primitive: "zinc-950",
    semantic: "bg-primary",
    use: "Primary actions, headings",
    dark: { base: "oklch(0.985 0 0)", primitive: "zinc-50" },
  },
]
 
<TokenFlow rows={rows} showUse />

Each row's base also colors the swatch on its three chips, so a row that swaps in the dark theme changes color along with its labels.

API reference

TokenFlow

Prop	Type	Default	Description
`rows`	`TokenRow[]`		One entry per color.
`showUse`	`boolean`	`false`	Print each row's `use` under its semantic chip.
`theme`	`"light" \| "dark"`		Pin the theme instead of following the document's `dark` class.
`className`	`string`		Classes for the outer plate.

TokenRow

Field	Type	Description
`base`	`string`	The raw value, as written in CSS.
`primitive`	`string`	The primitive it is named as, such as a palette step.
`semantic`	`string`	The semantic utility that points at the primitive.
`use`	`string`	What the role is for. Shown when `showUse` is set.
`dark`	`{ base: string; primitive: string }`	The value and primitive the role resolves to in the dark theme.

The pulse only runs while the plate is on screen, and holds still for readers who ask for reduced motion. The scramble on a theme change does the same.