Tokens
How the theme layer is put together and what to change first. The colors of the presentation layer are shown below by function; the complete list of every shipped token, with its value in both themes and what it points at, is the token catalog. To use the same foundation as Figma variables, see the Figma tokens guide.
Canonical groups
Section titled “Canonical groups”Theming ships as tokens.css — primitives (the raw palette) feed
semantic tokens (roles) that the components consume — plus a third tier of
per-component knobs that live in the components themselves (see
Component tokens):
import "@invisible-ui/svelte/tokens.css";colors.palette contains the complete named palette. colors.brand and
colors.feedback contain tenant choices. metrics and typography hold
dimensions and type settings. components.general defines shared UI decisions;
components.card, for example, defines Card-specific decisions.
The brand (--ds-colors-brand-*) and feedback (--ds-colors-feedback-*) tokens reference a
raw named scale (--ds-colors-palette-dioxazine-purple-500, --ds-colors-palette-alizarin-red-600, …) taken from the
color palette — never a raw value.
The primary is Dioxazine Purple and doubles as the selection / focus
color: selected controls and the focus ring derive from it. There is no distinct
secondary color — --ds-components-general-action-secondary-background-default resolves to the same purple.
“Secondary” names a function (a present-but-not-prominent button), realized
by inverting the primary, not a second hue.
Shared decisions (--ds-components-general-*). Role tokens that reference the
primitives and remap between light/dark. Components only ever read these:
--ds-components-general-action-primary-background-default: var(--ds-colors-brand-primary-default);--ds-components-general-feedback-danger-solid-background-default: var(--ds-colors-feedback-danger-default);--ds-components-general-foreground-default: var(--ds-colors-palette-grey-900); /* light; → --ds-colors-palette-grey-50 in dark */--ds-components-general-feedback-info-background-default: color-mix(in srgb, var(--ds-colors-feedback-info-default) 8%, var(--ds-colors-palette-grey-0));Naming rule — decoupled from style. A semantic token names a role (
background,border,foreground,primary…) or a state (hover,pressed,disabled,focus-ring…) — never an appearance. There is nomuted,softorsubtle: the neutral control fill is--ds-components-general-background-default, the hover overlay is--ds-components-general-background-hover. See ADR 0002 (tokens decoupled from style) in the repository’sdocs/adr/.
Tier 3 — component. Per-component tokens that point at a role or a primitive, never at a raw value. The background of each kind of component is one of them, so one kind can change without the others (see Component backgrounds); the other knobs live in the components themselves.
Component backgrounds
Section titled “Component backgrounds”Each kind of component reads its own background token. In the light theme they point at the page role, except the secondary card and the code block, which take the lightest grey. In the dark theme the page and the sidebar take Black, a near black; cards, dialogs, popovers, menus and code blocks take Grey 950, and the secondary card Grey 900.
| Token | Read by |
|---|---|
--ds-components-page-background-default |
The application’s page; no component paints it |
--ds-components-card-background-default |
Card |
--ds-components-card-secondary-background-default |
Card with the secondary surface |
--ds-components-dialog-background-default |
Dialog, Sheet, Alert, Confirm, Prompt and Search dialogs |
--ds-components-popover-background-default |
Popover, Hover Card, date picker popups, Navigation Menu panel |
--ds-components-menu-background-default |
Dropdown Menu, Context Menu, Menubar menus, Combobox and Multi Select listboxes |
--ds-components-sidebar-background-default |
Sidebar |
--ds-components-code-block-background-default |
Code Block |
Override one to restyle that kind of component alone:
:root { --ds-components-card-background-default: var(--ds-colors-palette-grey-50); /* example */}--ds-components-general-background-default stays the default for everything else: fields,
buttons and the other controls. Body text, supporting text and the control
boundary keep their contrast minimums on every component background in both
themes; the token catalog
measures each pair.
Background, foreground and state
Section titled “Background, foreground and state”Beyond brand and feedback, the semantic layer covers the everyday neutrals —
each named for its role or state, and each remapping per theme: the page
(--ds-components-general-background-default), an area on it (--ds-components-general-background-default and its hover),
text (--ds-components-general-foreground-default, --ds-components-general-foreground-secondary), the disabled state
(--ds-components-general-background-disabled, --ds-components-general-foreground-disabled), the interaction overlays
(--ds-components-general-background-hover, --ds-components-general-background-pressed) and focus
(--ds-components-general-focus-ring-color). Each one’s role, value per theme and alias chain is
listed in the token catalog.
Shared and component backgrounds
Section titled “Shared and component backgrounds”components.general.background.default is the shared background.
Each component owns its property tokens, for example
components.button.background.default. Shared choices are referenced by alias,
not duplicated under a generic container group.
Button reads components.button.background.hover; Ghost reads
components.button.background.ghost.hover. Both reference
components.general.background.hover, the same translucent interaction colour.
An explicit Button override changes Button only.
Two boundaries. --ds-components-general-border-default is the quiet line between areas:
dividers, table rules, the edge of a panel. --ds-components-general-border-control is the
boundary that identifies an interactive control — fields, outlined buttons,
check controls, the switch track — and it reaches 3:1 against the page and
against a surface in both themes (WCAG 2.2 SC 1.4.11). Style a divider with the
first and a control with the second; giving dividers the stronger colour makes
the page shout, and giving controls the quieter one makes them fail the
criterion.
Action fills. The secondary button paints --ds-components-button-background-secondary-default
with --ds-components-button-foreground-secondary-default as its label; the danger button paints
--ds-components-button-background-danger-default with --ds-components-button-foreground-danger-default.
“Danger” names the feedback status, “destructive” names the action, so the
status tint under a message (--ds-components-general-feedback-danger-background-default) and the fill of a
destructive button stay two different tokens.
Text emphasis (guideline). Reach emphasis levels through the role tokens,
never by picking a neutral weight directly: --ds-components-general-foreground-default for what is being
read, --ds-components-general-foreground-secondary for what supports it, and
--ds-components-general-foreground-disabled only on a control that cannot be used.
Shape & elevation (non-color)
Section titled “Shape & elevation (non-color)”Radius and shadow are tokens too, named for the role they shape rather than a pixel size:
| Token | Role |
|---|---|
--ds-metrics-radius-control |
buttons, inputs, the close button |
--ds-metrics-radius-container |
alerts, notices, cards |
--ds-metrics-radius-pill |
fully rounded: toggles, chips |
--ds-elevation-overlay |
the floating overlay shadow, per theme |
The current value of each is in the token catalog, under Radius and Elevation.
Components read these through their per-component override, e.g.
var(--ds-components-button-radius, var(--ds-metrics-radius-control, …)) — set the role token to
restyle a whole class of shapes at once, or the component token for a one-off.
Every such knob is listed in
Component tokens.
Customizing — in order of effort
Section titled “Customizing — in order of effort”- Brand — set
--ds-colors-brand-primary-default(primary buttons, selection and the focus ring follow). - Feedback — set
--ds-colors-feedback-*; the status icons and the InlineNotification/Notification surfaces re-derive. - Shared UI — set the relevant
--ds-components-general-*background, foreground or border. Keep the named palette immutable.
Theme switch. Follows prefers-color-scheme by default; force it per subtree
with [data-theme="dark"] / [data-theme="light"].
Forced colors (Windows High Contrast). The theme paints its focus ring with
a shadow, and forced colors drops every shadow, so tokens.css restores a real
outline in the platform’s own Highlight colour on whatever has keyboard focus
(:focus-visible). Only the outline is forced: each component keeps the offset
it already declares, so a control inside a scrolling row draws the ring within
itself and one with text at its edge does not draw across it. Controls whose
focus lives on a visually hidden input (checkbox, radio, switch, segmented
control, rating, toggle button, upload area) carry their own outline on the
visible part, and a combobox, multi-select or search list rings the option the
keyboard is on, since its tint would otherwise flatten away.
The rule is !important, which is what beats the components’ own
outline: none. To replace it, use !important at a higher specificity than
:focus-visible, for example .my-button:focus-visible. If you replace the
focus tokens, keep an outline: a shadow alone disappears in this mode. Our
checks emulate forced colors in Chromium, which supports but does not replace a
pass on real Windows High Contrast.
Accessibility. The defaults are checked against WCAG 2 AA (text 4.5:1, icon
glyphs 3:1) by an automated test over tokens.css, and the
token catalog measures
and publishes each pair it lists, target by target — including the ones that do
not reach their target in this alpha. If you change
the brand or feedback hues, re-verify contrast: white text sits on the
brand/danger fills and on the status icon boxes, while text labels with the
warning status (solid Tag, Count) sit on --ds-components-general-feedback-warning-label-background-default, a
lighter mix of the Burnt Orange, with a dark --ds-components-general-feedback-warning-solid-foreground-default at
4.5:1 or more.
Touch target. Under a coarse pointer, menu items and menubar triggers keep
a hit area of at least --ds-metrics-density-touch-min-target-size (44 by 44). Visual density
never reduces the touch target.