@axiapps/axi-design 1.10.0 → 1.11.0

package/dist/themes/glass.css

@@ -0,0 +1,11 @@
+/* axi design language - generated by scripts/build.mjs.
+   Edit the files in src/ and run `npm run build`; do not edit this file. */
+
+[data-axi-theme="glass"] {
+  --axi-ground: #141924;
+  --axi-surface: rgba(255, 255, 255, .09);
+  --axi-surface-raised: rgba(255, 255, 255, .15);
+  --axi-rule: rgba(255, 255, 255, .17);
+  --axi-scrim: rgba(6, 7, 9, .55);
+  --axi-surface-filter: blur(14px) saturate(140%);
+}

package/docs/RULES.md

@@ -14,7 +14,12 @@ to draw a *shape*, with no soft transition anywhere in them: the select caret
 (two `linear-gradient`s meeting to make a triangle) and `.axi-plot`'s
 gridlines (a `repeating-linear-gradient` of hard stops, which is how N evenly
 spaced rules get drawn without asking every consumer to emit N empty divs).
-A gradient across a surface is still forbidden, and always will be.
+A gradient across a surface is still forbidden in every component file, and
+always will be. The single relief is a *theme* restating the surface tokens
+themselves — see [Themes](#themes) — which is what lets a glass theme exist
+without one component ever learning the word "glass". A component cannot reach
+for that exception, because it cannot see it: what it reads is the same surface
+token it was already reading.
 
 ## 2. No colour at partial opacity over the ground
 
@@ -23,9 +28,19 @@ just brown, and five muted inks over near-black are five browns. When something
 should be quieter, reach for a neutral from the ramp — that is what the ramp is
 for.
 
+A theme gets the same carve-out as rule 1 and not one inch more: it may hold the
+*surface* tokens at partial opacity, because a translucent surface is that
+surface's own definition rather than a colour laid over the ground. The inks are
+untouched. A muted `--axi-warn`, a faded accent, a status ink at 60% — still
+forbidden, in a theme exactly as in a component, because the paragraph above is
+about what happens to meaning when five inks become five browns, and changing
+which stylesheet does the muting does not change that.
+
 ## 3. Every raised element is outlined and blocked
 
 An `--axi-ink-line` border plus a hard offset shadow, never a blur.
+A component spells that shadow `var(--axi-shadow-panel)` or
+`var(--axi-shadow-control)`; the offsets those compose are in the table below.
 
 Two weight steps, and only two:
 
@@ -37,10 +52,21 @@ Two weight steps, and only two:
 A third step is how a system stops looking like one system.
 
 There is one weight outside the table, and it is deliberately not a step:
-`--axi-border-hairline` (2px), used only inside `.axi-prose` — for inline
-code, table rules and the list bullet — where either form step reads as too
-heavy for a line of running text. It is a prose rule weight, never an outline
-on a raised thing.
+`--axi-border-hairline` (2px). It is a **rule** weight — a line drawn inside
+content to separate parts of it, where either form step would turn a list of
+numbers into a grid of boxes. That covers inline code and the list bullet in
+`.axi-prose`, the rules between table rows, and the gridlines inside a plot.
+It is never an outline on a raised thing: the two steps in the table above are
+what raise a surface, and reaching for the hairline instead is how a panel
+stops looking raised.
+
+There is exactly one element drawn in the line ink rather than on a surface,
+and it is named here so it stays an exception rather than becoming a habit:
+`.axi-tooltip` is filled with `--axi-ink-line` itself. A thing cannot be
+outlined in the colour it is already made of, and a block in that same ink
+under a box already made of it reads as the box being thicker rather than
+raised — so the tooltip takes a hairline in `--axi-rule` to hold its edge
+against the page, and carries no block. Nothing else may use that reasoning.
 
 **What is mechanically enforced.** `tests/tokens.test.mjs` enforces both
 columns:
@@ -52,18 +78,24 @@ columns:
   `outline`/`outline-width` are checked the same way as `border`
   (`outline-offset` and `outline-color` are not weight properties and are
   untouched).
-- *Offset* — every `box-shadow` in a component file must be exactly
-  `<offset> <offset> 0 var(--axi-ink-line)`, with the offset drawn from an
-  enumerated list of four tokens: the two resting steps above, plus the two
-  hover deepenings rule 4 describes (`--axi-offset-panel-hover` 10px,
+- *Offset* — the block is composed once, in `tokens.css`, as one of four
+  `--axi-shadow-*` tokens, and each must be exactly
+  `<offset> <offset> 0 var(--axi-ink-line)` with the offset drawn from an
+  enumerated list of four: the two resting steps above, plus the two hover
+  deepenings rule 4 describes (`--axi-offset-panel-hover` 10px,
   `--axi-offset-control-hover` 6px). That is what rules out a blur, a spread,
-  an invented offset and a shadow in any colour but the ink line.
-  `filter: drop-shadow(...)` and `text-shadow` — the two other CSS properties
-  that can draw the same blurred look — are forbidden outright, since nothing
-  in this language legitimately reaches for either.
+  an invented offset and a shadow in any colour but the ink line. A component
+  file then names one of the four — `box-shadow: var(--axi-shadow-panel)` —
+  and may write nothing else in a `box-shadow`. Two checks rather than one,
+  because either alone is hollow: the shape check protects the four
+  definitions, the naming check stops a component composing its own block
+  beside them. `filter: drop-shadow(...)` and `text-shadow` — the two other
+  CSS properties that can draw the same blurred look — are forbidden
+  outright, since nothing in this language legitimately reaches for either.
 - *No local escape hatch* — the form tokens themselves
   (`--axi-border-panel`, `--axi-border-control`, `--axi-border-hairline`,
-  `--axi-offset-panel`, `--axi-offset-control`, and their `-hover` variants)
+  `--axi-offset-panel`, `--axi-offset-control`, their `-hover` variants, and
+  the four `--axi-shadow-*` blocks composed from them)
   may be **declared** only in `tokens.css`. A component file redeclaring one
   of these on itself would change the value the border/offset checks above
   are silently trusting, without changing the `var()` text those checks read
@@ -173,8 +205,12 @@ than framing it down the left edge. A full-height stripe runs the height of the
 box, so it reads as the box's border: five cards in a row become five coloured
 frames, and the colour stops saying anything about any one number. A cap sits
 directly over the reading it is a verdict on, identifies it once, and then gets
-out of the way. Under rule 3 the cap is drawn at the panel weight; the card
-itself keeps its plain ink outline at the control weight.
+out of the way. Under rule 3 both the cap's edge and the card's own outline are
+drawn at the panel weight, because the card is a raised surface and rule 3
+pairs the panel border with the panel offset the card already carries. A card
+outlined at the control weight would pair a 3px border with a 6px offset —
+a third step in everything but name — and would put a thin frame around a
+heavier bar.
 
 A switch is the same rule in a slot. Its track fills to assert the setting's
 status and is empty otherwise; the slug that moves is `--axi-ink-line` in both
@@ -236,6 +272,14 @@ Three bounds, and the rule is only sound with all three:
   carries a 6px block. A second 6px block nested in the first reads as two
   planes arguing; the 3px control step reads as the contents of a box. This is
   also the honest weight: each row is a control you press, not a surface.
+- **Text on a status fill is `--axi-ink-on-fill`, not `--axi-ink-line`.** The
+  two hold the same near-black today, which is why this was easy to get wrong:
+  a chip that says `color: var(--axi-ink-line)` reads correctly and still means
+  the wrong thing. `--axi-ink-line` is *the colour a shape is outlined in*;
+  `--axi-ink-on-fill` is *the colour a word is written in when it sits on a
+  saturated fill*. They only have to diverge once — a theme that outlines in a
+  light colour — for the conflated spelling to put light text on a bright chip.
+  `--axi-accent-ink` is the same distinction for the accent fill specifically.
 - **The outline stays `--axi-ink-line`.** Status goes on a filled shape inside
   the row — the icon tile, a chip — and never on the row's own edge. Colouring
   the edge is exactly the full-height stripe rule 5 rejects: five states become
@@ -328,6 +372,31 @@ 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.
 
+### Layer stack
+
+Every `z-index` in this language is one of the layers below, and a component
+that needs to sit above something picks its layer here rather than inventing a
+number. A number not in this table is a component shouting over the stack
+instead of joining it.
+
+| Layer | z-index | What sits here |
+|---|---|---|
+| Sticky chrome | 40 | `.axi-mast` |
+| Popovers | 41 | `.axi-menu__pop`, `.axi-picker__pop` |
+| Scrim | 50 | `.axi-scrim` |
+| Drawer | 51 | `.axi-drawer` |
+| Toasts | 60 | `.axi-toasts` |
+| Tooltip | 70 | `.axi-tooltip` |
+| Modal | top layer | `dialog.axi-modal`, promoted by `showModal()` |
+
+The modal has no number on purpose. A `<dialog>` opened with `showModal()` is
+promoted to the browser's top layer, which sits above every `z-index` there is;
+writing a number in that row would describe a competition the modal is not in.
+
+A negative `z-index` inside a component's own `isolation` context — the sigil's
+backing shape — is not a layer and is not listed. It is invisible outside the
+component that owns it.
+
 ## Light mode
 
 Not shipped. The system is *structured* for it: no component contains a colour
@@ -335,6 +404,9 @@ literal, so a light theme is a second palette block, not a rewrite. It is not
 a token swap either — the saturated inks that read as vivid on near-black go
 washed out on white and would need retuning.
 
+When it does ship it ships as a theme, under the section below, with the same
+1:1 obligation: light mode does not get a component the dark language lacks.
+
 ## The official accents
 
 `--axi-accent` is the per-app theming surface, and the family now agrees on
@@ -354,12 +426,69 @@ dist/axi.css.
 The default remains `#ffc53d` Axi Gold, declared in tokens.css: an app that
 sets no `data-axi-accent` is gold, and correctly themed.
 
+## Themes
+
+The palette in `tokens.css` is not "the default theme". It is the language, and
+a theme is a repaint of it. Everything rules 1-11 describe — the outline, the
+block, what a fill means, what the cool ink is reserved for — is defined once,
+there, and a theme inherits all of it. Anything a theme cannot say by restating
+a token is not a theme; it is a change to the language, and it goes through the
+rules above like any other.
+
+A theme is a generated stylesheet, `dist/themes/<id>.css`, built the way
+`dist/accents.css` is: `themes/<id>.json` is the source of truth and the build
+emits one `[data-axi-theme="<id>"]` block of custom properties, no structural
+CSS. That makes `themes/*.json` the third sanctioned home for a colour literal,
+after `tokens.css` and `accents.json`, and for the same reason as the second —
+it is data the build generates from, not stylesheet source. Hand-editing
+`dist/themes/glass.css` is exactly as wrong as hand-editing `dist/axi.css`. A consumer imports it beside `axi.css` and sets
+`data-axi-theme` on its root element. That is the whole integration — which is
+the point. A site gets the dark language by default and a different one by
+adding an attribute, and in neither case does it author, carry or maintain a
+line of theme CSS of its own.
+
+**A theme mirrors the main theme one-for-one.** In both directions:
+
+- **Nothing added.** No token a theme invents, no selector but its own root
+  hook, and above all no component that exists only under a theme. There is no
+  `.axi-panel--glass`, no glass-only card, no variant that appears when the
+  attribute is set. A component that is worth having is worth having in the
+  language; one that only makes sense translucent is a component the language
+  does not have.
+- **Nothing dropped.** A theme may not leave a token unset and a component
+  unpainted. Every component renders under every theme, which is what makes the
+  attribute a swap rather than a migration — a site can set it, unset it, or
+  offer the choice to its users, and no markup changes either way.
+
+The consequence worth stating plainly: **a new theme capability costs a
+main-theme token first.** A glass theme wants a `backdrop-filter`; it does not
+get to introduce one. `--axi-surface-filter` is declared in `tokens.css` with an
+inert default (`none`), the surfaces read it unconditionally, and the theme
+restates it. The main theme is unchanged in appearance and the hook is part of
+the language rather than part of the theme. Every theme pays this toll, and it
+is what keeps the mirror true: a token the theme could set that the main theme
+had never heard of is the first step back toward theme-only components.
+
+Rules 1 and 2 name the only relief a theme gets, and it is confined to the
+surface layer: a theme may put a gradient on a surface and may hold a surface
+token at partial opacity. It may not mute an ink. Read those two rules for why.
+
+**What is mechanically enforced.** `tests/themes.test.mjs` reads every
+`dist/themes/*.css` and checks the mirror rather than trusting it: the file
+contains exactly one rule, its selector is `[data-axi-theme="<id>"]` for the
+`<id>` in its own filename, every declaration in it is a custom property with a
+non-empty value, and every property it declares is already declared in
+`tokens.css`. A theme-only component fails the first check, because drawing one
+takes a second selector. An invented token fails the last. The suite passes
+vacuously while no theme exists, and binds the moment the first file lands.
+
 ## Adding a component
 
 1. Which rule justifies it? If none, write the rule first or stop.
 2. Build it from the existing primitives. A shell that redefines `.axi-panel`
    instead of using it will drift the first time the panel changes.
-3. No colour literals. No third form step.
+3. No colour literals. No third form step. No theme-only variant — see
+   [Themes](#themes).
 4. Add it to the gallery, and check it with the accent switcher — if it does
    not follow the accent, it hard-coded something.
 5. `npm run build` and commit `dist/axi.css` with your source change.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@axiapps/axi-design",
-  "version": "1.10.0",
+  "version": "1.11.0",
   "description": "The design language for the axi suite — flat and outlined, dark, drawn in saturated ink.",
   "type": "module",
   "license": "MIT",
@@ -17,11 +17,12 @@
   "publishConfig": {
     "access": "public"
   },
-  "//exports": "Two entry points, and both are stylesheets. Consumers import the path rather than the package root because there is no JavaScript here to be a default export - `import '@axiapps/axi-design/axi.css'` says what it does, and a bare `import '@axiapps/axi-design'` resolving to a stylesheet would not. ./tokens.css is the palette without the components, for an app that already draws its own components through its own variables and wants to point them at ours: it is the whole language for a consumer like that, and copying the token block by hand is the one way those values are guaranteed to drift.",
+  "//exports": "Every entry point is a stylesheet. Consumers import the path rather than the package root because there is no JavaScript here to be a default export - `import '@axiapps/axi-design/axi.css'` says what it does, and a bare `import '@axiapps/axi-design'` resolving to a stylesheet would not. ./tokens.css is the palette without the components, for an app that already draws its own components through its own variables and wants to point them at ours: it is the whole language for a consumer like that, and copying the token block by hand is the one way those values are guaranteed to drift. ./themes/*.css is a subpath pattern rather than one entry per theme, so adding a theme is adding themes/<id>.json and nothing else - an entry that has to be remembered is an entry that will be forgotten, and the symptom would be an import that resolves in this repo and not from an install.",
   "exports": {
     "./axi.css": "./dist/axi.css",
     "./tokens.css": "./src/tokens.css",
     "./accents.css": "./dist/accents.css",
+    "./themes/*.css": "./dist/themes/*.css",
     "./accents.json": "./accents.json",
     "./package.json": "./package.json"
   },
@@ -29,19 +30,22 @@
   "sideEffects": [
     "*.css"
   ],
-  "//files": "dist/ is the artifact; src/ and docs/ ride along because RULES.md is the reason any of it is shaped the way it is, and a consumer reading a component wants it next to them. No tests, no gallery. LICENSE and README are included by npm regardless of this list.",
+  "//files": "dist/ is the artifact; src/ rides along because a consumer reading a component wants the source next to them; docs/RULES.md rides along because it is the reason any of it is shaped the way it is. The rest of docs/ - the manifest, the generator and the guides - builds the site and is no use to a consumer. No tests, no gallery. LICENSE and README are included by npm regardless of this list.",
   "files": [
     "dist",
     "src",
-    "docs",
+    "docs/RULES.md",
     "accents.json",
     "README.md"
   ],
   "scripts": {
     "build": "node scripts/build.mjs",
+    "docs": "node scripts/site.mjs",
+    "serve": "node scripts/serve.mjs",
     "test": "vitest run"
   },
   "devDependencies": {
+    "marked": "^18.0.14",
     "vitest": "^2.1.0"
   }
 }

package/src/feedback.css

@@ -0,0 +1,67 @@
+/* axi design language - feedback.
+   Things that report on work, and things that report on how work went. Rule
+   11 governs the first kind and is the one rule in this language described as
+   non-negotiable: an indicator of work may animate only `transform` and
+   `opacity`, because those are the two the compositor runs off the main
+   thread. A spinner animated by layout freezes with the work it reports on,
+   and a frozen spinner tells the reader the app crashed at the exact moment
+   it was working hardest. tests/motion.test.mjs enforces it. */
+
+/* ---------- spinner ---------- */
+/* The family motif, turning. A square rotated 45deg is the diamond, so the
+   loop runs 45deg -> 405deg: one full turn that begins and ends on the
+   motif rather than on a square.
+   That start and end also make it correct under reduced motion for free.
+   base.css only shortens the animation to one .01ms iteration; it never sets
+   animation-fill-mode, so once that instant run finishes the element reverts
+   to its specified transform: rotate(45deg) - the motif at rest, and visually
+   identical to where the loop begins. */
+@keyframes axi-spin { from { transform: rotate(45deg); } to { transform: rotate(405deg); } }
+.axi-spinner {
+  display: inline-block;
+  flex: none;
+  width: var(--axi-spinner-size, 20px);
+  height: var(--axi-spinner-size, 20px);
+  border: var(--axi-border-control) solid var(--axi-accent);
+  border-radius: var(--axi-radius-sm);
+  transform: rotate(45deg);
+  animation: axi-spin 1.1s linear infinite;
+}
+
+/* ---------- indeterminate meter ---------- */
+/* The .axi-meter that does not know how far along it is. The fill keeps a
+   fixed width and travels; `width` is never animated, which is the whole of
+   rule 11. --axi-meter-v is ignored in this mode - there is no value to
+   express, which is what indeterminate means. */
+@keyframes axi-meter-busy {
+  from { transform: translateX(-100%); }
+  to { transform: translateX(400%); }
+}
+.axi-meter--busy .axi-meter__fill {
+  width: 25%;
+  animation: axi-meter-busy 1.3s ease-in-out infinite;
+}
+/* base.css only ever sets animation-duration and animation-iteration-count
+   under reduced motion; it never touches animation-fill-mode. The shorthand
+   above resets animation-fill-mode to its default, none, so once the .01ms
+   run finishes the element reverts to its specified style rather than
+   holding the keyframe it ended on - here that is transform: none and the
+   fill's own width: 25%, a left-anchored quarter-width bar. That is already
+   the right thing to show: visible, and unmistakably not finished. This rule
+   states transform: none explicitly rather than relying on the revert, so
+   the "at rest" case is not accidental. */
+@media (prefers-reduced-motion: reduce) {
+  .axi-meter--busy .axi-meter__fill { transform: none; }
+}
+
+/* ---------- notice status ---------- */
+/* Rule 5: the icon is the part of a notice that asserts something, so the
+   status lives there. The body text stays in the reading ink at every status
+   - a whole paragraph in the danger ink is the tinted-everything failure rule
+   2 exists to prevent, and it is unreadable besides. */
+.axi-notice--ok .axi-notice__icon { background: var(--axi-ok); }
+.axi-notice--warn .axi-notice__icon { background: var(--axi-warn); }
+.axi-notice--danger .axi-notice__icon { background: var(--axi-danger); }
+.axi-notice--ok b { color: var(--axi-ok); }
+.axi-notice--warn b { color: var(--axi-warn); }
+.axi-notice--danger b { color: var(--axi-danger); }

package/src/forms.css

@@ -0,0 +1,89 @@
+/* axi design language - forms.
+   Real inputs, styled. Every control here is an actual <input> or <textarea>
+   with `appearance: none`, never a <div> wearing a class: a checkbox that is
+   not an <input> does not submit with its form, does not toggle from the
+   keyboard, and is not announced as a checkbox. The language styles controls;
+   it does not reimplement them.
+
+   Rule 3's flat case governs the geometry: a control inside a panel is
+   outlined and carries no block, exactly as .axi-input and .axi-switch
+   already are. Rule 5 governs the state: the fill is what says "on".
+
+   The focus ring is deliberately absent from this file. base.css draws one
+   page-wide on :focus-visible, and appearance: none does not remove it - it
+   removes the browser's own. Suppressing the outline anywhere here would make
+   every control in it unusable by keyboard. */
+
+/* ---------- checkbox and radio ---------- */
+/* One box, two marks. --axi-radius is 0, so both are square and a round radio
+   would be the only rounded shape in the language - the first place a flat
+   outlined form starts looking like some other framework's. So they are told
+   apart by their mark instead: the checkbox gets a check, the radio gets the
+   family diamond (rule 7).
+
+   Both read the same two knobs on purpose. A form holding checkboxes and
+   radios together should not need two properties set to the same value to
+   keep its controls the same size. */
+.axi-check,
+.axi-radio {
+  appearance: none;
+  -webkit-appearance: none;
+  margin: 0;
+  flex: none;
+  width: var(--axi-check-size, 22px);
+  height: var(--axi-check-size, 22px);
+  display: inline-grid;
+  place-items: center;
+  background: var(--axi-ground);
+  border: var(--axi-border-control) solid var(--axi-ink-line);
+  border-radius: var(--axi-radius-sm);
+  cursor: pointer;
+}
+/* The mark is always in the DOM and revealed with opacity rather than being
+   created on :checked, so the box never changes size as it toggles. */
+.axi-check::after {
+  content: "";
+  width: 55%;
+  height: 30%;
+  opacity: 0;
+  border-left: var(--axi-border-control) solid var(--axi-accent-ink);
+  border-bottom: var(--axi-border-control) solid var(--axi-accent-ink);
+  transform: translateY(-12%) rotate(-45deg);
+}
+.axi-check:checked { background: var(--axi-check-fill, var(--axi-accent)); }
+.axi-check:checked::after { opacity: 1; }
+/* The radio's mark is the diamond itself, so it is drawn in the fill rather
+   than on it - there is no filled box underneath it to sit on. It takes the
+   hairline outline rule 7's diamond wears at this scale (see the prose
+   bullet, src/prose.css, the other place a diamond this small is drawn) -
+   the mark is revealed with opacity, so the hairline is hidden along with
+   the fill in the unchecked state and never leaks out on its own. */
+.axi-radio::after {
+  content: "";
+  width: 46%;
+  height: 46%;
+  opacity: 0;
+  background: var(--axi-check-fill, var(--axi-accent));
+  border: var(--axi-border-hairline) solid var(--axi-ink-line);
+  transform: rotate(45deg);
+}
+.axi-radio:checked::after { opacity: 1; }
+.axi-check:disabled,
+.axi-radio:disabled { cursor: not-allowed; opacity: .5; }
+
+/* ---------- textarea ---------- */
+/* Not a component: the same .axi-input a single-line field uses, with the two
+   things a <textarea> needs that an <input> does not. The font is restated
+   because a textarea does not inherit the page font in any browser, and a
+   form whose notes field is monospace while its name field is not is a bug
+   nobody files and everybody sees.
+
+   Resizing is vertical only. A textarea dragged wider than its field breaks
+   the column its form is laid out in, and the reader who did it has no way
+   to discover that the layout is not at fault. */
+textarea.axi-input {
+  min-height: var(--axi-textarea-h, 90px);
+  resize: vertical;
+  font-family: var(--axi-sans);
+  line-height: 1.5;
+}

package/src/primitives.css

@@ -10,9 +10,19 @@
    us to ship a component for it. */
 .axi-panel {
   background: var(--axi-surface);
+  /* What the surface does to whatever is behind it. `none` in the main theme,
+     which is inert: unlike a transform, `backdrop-filter: none` establishes no
+     containing block, so rule 4's fixed-descendant trap is not reopened here.
+     A theme that makes the surfaces translucent restates this token and the
+     blur arrives everywhere at once. Carried only by the surfaces something
+     can actually be behind - a panel, a popover, an overlay, the scrim. A
+     chip, a switch, a page number and a card glyph sit directly on their
+     parent's fill with nothing but that fill behind them, so the filter would
+     cost a compositor layer each to blur a flat colour. */
+  backdrop-filter: var(--axi-surface-filter);
   border: var(--axi-border-panel) solid var(--axi-ink-line);
   border-radius: var(--axi-radius);
-  box-shadow: var(--axi-offset-panel) var(--axi-offset-panel) 0 var(--axi-ink-line);
+  box-shadow: var(--axi-shadow-panel);
   /* A panel owns its padding so every consumer doesn't have to invent one;
      override per instance with --axi-panel-pad where a tighter or looser
      fit is genuinely called for. */
@@ -39,13 +49,13 @@
    vision and costs no colour. */
 .axi-btn:hover {
   color: var(--axi-text);
-  box-shadow: var(--axi-offset-control) var(--axi-offset-control) 0 var(--axi-ink-line);
+  box-shadow: var(--axi-shadow-control);
   transform: translate(-2px, -2px);
 }
 .axi-btn--primary {
   background: var(--axi-accent);
   color: var(--axi-accent-ink);
-  box-shadow: var(--axi-offset-control) var(--axi-offset-control) 0 var(--axi-ink-line);
+  box-shadow: var(--axi-shadow-control);
 }
 /* The one button that rests with a block already under it, so the generic
    hover's translate alone would move element and block together and leave the
@@ -53,7 +63,7 @@
    rule 4 warns about. It lifts the way a panel does: the block deepens too. */
 .axi-btn--primary:hover {
   color: var(--axi-accent-ink);
-  box-shadow: var(--axi-offset-control-hover) var(--axi-offset-control-hover) 0 var(--axi-ink-line);
+  box-shadow: var(--axi-shadow-control-hover);
 }
 .axi-btn--ghost { background: transparent; }
 .axi-btn--dashed { background: transparent; border-style: dashed; }
@@ -79,13 +89,13 @@
 }
 .axi-pill:hover {
   color: var(--axi-text);
-  box-shadow: var(--axi-offset-control) var(--axi-offset-control) 0 var(--axi-ink-line);
+  box-shadow: var(--axi-shadow-control);
   transform: translate(-2px, -2px);
 }
 .axi-pill[aria-pressed="true"] {
   background: var(--axi-pill-fill, var(--axi-accent));
   color: var(--axi-accent-ink);
-  box-shadow: var(--axi-offset-control) var(--axi-offset-control) 0 var(--axi-ink-line);
+  box-shadow: var(--axi-shadow-control);
 }
 /* Spelled out rather than left to source order: `.axi-pill:hover` and
    `.axi-pill[aria-pressed="true"]` have identical specificity, so without this
@@ -95,7 +105,7 @@
 .axi-pill[aria-pressed="true"]:hover {
   background: var(--axi-pill-fill, var(--axi-accent));
   color: var(--axi-accent-ink);
-  box-shadow: var(--axi-offset-control-hover) var(--axi-offset-control-hover) 0 var(--axi-ink-line);
+  box-shadow: var(--axi-shadow-control-hover);
   transform: translate(-2px, -2px);
 }
 
@@ -169,9 +179,9 @@
   letter-spacing: var(--axi-ls-micro);
   text-transform: uppercase;
 }
-.axi-chip--ok { background: var(--axi-ok); color: var(--axi-ink-line); }
-.axi-chip--warn { background: var(--axi-warn); color: var(--axi-ink-line); }
-.axi-chip--danger { background: var(--axi-danger); color: var(--axi-ink-line); }
+.axi-chip--ok { background: var(--axi-ok); color: var(--axi-ink-on-fill); }
+.axi-chip--warn { background: var(--axi-warn); color: var(--axi-ink-on-fill); }
+.axi-chip--danger { background: var(--axi-danger); color: var(--axi-ink-on-fill); }
 .axi-chip--accent { background: var(--axi-accent); color: var(--axi-accent-ink); }
 .axi-chip--meta {
   background: transparent;
@@ -267,7 +277,7 @@
 .axi-picker__btn:hover,
 .axi-picker__btn[aria-expanded='true'] {
   color: var(--axi-text);
-  box-shadow: var(--axi-offset-control) var(--axi-offset-control) 0 var(--axi-ink-line);
+  box-shadow: var(--axi-shadow-control);
   transform: translate(-2px, -2px);
 }
 
@@ -288,7 +298,8 @@
     border: var(--axi-border-panel) solid var(--axi-ink-line);
     border-radius: var(--axi-radius);
     background: var(--axi-surface-raised);
-    box-shadow: var(--axi-offset-panel) var(--axi-offset-panel) 0 var(--axi-ink-line);
+    backdrop-filter: var(--axi-surface-filter);
+    box-shadow: var(--axi-shadow-panel);
   }
   .axi-select option {
     display: flex; align-items: center; gap: 9px;
@@ -359,12 +370,13 @@
   max-height: 340px; overflow-y: auto;
   padding: 6px;
   background: var(--axi-surface-raised);
+  backdrop-filter: var(--axi-surface-filter);
   border: var(--axi-border-panel) solid var(--axi-ink-line);
   border-radius: var(--axi-radius);
   /* The block falls outside the popover's own box. An ancestor that clips -
      a scrolling pane, a panel with overflow: hidden - eats it, and the only
      shadow on the screen is the one that goes missing. */
-  box-shadow: var(--axi-offset-panel) var(--axi-offset-panel) 0 var(--axi-ink-line);
+  box-shadow: var(--axi-shadow-panel);
 }
 .axi-picker__pop[hidden] { display: none; }
 /* A popover cannot always live beside its trigger. Inside a pane that scrolls
@@ -405,3 +417,31 @@
 .axi-picker__opt:focus-visible { outline-offset: -3px; }
 .axi-picker__opt[aria-selected='true'] { color: var(--axi-text); }
 .axi-picker__opt[aria-selected='true']::before { color: var(--axi-accent); }
+
+/* ---------- avatar ---------- */
+/* A square, because a circle is the one shape this language does not have:
+   --axi-radius is 0, and a round avatar would be the only rounded thing on
+   the page. It follows the radius scale like everything else, so a consumer
+   who wants round avatars sets --axi-radius-sm and gets rounded controls
+   everywhere - which is the honest version of the request.
+   Flat: outlined, no block. An avatar is content inside a panel, the same as
+   .axi-stat and .axi-table__rank, not a thing raised off it. */
+.axi-avatar {
+  width: var(--axi-avatar-size, 40px);
+  height: var(--axi-avatar-size, 40px);
+  flex: none;
+  display: grid;
+  place-items: center;
+  overflow: hidden;
+  background: var(--axi-ground);
+  color: var(--axi-text-dim);
+  border: var(--axi-border-control) solid var(--axi-ink-line);
+  border-radius: var(--axi-radius-sm);
+  font: var(--axi-t-label);
+  letter-spacing: var(--axi-ls-label);
+  text-transform: uppercase;
+}
+.axi-avatar--accent { background: var(--axi-accent); color: var(--axi-accent-ink); }
+/* object-fit rather than a background-image, so the <img>'s alt text survives
+   and a broken source is visible rather than silently blank. */
+.axi-avatar__img { width: 100%; height: 100%; object-fit: cover; display: block; }

package/src/prose.css

@@ -57,7 +57,7 @@
   background: var(--axi-ground);
   border: var(--axi-border-control) solid var(--axi-ink-line);
   border-radius: var(--axi-radius-sm);
-  box-shadow: var(--axi-offset-control) var(--axi-offset-control) 0 var(--axi-ink-line);
+  box-shadow: var(--axi-shadow-control);
 }
 .axi-prose pre code { background: none; border: 0; padding: 0; font-size: 12.5px; line-height: 1.6; }