<token-specimen>
Unified design token scale display. Renders shadows, radii, borders, colors, or sizes based on the type attribute.
Overview
A single component for displaying any design token scale. The type attribute controls the visual rendering while sharing the same core API across all token categories.
Part of the Design System Pack.
Types
Shadow
Cards with applied box-shadow at each elevation step.
<token-specimen type="shadow" label="Elevation Scale"></token-specimen>Radius
Squares with applied border-radius at each scale step.
<token-specimen type="radius" label="Corner Radius"></token-specimen>Border
Lines at each border width.
<token-specimen type="border" label="Border Widths"></token-specimen>Color
Swatches for color tokens.
<token-specimen type="color" tokens="primary,secondary,accent,success,warning,error" label="Brand Colors"></token-specimen>Size
Horizontal bars showing spacing values (same visualization as <spacing-specimen>).
<token-specimen type="size" tokens="xs,s,m,l,xl,2xl" label="Spacing Scale"></token-specimen>Icon
Icons from the active icon set, rendered as a labelled grid. Useful for documenting which icons a design system uses. The size attribute controls icon size; the optional icon-set attribute switches sets (lucide, phosphor, tabler, etc.).
<token-specimen type="icon" tokens="home,search,settings,user,bell,heart,star,check,x,chevron-right,menu,trash" size="md" label="Core Icons"></token-specimen>Switch icon sets to compare styles:
<token-specimen type="icon" tokens="home,search,user,heart" size="lg" icon-set="phosphor" label="Phosphor Set"></token-specimen>Editable Mode
Add the editable attribute to replace the computed-value cell in every row with an input. Editing a value writes the token as a CSS custom property on target (default :root), so the rest of the page updates live. Ignored for type="icon".
<token-specimen type="radius" editable tokens="xs,s,m,l,xl" label="Editable Radii"></token-specimen>For type="color", values in hex format get a native color picker; oklch or named colors fall back to a text input.
<token-specimen type="color" editable tokens="primary,secondary,accent" label="Editable Colors"></token-specimen>Listen for edits via token-specimen:change:
document.querySelector('token-specimen') .addEventListener('token-specimen:change', (e) => { console.log(e.detail); // { name: 'm', value: '0.75rem', token: '--radius-m', target: ':root' } });Custom Tokens
Override tokens and prefix to display any set of CSS custom properties.
<token-specimen type="shadow" tokens="card,dropdown,modal" prefix="--my-shadow-" label="Custom Shadows"></token-specimen>Attributes
| Attribute | Values | Default | Description |
|---|---|---|---|
type | "shadow", "radius", "border", "color", "size", "icon" | — | Token type to display |
tokens | string | — | Comma-separated token names (for icon type: comma-separated icon names). Defaults vary by type |
prefix | string | — | CSS variable prefix (auto-set from type if omitted; ignored for icon type) |
show-values | boolean | true | Show computed token values (for icon type: show icon name labels) |
label | string | — | Optional heading label |
size | string | — | Icon size (icon type only): xs, sm, md, lg, xl, 2xl |
icon-set | string | — | Icon set (icon type only): lucide, phosphor, tabler, etc. Defaults to icon-wc's default |
editable | boolean | — | Turn value cells into inputs that write the token on the target scope. Ignored for icon type. |
target | string | — | CSS selector for the element to receive token overrides (default: ":root"). Only used when editable. |