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.

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.

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