Guide
Theming
Tokens
Three layers, in src/tokens.css — the only file permitted to contain a colour
literal.
- Surface & text —
--axi-ground,--axi-surface,--axi-surface-raised,--axi-ink-line,--axi-ground-deep,--axi-rule,--axi-text,--axi-text-dim,--axi-text-faint,--axi-scrim - Accent & status —
--axi-accent,--axi-accent-ink,--axi-meta,--axi-ok,--axi-warn,--axi-danger. This is the per-app override surface. An app that sets--axi-accentand nothing else is correctly themed. - Form — outline and offset steps, radii, measures (
--axi-page,--axi-page-narrow,--axi-page-wide,--axi-gutter) and the type scale. Overriding these means leaving the language, not theming it.
Theming an app
:root { --axi-accent: #b06bff; }
If an app picks an accent dark enough that near-black text on it fails
contrast, it also sets --axi-accent-ink: var(--axi-text). It should not edit
components.
The official accents
--axi-accent is the per-app theming surface, and the family agrees on what
may go in it. The official accents live in accents.json — id, label, hex —
and dist/accents.css is generated from it: one [data-axi-accent="<id>"]
selector per accent, setting --axi-accent and nothing else. An app opts in
by importing accents.css alongside axi.css and setting data-axi-accent
on its root element; an app that renders a picker reads accents.json for the
ids and labels.
| Accent | Id | Hex |
|---|---|---|
| Axi Gold | axi-gold | #ffc53d |
| Electric Blue | electric-blue | #3b82f6 |
| Refined Cyan | refined-cyan | #5eadd5 |
| Amber Warm | amber-warm | #f59e0b |
| Emerald Mint | emerald-mint | #34d399 |
| Rose Pink | rose-pink | #f43f5e |
| Violet Purple | violet-purple | #8b5cf6 |
| Crimson Red | crimson-red | #ef4444 |
| Slate Silver | slate-silver | #94a3b8 |
| Teal Ocean | teal-ocean | #14b8a6 |
| Gold Bronze | gold-bronze | #d4a017 |
| Electric Cyan | electric-cyan | #22d3ee |
The default remains #ffc53d Axi Gold, declared in tokens.css: an app that
sets no data-axi-accent is gold, and correctly themed.
Themes
An accent moves one ink. A theme repaints the surface layer: import it beside
axi.css and set one attribute on your root element.
import '@axiapps/axi-design/axi.css'
import '@axiapps/axi-design/themes/glass.css'
<html data-axi-theme="glass">
| Theme | Attribute | Import |
|---|---|---|
| Flat | data-axi-theme="flat" | @axiapps/axi-design/themes/flat.css |
| Glass | data-axi-theme="glass" | @axiapps/axi-design/themes/glass.css |
The picker in the masthead does exactly that and nothing else, so the page you are reading is the demo: switch it and every component on this site repaints at once, with no markup anywhere knowing which theme is on.
That is the whole contract. A theme is one [data-axi-theme="<id>"] block of
custom properties restating tokens the main theme already declares — it may
not invent a token, add a selector, or ship a component the main theme lacks,
and tests/themes.test.mjs fails the build if one tries. So there is never a
.axi-panel--glass to migrate to and never one to migrate back from: remove
the attribute and you are on the main theme, with no other change.
The main theme is the language and a theme is a repaint of it — the Themes section of the rules says what a theme may and may not do.
Knobs are not tokens
Tokens answer "what does the system look like" — they live in :root, once,
and every component reads them. Per-instance knobs answer a different
question: "how wide is this grid". They are custom properties a component
reads with a fallback and never declares itself, so setting one on a single
element or on any ancestor changes only what it cascades to. Setting most of
them in :root is legal and meaningless, because a knob is never asking what
the system looks like — a --axi-grid-min set globally does not make sense
the way --axi-accent set globally does.
Every knob below is scoped with a style="" attribute on the element or an
ancestor, not in a global stylesheet:
<button class="axi-pill" aria-pressed="true" style="--axi-pill-fill: var(--axi-danger)">
| Knob | Sets | Fallback | Example |
|---|---|---|---|
--axi-pill-fill |
the fill a pressed .axi-pill takes |
var(--axi-accent) |
<button class="axi-pill" aria-pressed="true" style="--axi-pill-fill: var(--axi-danger)"> |
--axi-switch-fill |
the fill an on .axi-switch takes |
var(--axi-accent) |
<button class="axi-switch" aria-checked="true" style="--axi-switch-fill: var(--axi-danger)"> |
--axi-switch-w |
a .axi-switch's track width |
46px |
<button class="axi-switch" style="--axi-switch-w: 32px"> |
--axi-switch-h |
a .axi-switch's track height |
26px |
<button class="axi-switch" style="--axi-switch-h: 18px"> |
--axi-switch-knob |
a .axi-switch's slug (knob) size |
16px |
<button class="axi-switch" style="--axi-switch-knob: 11px"> |
--axi-check-size |
the size of an .axi-check or .axi-radio box |
22px |
<input type="checkbox" class="axi-check" style="--axi-check-size: 16px"> |
--axi-check-fill |
the fill a checked .axi-check takes, and the colour of a checked .axi-radio's diamond |
var(--axi-accent) |
<input type="checkbox" class="axi-check" style="--axi-check-fill: var(--axi-danger)"> |
--axi-textarea-h |
the minimum height of a <textarea class="axi-input"> |
90px |
<textarea class="axi-input" style="--axi-textarea-h: 200px"> |
--axi-btn-pad |
the padding inside an .axi-btn. The three named steps set it for you; reach for the knob only for a size they do not cover |
12px 20px |
<button class="axi-btn" style="--axi-btn-pad: 3px 7px"> |
--axi-btn-size |
an .axi-btn's text size, which travels with its padding |
13px |
<button class="axi-btn" style="--axi-btn-size: 10px"> |
--axi-pill-pad |
the padding inside an .axi-pill. The same scale and the same two named steps as the button, because a pill is a button that holds a state |
12px 20px |
<button class="axi-pill" style="--axi-pill-pad: 3px 7px"> |
--axi-pill-size |
an .axi-pill's text size, which travels with its padding |
13px |
<button class="axi-pill" style="--axi-pill-size: 10px"> |
--axi-input-pad |
the padding inside an .axi-input, for a field that is furniture in a header rather than a control on a page |
11px 12px |
<input class="axi-input" style="--axi-input-pad: 7px 12px"> |
--axi-input-size |
an .axi-input's text size, which travels with its padding |
14px |
<input class="axi-input" style="--axi-input-size: 13px"> |
--axi-action-hit |
the hit target of an .axi-action--glyph, whose label is one character and gives the pointer nothing to land on |
24px |
<button class="axi-action axi-action--glyph" style="--axi-action-hit: 32px"> |
--axi-well-pad |
the padding inside an .axi-well |
10px |
<div class="axi-well" style="--axi-well-pad: 18px"> |
--axi-well-radius |
an .axi-well's corner radius, for a well used at reading scale rather than page scale |
var(--axi-radius) |
<div class="axi-well" style="--axi-well-radius: var(--axi-radius-sm)"> |
--axi-empty-pad |
the padding inside an .axi-empty, for an empty state standing in a tighter space than a table would |
24px 16px |
<div class="axi-empty" style="--axi-empty-pad: 12px"> |
--axi-rail-w |
an .axi-rail's width, for labels longer than the default holds |
208px |
<aside class="axi-rail" style="--axi-rail-w: 260px"> |
--axi-rail-pad |
the padding inside an .axi-rail |
10px |
<aside class="axi-rail" style="--axi-rail-pad: 6px"> |
--axi-toolbar-pad |
the padding inside an .axi-toolbar |
14px |
<div class="axi-toolbar" style="--axi-toolbar-pad: 4px 7px"> |
--axi-dock-pad |
the padding inside an .axi-dock |
12px 16px |
<div class="axi-dock" style="--axi-dock-pad: 6px 10px"> |
--axi-avatar-size |
the size of an .axi-avatar square |
40px |
<span class="axi-avatar" style="--axi-avatar-size: 28px">MS</span> |
--axi-modal-width |
the maximum width of an .axi-modal, before the viewport clamp |
560px |
<dialog class="axi-modal" style="--axi-modal-width: 760px"> |
--axi-card-strip |
the colour of .axi-card--strip's top strip |
var(--axi-accent) |
<a class="axi-card axi-card--strip" style="--axi-card-strip: var(--axi-ok)"> |
--axi-grid-min |
minimum column width in .axi-grid |
300px |
<div class="axi-grid" style="--axi-grid-min: 240px"> |
--axi-matrix-cell |
the floor on a matrix cell's height and width | 24px |
<table class="axi-table axi-table--matrix" style="--axi-matrix-cell: 18px"> |
--axi-split-nav-w |
the width of an .axi-split's picker column |
280px |
<div class="axi-split" style="--axi-split-nav-w: 180px"> |
--axi-split-gap |
the parting between an .axi-split's picker and its body |
10px |
<div class="axi-split" style="--axi-split-gap: 16px"> |
--axi-split-nav-h |
the picker's height cap once an .axi-split has stacked under 640px |
200px |
<div class="axi-split" style="--axi-split-nav-h: 140px"> |
--axi-row-gap |
gap between .axi-row children |
10px |
<div class="axi-row" style="--axi-row-gap: 6px"> |
--axi-stack-gap |
gap between .axi-stack children |
12px |
<div class="axi-stack" style="--axi-stack-gap: 20px"> |
--axi-eyebrow-gap |
the gap under an .axi-eyebrow; tighter by default inside a tile |
14px, or 6px inside .axi-panel--tile |
<p class="axi-eyebrow" style="--axi-eyebrow-gap: 0"> |
--axi-readout-pad |
the vertical padding of an .axi-readout__row; tighter by default inside a tile |
7px, or 3px inside .axi-panel--tile |
<dl class="axi-readout" style="--axi-readout-pad: 10px"> |
--axi-panel-pad |
.axi-panel's own padding |
26px |
<div class="axi-panel" style="--axi-panel-pad: 14px"> |
--axi-page-pad |
.axi-page's horizontal gutter |
var(--axi-gutter) |
<div class="axi-page axi-page--narrow" style="--axi-page-pad: 0"> |
--axi-palette-w |
the widest an .axi-palette__panel gets (it fills the room below that) |
560px |
<div class="axi-palette__panel" style="--axi-palette-w: 720px"> |
--axi-palette-top |
how far down the screen an .axi-palette opens |
12vh |
<div class="axi-scrim axi-palette" style="--axi-palette-top: 6vh"> |
--axi-menu-width |
width of .axi-menu__pop |
310px |
<div class="axi-menu__pop" style="--axi-menu-width: 380px"> |
--axi-drawer-width |
width of .axi-drawer (capped at 100vw) |
560px |
<aside class="axi-drawer" style="--axi-drawer-width: 720px"> |
--axi-sheet-top |
where an .axi-sheet's top edge sits, for an app whose own chrome starts above it |
0 |
<div class="axi-sheet" style="--axi-sheet-top: 2.5rem"> |
--axi-sheet-pad |
the padding inside an .axi-sheet |
12px 16px |
<div class="axi-sheet" style="--axi-sheet-pad: 0"> |
--axi-series |
the ink a meter fill, bar, plot line or .axi-diamond--series is drawn in |
var(--axi-accent) |
<span class="axi-meter__fill" style="--axi-series: var(--axi-ok)"> |
--axi-meter-v |
how full one .axi-meter__fill is |
0% |
<span class="axi-meter__fill" style="--axi-meter-v: 62%"> |
--axi-meter-h |
height of a .axi-meter |
12px |
<div class="axi-meter" style="--axi-meter-h: 18px"> |
--axi-meter-label |
the label column width of .axi-meter-list |
132px |
<div class="axi-meter-list" style="--axi-meter-label: 180px"> |
--axi-meter-value |
the value column width of .axi-meter-list |
62px |
<div class="axi-meter-list" style="--axi-meter-value: 80px"> |
--axi-bar-v |
height of one .axi-bars__col |
0% |
<div class="axi-bars__col" style="--axi-bar-v: 78%"> |
--axi-bar-part |
height of one .axi-bars__part within its column |
0% |
<span class="axi-bars__part" style="--axi-bar-part: 40%"> |
--axi-bars-gap |
gap between columns in .axi-bars |
6px |
<div class="axi-bars" style="--axi-bars-gap: 2px"> |
--axi-plot-h |
height of a .axi-plot or .axi-bars |
180px |
<div class="axi-plot" style="--axi-plot-h: 240px"> |
--axi-plot-rows |
how many horizontal rules a .axi-plot draws |
4 |
<div class="axi-plot" style="--axi-plot-rows: 6"> |
--axi-tick-w |
the width of one .axi-ticks__tick |
5px |
<div class="axi-ticks" style="--axi-tick-w: 7px"> |
--axi-tick-h |
the height of an .axi-ticks strip, and so of every mark in it |
15px |
<div class="axi-ticks" style="--axi-tick-h: 22px"> |
--axi-ticks-gap |
the gap between marks in .axi-ticks |
3px |
<div class="axi-ticks" style="--axi-ticks-gap: 2px"> |
--axi-spinner-size |
the size of an .axi-spinner |
20px |
<span class="axi-spinner" style="--axi-spinner-size: 34px"></span> |
--axi-skeleton-w |
the length of an .axi-skeleton bar |
100% (56px on .axi-skeleton--chip) |
<span class="axi-skeleton" style="--axi-skeleton-w: 96px"></span> |
--axi-icon-size |
an .axi-icon's box, both dimensions |
1.25em |
<svg class="axi-icon" style="--axi-icon-size: 2rem"><use href="#axi-search"/></svg> |