axi-designv1.50.0

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-accent and 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.

AccentIdHex
Axi Goldaxi-gold#ffc53d
Electric Blueelectric-blue#3b82f6
Refined Cyanrefined-cyan#5eadd5
Amber Warmamber-warm#f59e0b
Emerald Mintemerald-mint#34d399
Rose Pinkrose-pink#f43f5e
Violet Purpleviolet-purple#8b5cf6
Crimson Redcrimson-red#ef4444
Slate Silverslate-silver#94a3b8
Teal Oceanteal-ocean#14b8a6
Gold Bronzegold-bronze#d4a017
Electric Cyanelectric-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">
ThemeAttributeImport
Flatdata-axi-theme="flat"@axiapps/axi-design/themes/flat.css
Glassdata-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>