Component Tokens

A Visor theme has always been able to repaint the Tier-1 semantic surface — --surface-*, --text-*, --border-*, --interactive-*. That is enough to make an admin UI functional. It is not enough to make it look like one thing: nothing stopped a page inventing its own table-header treatment, its own chip tracking, its own filter-bar padding. A fidelity retro on a shipped admin app measured the result — 247 element categories across 13 families whose inconsistency traced to the substrate, not to any one component. The page title rendered five ways; the table header cell four ways; the same mono status chip at 8.5 / 9 / 9.5 / 10 / 11px across nine implementations.

Component tokens close that gap. Each family below exposes a set of component-scoped custom properties a theme binds once, in its .visor.yaml. Distil the design into the theme, and every consuming surface inherits it — instead of each page re-deriving the look in local CSS.

The two guarantees

1. Bind nothing and nothing changes. Every token is read as var(--token, <Tier-1 expression>) where the fallback is byte-for-byte what the component rendered before the token existed. A theme with no components: block is pixel-identical to a theme from before this contract, and the engine emits no extra CSS at all.
2. Bind one thing and every surface follows. A bound token retunes every consuming rule at once — the whole point of moving the decision into the theme.

Binding a family

# my-theme.visor.yaml
components:
  table:
    head-height: "2.5rem"
    head-font-family: '"IBM Plex Mono", monospace'
    head-font-size: "11px"
    head-text-transform: uppercase
    head-letter-spacing: "0.06em"
    head-bg:
      light: "#f7f7f8"
      dark: "#141418"
  chip:
    md-font-size: "11px"
    letter-spacing: "0.04em"
    text-transform: uppercase
  badge:
    text-transform: uppercase
    letter-spacing: "0.04em"
    font-size: "11px"
    font-weight: "600"

A bare string binds both modes; { light, dark } binds them independently, and a binding may be mode-asymmetric (dark only, say). Family and key names are validated — an unknown key is an error, not a warning, because a typo'd component token is otherwise silently inert: the component just keeps resolving its fallback and you never learn the binding missed.

Where the CSS lands

Bound tokens emit into the visor-adaptive cascade layer, on the same selectors as the Tier-1 adaptive set (light on the host selector; dark on the manual-toggle selectors plus a prefers-color-scheme query). Single-mode brands (color-scheme: dark-only / light-only) collapse onto the host selector, with no toggle blocks — the same shape every other emitter uses.

Component .module.css files use no @layer at all, so a consumer that really must override one surface locally still can. The point of this contract is that they should not have to.

Overriding without a theme

The same properties work as plain CSS custom properties, so a block or a page shell can scope a treatment without touching the theme:

.myAdminShell {
  --table-head-text-transform: uppercase;
  --table-head-letter-spacing: 0.06em;
}

Prefer the theme. A local override is exactly the per-page divergence this contract exists to end — reach for it only when the treatment genuinely belongs to one surface.

The contract

table

Table head, row and cell treatment. The retro measured the same header cell rendered four ways across one admin app; binding this family pins it once.

data-table

The admin-ui Tier-2 data-table surface stack (D3). Shared between the Table primitive and the DataTable shell so a list page and its table read as one surface.

chip

Chip / filter-pill treatment. The retro found the same mono status chip at 8.5 / 9 / 9.5 / 10 / 11px with tracking .03–.14em across nine implementations; this family is the single dial.

badge

Badge treatment — the D3 Tier-2 --badge-text-transform / -letter-spacing / -font-size / -font-weight set, promoted from the admin-ui audit to a bindable contract.

A theme-wide bg / ink binding paints every variant the same, including destructive and success, so status colour is lost. To tint one badge or one region, set --badge-bg / --badge-ink on that badge or its container instead.

status-badge

Status-badge indicator dot and the mono readout label. Chrome is inherited from the Badge family.

filter-bar

The operator's named case: "the filter bar above the table in many admin pages was pretty different from one to the next; that should be streamlined."

page-header

Page-header lockup. The retro found the page title rendered five ways across one app.

empty-state

Empty-state placard — surface, icon chip and copy scale.

banner

Full-width notice bar. The retro found six separate banner systems across ~180 instances in one app; binding this family collapses them to one.

sidebar

Sidebar chrome and nav-item treatment. The palette roles (bg, text, border, accent-*) already ship defaults from visor-core's visor-semantic layer and are read bare; the structural roles below are new in VI-625.

tabs

Tab rail and trigger treatment, for both the segmented (default) and underlined (line) variants.

skeleton

Loading-placeholder shimmer and the content-shape geometry the admin list/table/detail skeletons use.

spinner

Inline loading ring — track, leading edge, per-size geometry and cycle length.

checkbox

Control sizing — the D3 Tier-2 --checkbox-size / -radius / -bg / -border set, promoted from the admin-ui audit to a bindable contract.

input

Input shape at the default md size. Each key falls back to the matching --input-*-md variable, so a scope that sets one still applies while the key is unbound; a bound key wins.

textarea

Textarea shape at the default md size.

select

Select trigger shape at the default md size.

A 40px field with 10px 12px padding and 9px corners, on all three:

components:
  input:
    md-height: "40px"
    md-padding: "10px 12px"
    md-radius: "9px"
  textarea:
    padding: "10px 12px"
    radius: "9px"
  select:
    height: "40px"
    padding: "10px 12px"
    radius: "9px"

tag-input

TagInput — the field around the tags, each held tag, and the opt-in typing slot (entryAs="slot"). The slot follows the tag's shape unless its own keys are set.

The typing slot draws its dashed edge from --control-drop-edge-width and --control-drop-edge-style, so edges: off turns it off with every other edge. A 29px tag and slot with 9px corners, in a 40px field:

components:
  tag-input:
    min-height: "40px"
    padding: "5px"
    radius: "9px"
    tag-height: "29px"
    tag-padding-x: "10px"
    tag-font-weight: "300"
    tag-radius: "9px"

<TagInput entryAs="slot" defaultValue={["techno", "house"]} />

control

The one switch for form-control edges. Every form control — Input, Textarea, Select, Checkbox, Switch, TagInput, Chip, FileUpload, EmptyState and the edged Button faces — draws its resting edge from these, so edge-width: 0 removes every resting edge at once, dashed edges included.

Turning every edge off is one line in the theme:

# my-theme.visor.yaml
edges: off   # shorthand for components.control.edge-width: "0"

Or set the token on any ancestor, for one part of an app:

.editor {
  --control-edge-width: 0;
}

How the switch holds up:

• No layout shift. The edge is an outline pulled inside the box with a matching negative outline-offset, over a transparent border that only holds the box's geometry. Flipping the switch moves nothing.
• No border to fight. Nothing visible depends on border-color, so a consumer never needs a border-color: transparent !important override.
• Focus and invalid stay visible. They draw at state-edge-width, which the switch does not touch.
• The checkbox still reads as a box. With the edge off, an unchecked checkbox takes a fill (--checkbox-edgeless-bg), because the box is the control, not decoration.
• Dashed edges can come back on their own. Set --control-drop-edge-width to keep drop-target and empty-state edges while solid edges stay off.

The refused-value look on Input, Textarea and Select is a ring in the error colour plus a soft halo. A 1px ring with a 3px halo on all three:

components:
  control:
    invalid-ring-width: "1px"
    invalid-halo-width: "3px"

hairline

The one switch for hairlines. Every hairline rule, divider and ring — the soft separators and rings coloured by --hairline and --hairline-strong — reads its weight from --hairline-width, so width: 0 removes all of them at once. Independent of the control edge switch above: neither touches the other's tokens.

Turning every hairline off is one line in the theme:

# my-theme.visor.yaml
hairlines: off   # shorthand for components.hairline.width: "0"

Or set the token on any ancestor, for one part of an app:

.canvas {
  --hairline-width: 0;
}

How the switch holds up:

• Independent of edges. hairlines: off emits only --hairline-width: 0 and edges: off emits only --control-edge-width: 0. Set both, either, or neither.
• No layout shift. Hairlines follow the same rule as the control edge: the box keeps its geometry and only the paint changes. A ring (all four sides) is an outline pulled inside a transparent border of constant width (outline-offset: calc(-1 * var(--hairline-width))); a single rule (a rail, a header or footer rule, a divider) is a transparent border of constant width with the line painted by border-image at --hairline-width; a divider that is its own 1px box is an inset box-shadow. Flipping the switch moves nothing. Rendering with it on is unchanged.
• Two exceptions, both collapsed-border tables. border-image and outline do not apply to a border-collapse: collapse cell, so Table's cell hairline and MatrixTable's header and cell rules stay real borders. Table's cell rule shares its edge with the row rule, so removing it moves nothing; MatrixTable's header/body join has no second rule, so it tightens by 1px.
• A bound border shorthand wins. --tabs-line-border-bottom and --dialog-form-panel-border take a full border value. Bound, they draw that border instead of the painted hairline, and the switch no longer governs them.
• Colour is still yours. --hairline and --hairline-strong are unchanged; the switch is the width, so a theme can still tune the colour while hairlines are on.
• Focus and invalid stay visible. They draw at --control-state-edge-width, which this switch does not touch.

field

Field label treatment — size, case, tracking and colour of FieldLabel, in both densities.

button

Button type treatment and rounding. The unprefixed keys set every size at once; a size key (dlg-radius) overrides one size.

text

Text type treatment, per size — set sm-font-size: 13px for a 13px step, or caps and tracking on xs for a state tag. Every key begins with a size.

switch

Switch track and knob dimensions (default size; size="sm" keeps its own) and colours. Set knob-inset to size the knob from the track: it sits that far from the track's outer edge on every side.

Every hook in field, button, text and switch defaults to what shipped before it existed. Case and tracking are declared in Visor's lowest cascade layer (visor-base, where the reset lives) and fall back to revert-layer, so while a hook is unset the element is exactly as it would be without it: your own rules, a utility class, a reset, inheritance or the browser's <button> default still decide. Set, the hook still yields to any rule of yours.

A compact caps pill for dialog actions, a 13px state line and a caps state tag:

# my-theme.visor.yaml
components:
  button:
    dlg-font-size: "10px"
    dlg-text-transform: uppercase
    dlg-letter-spacing: "0.06em"
    dlg-radius: "999px"
  text:
    sm-font-size: "13px"
    xs-font-size: "9px"
    xs-text-transform: uppercase
    xs-letter-spacing: "0.12em"
  field:
    label-font-size: "9px"
    label-text-transform: uppercase
    label-letter-spacing: "0.12em"
    label-color: "var(--text-tertiary)"
  switch:
    track-width: "30px"
    track-height: "17px"
    knob-inset: "3px"

None of these hooks draws an edge. The outline Button (at any size, dlg included) and the Switch track take their edge from the control family, so control.edge-width: 0 still turns them off.

save-status

SaveStatus readout — the fixed-width slot, its type, the Syncing ink and the Unsaved dot, so the readout never reflows its row.

Family, case and tracking sit in visor-base and fall back to revert-layer, like the type hooks above, so while they are unset the readout inherits from its row and any rule of yours wins. A 78px caps mono readout:

components:
  save-status:
    width: "78px"
    font-family: "var(--font-mono)"
    text-transform: uppercase
    letter-spacing: "0.06em"

With dot, SaveStatus draws a status dot before the label in every state, in the state's ink. A 9px readout with a 5px dot that grows to 6px while unsaved:

components:
  save-status:
    font-size: "9px"
    dot-size: "5px"
    unsaved-dot-size: "6px"

The dot's box is as wide as the larger diameter, so the label never moves.

SaveStatus draws no edge, so there is nothing for control.edge-width to turn off.

segmented-control

SegmentedControl — the well, its corner radius, the sliding pill, the ink and the state edge on it. The resting edge is the shared control edge.

The state edge is an inset ring at --control-state-edge-width (the width focus and invalid use), so control.edge-width: 0 turns the resting edge off and leaves the state edge, with no layout shift. A theme whose pill already clears 3:1 against the well, such as an accent fill on black, binds it to transparent:

components:
  segmented-control:
    indicator-edge: "transparent"

A red pill with white ink, muted inactive labels, a bold active label and an 8px track:

components:
  segmented-control:
    indicator-bg: "#e51a1a"
    indicator-text: "#ffffff"
    inactive-text: "rgba(255, 255, 255, 0.46)"
    active-weight: "600"
    radius: "8px"

SegmentedControl's resting edge is an outline from --control-edge-*, so control.edge-width: 0 turns it off while focus stays visible.

toggle-group

ToggleGroup — the outline track's fill, the selected option's fill and ink, the unselected ink, and the compact (xs) size: its label size, option sides and corners. SegmentedControl takes the xs option keys too.

The track fill is set at zero specificity, so a consumer class that sets the group's background still wins. SegmentedControl keeps its own track, pill and inks (segmented-control); only the xs option keys reach it. A dark theme that wants a compact group on a well, with the selected option in a soft accent wash:

components:
  toggle-group:
    track-bg: "rgba(0, 0, 0, 0.65)"
    selected-bg: "rgba(44, 224, 230, 0.09)"
    selected-text: "#2ce0e6"
    unselected-text: "rgba(255, 255, 255, 0.46)"
    xs-font-size: 10px
    xs-padding-x: 11px
    xs-track-radius: 8px
    xs-item-radius: 6px

tooltip

Tooltip ground and ink, so a dark theme can keep the label legible without retuning the shared inverse pair other components read.

Unbound, the tooltip reads --surface-overlay under --text-inverse, as it always has. In a dark theme both can resolve dark, and --text-inverse cannot be retuned for the tooltip alone: it is the dark ink Calendar, Badge and Chip set on light and accent fills. Bind the pair in dark mode instead:

components:
  tooltip:
    bg:
      dark: "rgba(0, 0, 0, 0.8)"
    text:
      dark: "#fafafa"

A flat overrides.dark.tooltip-bg / tooltip-text pair emits the same two properties through the brand pass-through.

action-row

ActionRow state fills, edge and geometry: rest, hover, open, selected and disabled each read their own token.

Unbound, the selected row is --surface-interactive-active (a neutral lift, not the accent --surface-selected) with a --text-secondary inset edge. The row has no resting edge, and the selected edge is a state edge at --control-state-edge-width, like focus and invalid: edges: off leaves it (WCAG 1.4.11 asks 3:1 for a state indicator). The list's hairlines between rows read --hairline-width (hairlines: off). Focus stays visible either way. A dark theme that wants the lifted dark fill with a light edge binds the two selected tokens:

components:
  action-row:
    selected-bg:
      dark: "#26262b"
    selected-edge-color:
      dark: "rgba(255, 255, 255, 0.24)"

input-affix

Input and NumberInput prefix and suffix: the gap between a fixed affix and the value, and the affix's ink.

The affix draws no edge of its own. The well keeps its one edge from the control tokens, around the affix and the value together, so control.edge-width: 0 turns it off and focus and invalid stay visible.

components:
  input-affix:
    gap: "12px"
    color:
      dark: "#a3a3a3"

separator

The line a Separator draws, bare or on both sides of a label.

A borderless theme sets border-default to transparent, which hides the rule. Bind separator.color to keep it visible without bringing structural borders back.

components:
  separator:
    color:
      dark: "#2c2c2c"

alert

Alert's soft appearance: the inline alert under a control or in a dialog. Every key is soft-only, so binding the family never moves an edged Alert.

The defaults are Animal Booking's build. Blacklight's door sets a smaller, lighter type:

components:
  alert:
    font-size: "13px"
    lead-font-weight: "600"

admin-ui

Structural roles the admin-ui pattern owns. marquee-family is the display face for KPI hero figures and marquee page titles — the role the admin-ui portability audit named as the one piece of ENTR brand coupling a new theme must rebind.

Emit-only roles

Two entries above have no Visor component reading them. They exist so a generated theme can carry the admin-ui pattern's Tier-2 treatment layer rather than leaving it as prose in a design audit — the pattern shell (design-prototypes/admin-ui/tokens.css) is the consumer. --surface-screen is the deepest chrome tier (the sidebar rail); bind it to the theme's deep overlay, never to a literal.

See also

• Token Rules — the rules every token and fallback must satisfy
• Creating Themes — the full .visor.yaml surface
• Theming — how a theme is applied and switched