TokenValue
Preview appears after the next Storybook update.
<TokenValue />When to use
Use it for
- Showing a token in a table, a review or a change list: the name, the value as written, and the resolved value when it is an alias.
- Before and after a change: the previous value with previous (struck through), then the new value.
- Inside a ChoiceCard description, so the reader sees the value each choice keeps.
- size sm in dense tables and inside sentences; md everywhere else.
- Plain-script pages that build rows as HTML strings use tokenValueHtml() from @bridge-ds/react/dom: the same markup and swatch rules, without React.
Not for
- A command or a snippet the reader copies: use CodeBlock.
- A status such as Changed or Removed: use Badge next to the value.
- Editing a value: use an Input, and show the TokenValue as the current value next to it.
Do and don't
Every example is rendered with the real component, so it always matches what ships.
Show the alias and what it resolves to
The alias says where the value comes from, the resolved value says what the reader will see. Together they answer both questions in one glance.
Pair a previous value with the new one
The struck-through value reads as removed, the plain one as the new value. Keep them on one line, old first.
Repeating the token name in its own row
When the row or column already names the token, drop name and show the value only. The same name twice is noise.
A previous value on its own
A struck-through value without the new one tells the reader what is gone but not what replaces it.
Accessibility
- Static text, no interaction: screen readers read the name, the value and the resolved value in order.
- The swatch is decorative (aria-hidden): the value text always says the color, so the swatch is never the only signal.
- A previous value is wrapped in del, so assistive technology that reports deletions reads it as removed, and it is struck through for sighted readers.
- The swatch carries a hairline border, so white and near-background colors still read as a square in both themes.
- Long names and aliases break anywhere instead of overflowing a narrow cell.
- Plain scripts render the same markup with tokenValueHtml() from @bridge-ds/react/dom.
Content guidelines
- Write the name as the token path, dot separated: color.action.primary.bg, not --color-action-primary-bg.
- Write the value as the token file has it: an alias in braces ({color.harbor.700}) or a literal (#0B4A8B, 16px).
- Hex values in upper case, so before and after values line up character by character.
From the code Generated from the component, not editable here.
Anatomy and tokens
Read from packages/react/src/components/TokenValue/TokenValue.module.css at build time. Every value is a token: open one to see its alias chain in both themes.
- Container
.root - Size md (ui text)
.md - Size sm (caption text)
.sm - Color swatch, only for color values
.swatch - Size sm (caption text)
.sm .swatch - Token name
.name + .text - Value group (del when previous)
.text - Resolved value of an alias
.resolved - Previous value, struck through
.previous
Motion and interaction
TokenValue does not animate: its states change at once.
From the code Generated from the component, not editable here.
Props
Parsed from the TypeScript types in packages/react/src/components/TokenValue/TokenValue.tsx, so this table cannot drift from the code. It also accepts every native <span> attribute except children.
| Prop | Type | Default | Description |
|---|---|---|---|
valuerequired | string | none | The value as written: a literal (`#0B4A8B`, `16px`) or an alias (`{color.harbor.700}`). |
name | string | none | The token name, `color.action.primary.bg`. Omit it where the row already names the token. |
resolved | string | none | The resolved value when `value` is an alias, shown muted after it: `#0B4A8B`. |
swatch | string | false | none | The color of the swatch. By default the swatch shows when `resolved` or `value` is a color literal (hex, rgb, hsl, oklch, oklab, lab, lch, color()). Pass a color to force it, `false` to hide it. |
previous | boolean | false | The value before a change: muted and struck through, read as a deletion. Pair it with the new value. |
size | 'sm' | 'md' | 'md' | Default `md` (ui text). `sm` uses caption text, for dense tables. |
Comes with breakAfterDots, each accepting native <div> attributes.
Playground
Change the props and see the real TokenValue update. Controls are generated from the TypeScript props; nothing here changes the system.
<TokenValue
value="{color.harbor.700}"
name="color.action.primary.bg"
resolved="#0B4A8B"
/>Workbench
For contributors: every state with the accessibility panel, in the component workbench (Storybook). The stories double as visual test fixtures; the guidance on this page is the user documentation (open TokenValue in Storybook).
Embed Storybook stories here (9)
Loads from https://bridge-storybook.floriangouloubi.com (set STORYBOOK_URL at build time). If Storybook is not running, the frames stay empty.
Default
Literal
ValueOnly
NotAColor
Small
NoSwatch
BeforeAfter
NarrowCell
AllStates
From the code Generated from the component, not editable here.
Changelog
No release note mentions TokenValue yet.