@axiapps/axi-design 1.41.0 → 1.43.0

package/accents.json

@@ -9,5 +9,6 @@
   { "id": "crimson-red", "label": "Crimson Red", "hex": "#ef4444" },
   { "id": "slate-silver", "label": "Slate Silver", "hex": "#94a3b8" },
   { "id": "teal-ocean", "label": "Teal Ocean", "hex": "#14b8a6" },
-  { "id": "gold-bronze", "label": "Gold Bronze", "hex": "#d4a017" }
+  { "id": "gold-bronze", "label": "Gold Bronze", "hex": "#d4a017" },
+  { "id": "electric-cyan", "label": "Electric Cyan", "hex": "#22d3ee" }
 ]

package/dist/accents.css

@@ -12,3 +12,4 @@
 [data-axi-accent="slate-silver"] { --axi-accent: #94a3b8; }
 [data-axi-accent="teal-ocean"] { --axi-accent: #14b8a6; }
 [data-axi-accent="gold-bronze"] { --axi-accent: #d4a017; }
+[data-axi-accent="electric-cyan"] { --axi-accent: #22d3ee; }

package/dist/axi.css

@@ -54,6 +54,63 @@
      own token, and a theme that goes translucent restates it near-opaque
      without giving up the tint on everything that merely sits still. */
   --axi-surface-float: var(--axi-surface);
+  /* --- a surface as a single paint --- */
+  /* The three surface tokens above, each reduced to one flat <color>.
+
+     They exist because a surface token is allowed to hold a gradient - rule 1's
+     one relief, which is how a glass theme exists at all - and a token holding
+     a gradient can only ever BE a background. `fill` takes <paint> and not
+     <image>. `color-mix()` takes colours and nothing else. `background-color`
+     and `border-color` take a colour. So every consumer that wanted a
+     surface-coloured chart fill, or a surface mixed some way toward the accent,
+     had nothing in this language to ask for.
+
+     Nothing in this package noticed, because every component here paints a
+     surface through the `background` shorthand, where an image is welcome. The
+     cost landed downstream, and the way it lands is silent: an invalid `fill`
+     is dropped at computed-value time, and `fill` inherits, so the element
+     adopts its ancestor's paint rather than showing anything wrong. Measured in
+     axibridge under the flat theme - a chart's brush slide and its bar cursor
+     both computed rgb(0, 0, 0), and a heat ramp built on color-mix() lost its
+     fill altogether. The app had papered over the glass half by pinning two
+     flat values of its own by eye, and had no way to paper over flat.
+
+     Why a companion rather than splitting each surface into a colour and an
+     `-image` half, the way --axi-ground is split. That was tried first and
+     measured. It works for the ground because the ground is OPAQUE: the colour
+     is the page and the image is light added over it. It does not transfer to a
+     translucent surface, where the gradient is not light on a fill, it IS the
+     fill - alpha and all. Painting a glass panel as an absolute gradient over a
+     flat base composites the two and takes the panel from .55 to .77 opacity,
+     which is 15 RGB steps of visible change. Fitting a base and a modulation
+     that reproduce the original to within 2 steps is possible, and the fit
+     lands on rgba(28, 41, 65, .361) - a set of constants no one can maintain,
+     carrying an alpha .12 below the surface it is meant to be a reduction of,
+     which would make a chart fill read as a different material from the panel
+     beside it. A translucent surface genuinely is an image, and "that surface
+     as one flat paint" is genuinely a second thing derived from it.
+
+     What the value has to be is not a judgement each theme makes fresh: it is
+     the midpoint of that theme's gradient, the colour the gradient is a spread
+     around. Both shipped themes confirm it independently - flat's two midpoints
+     come out at exactly the #1a1f2e and #222838 its own notes call "axibridge's
+     flat values", and glass's two land within three per channel, at an
+     identical alpha, of the pair axibridge had already pinned by eye. The
+     colour was always there; it was never a token.
+
+     Aliased here because the main theme's surfaces are flat colours already, so
+     there is nothing to reduce. A theme that puts an image in a surface token
+     must restate that token's companion, or the alias hands the image straight
+     back - themes.test.mjs asserts exactly that, and it is the only way this
+     token can go wrong. Note the float's companion follows --axi-surface-paint
+     and NOT --axi-surface-float: the float's own default is var(--axi-surface),
+     so aliasing the float would walk the chain back into a theme's gradient in
+     any theme that restates the surface and leaves the float alone - which is
+     what flat does. */
+  --axi-surface-paint: var(--axi-surface);
+  --axi-surface-raised-paint: var(--axi-surface-raised);
+  --axi-surface-float-paint: var(--axi-surface-paint);
+
   --axi-ink-line: #0c0e12;        /* the outline every raised element is drawn with */
   /* The tone a shape is made of when it is made of the line ink rather than
      outlined in it - the tooltip, the titlebar strip, the switch's slug. Holds
@@ -1959,7 +2016,44 @@ textarea.axi-input {
 .axi-card:hover .axi-card__go { color: var(--axi-text); }
 
 /* ---------- drawer ---------- */
+/* A scrim's layer is not a property of the scrim. It is "directly below the
+   thing I dismiss", and this language has two things that get dismissed at two
+   different rungs, so the scrim has two.
+
+   The default is the drawer-and-modal rung at 50, which is where
+   --axi-scrim's own value was tuned (its token comment reads "behind a
+   drawer"). `.axi-scrim--sheet` is the same scrim one rung below the sheet at
+   45.
+
+   Without that modifier a sheet cannot be scrimmed at all, and the failure is
+   not cosmetic - it is a dead interface. Both elements are `position: fixed` in
+   the same stacking context with no isolation between them, so at 50 over 45
+   the scrim covers the sheet completely: measured with
+   `document.elementFromPoint` at the centre of an open sheet, the element
+   returned is the scrim. Every click lands on the dismiss handler instead of on
+   the content, so the sheet opens and then does nothing.
+
+   The sheet still wants a scrim even though it is opaque and covers the view,
+   for two reasons the sheet's own note explains. --axi-sheet-top pushes it down
+   under an app's titlebar, so a strip of live page stays visible above it and
+   wants darkening; and the scrim is the click-to-dismiss target for that strip,
+   which is a function rather than an appearance.
+
+   A sheet that opens a modal or a drawer is unaffected: those land at 50 and
+   51, above both the sheet and its scrim, which is the ordering the sheet's own
+   comment argues for. That is why this is a second rung and not a change to the
+   first - moving the scrim below 45 outright would put it under the drawer it
+   was measured for.
+
+   No motion here, deliberately. This language has no transition vocabulary -
+   no duration or easing tokens - and rule 11 is a restriction on work
+   indicators rather than a system for animating chrome. A consumer that fades
+   a scrim in owns that animation, and owns keeping its keyframes off the fill:
+   an enter/exit class that also sets a background is a colour literal standing
+   on top of --axi-scrim, which is how the one consumer here had quietly
+   replaced the token with rgba(10, 14, 18, .85). */
 .axi-scrim { position: fixed; inset: 0; z-index: 50; background: var(--axi-scrim); backdrop-filter: var(--axi-surface-filter); border: 0; }
+.axi-scrim--sheet { z-index: 44; }
 .axi-drawer {
   position: fixed; top: 0; right: 0; bottom: 0; z-index: 51;
   width: min(var(--axi-drawer-width, 560px), 100vw);

package/dist/themes/flat.css

@@ -4,7 +4,9 @@
 [data-axi-theme="flat"] {
   --axi-ground: #090b10;
   --axi-surface: linear-gradient(#1c2130, #181d2c);
+  --axi-surface-paint: #1a1f2e;
   --axi-surface-raised: linear-gradient(#242a3b, #202636);
+  --axi-surface-raised-paint: #222838;
   --axi-well-fill: #141822;
   --axi-ink-line: rgba(255, 255, 255, .10);
   --axi-rule: rgba(255, 255, 255, .07);

package/dist/themes/glass.css

@@ -5,8 +5,11 @@
   --axi-ground: #0a0c10;
   --axi-ground-image: radial-gradient(900px 500px at 15% 0%, rgba(120, 90, 255, .30), transparent 60%), radial-gradient(700px 500px at 95% 30%, rgba(0, 190, 255, .22), transparent 62%), radial-gradient(600px 600px at 60% 100%, rgba(255, 90, 170, .20), transparent 60%);
   --axi-surface: linear-gradient(145deg, rgba(58, 68, 92, .55), rgba(28, 33, 46, .42));
+  --axi-surface-paint: rgba(43, 50, 69, .485);
   --axi-surface-raised: linear-gradient(145deg, rgba(86, 99, 130, .5), rgba(44, 52, 71, .38));
+  --axi-surface-raised-paint: rgba(65, 76, 100, .44);
   --axi-surface-float: linear-gradient(145deg, rgba(38, 45, 62, .97), rgba(22, 26, 36, .97));
+  --axi-surface-float-paint: rgba(30, 36, 49, .97);
   --axi-surface-filter: blur(18px) saturate(140%);
   --axi-ink-line: rgba(180, 200, 255, .16);
   --axi-rule: rgba(180, 200, 255, .14);

package/docs/RULES.md

@@ -22,6 +22,23 @@ 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.
 
+That relief has a consequence worth stating next to it, because it is not
+visible from inside this package. A surface token that may hold a gradient can
+only ever *be* a background: `fill` takes `<paint>` and not `<image>`,
+`color-mix()` takes colours only, `background-color` and `border-color` take a
+colour. Every component here paints a surface through the `background`
+shorthand and so never meets this — but a consumer wanting a surface-coloured
+chart fill, or a surface mixed some way toward the accent, has nothing to ask
+for, and the failure is silent: an invalid `fill` drops at computed-value time
+and `fill` inherits, so the element takes its ancestor's paint and renders
+something plausible. So each surface has a **`-paint` companion** —
+`--axi-surface-paint`, `--axi-surface-raised-paint`,
+`--axi-surface-float-paint` — holding the same surface as one flat `<color>`.
+Paint a surface with the surface token; reach for the companion wherever only a
+colour is valid. A theme that grades a surface must restate that surface's
+companion, and `themes.test.mjs` asserts it: the companions are aliased to the
+surfaces, so a theme that forgets one hands its gradient straight back.
+
 ## 2. No colour at partial opacity over the ground
 
 If a colour is present it is at full strength. A muted gold over near-black is
@@ -490,6 +507,8 @@ Three layers, in `src/tokens.css` — the only file permitted to contain a colou
 literal.
 
 - **Surface & text** — `--axi-ground`, `--axi-surface`, `--axi-surface-raised`,
+  `--axi-surface-float`, their three `-paint` companions (the same surfaces as a
+  single `<color>`, for `fill`, `color-mix()` and the `*-color` properties),
   `--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`,
@@ -529,6 +548,7 @@ instead of joining it.
 | Table corner | 3 | where the two cross |
 | Sticky chrome | 40 | `.axi-mast` |
 | Popovers | 41 | `.axi-menu__pop`, `.axi-picker__pop` |
+| Sheet scrim | 44 | `.axi-scrim--sheet` |
 | Sheet | 45 | `.axi-sheet` |
 | Scrim | 50 | `.axi-scrim` |
 | Drawer | 51 | `.axi-drawer` |
@@ -553,6 +573,15 @@ A negative `z-index` inside a component's own `isolation` context — the sigil'
 backing shape — is not a layer and is not listed. It is invisible outside the
 component that owns it.
 
+The scrim appears twice, and that is the table saying something rather than
+repeating itself. A scrim's rung is not a property of the scrim; it is "directly
+below the thing I dismiss", so a language with two dismissible surfaces at two
+rungs has two scrims. Reading the single 50 as the scrim's own number is what
+makes a sheet impossible to scrim: at 50 over the sheet's 45 the scrim covers
+the sheet completely, every click lands on the dismiss handler, and the surface
+opens dead. So when you add a dismissible surface, check whether it needs a
+scrim rung directly beneath it, and add both rows together.
+
 ## Light mode
 
 Not shipped. The system is *structured* for it: no component contains a colour
@@ -631,7 +660,9 @@ first step back toward theme-only components.
 
 Rules 1 and 2 name the relief a theme gets in 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.
+may not mute an ink. Read those two rules for why. A theme taking the gradient
+half of that relief owes the `-paint` companion of every surface it grades —
+see rule 1.
 
 The relief is not confined to that layer, though, and the first draft of this
 section said it was. **A theme may also restate the block and the corner** —
@@ -663,6 +694,44 @@ The line to hold is the one-for-one rule above, not a list of layers. A theme
 that restates the block still paints every component; a theme that invents one
 does not.
 
+### A change to the language is not finished until every theme wears it
+
+The one-for-one rule above is written as an obligation on a *theme* — here is
+what a new theme owes the language. Read only that way it has a hole in it, and
+the hole is every change that goes the other direction. A token added to
+`tokens.css`, a component added to `src/`, a look retuned: each of those is a
+change to the thing the themes are mirroring, and none of them is finished when
+the main theme looks right. There are three themes — the language itself in
+`src/tokens.css`, `flat`, and `glass` — and a change lands in all three or it
+has not landed.
+
+That is the symmetric half of the toll already stated above. **A new theme
+capability costs a main-theme token first; a change to the main theme costs
+every theme a look.** Neither direction is optional, and the second is the one
+easy to skip, because the default theme is the one on screen while you work.
+
+What "answered in every theme" means depends on the shape of the change:
+
+- **A new token.** Every theme either restates it or can point at why it does
+  not need to. Two reasons count. The default is inert — `--axi-surface-filter`
+  and `--axi-ground-image` are `none`, so a theme that wants neither is already
+  correct. Or the token aliases one the theme did restate —
+  `--axi-surface-float: var(--axi-surface)`, so `flat` restating the surface
+  restates the float with it. A token holding a literal of its own is answered
+  by neither of those, and every theme has to say it. This is checked; see
+  below.
+- **A new component.** It renders under all three, and you look at it under all
+  three. The gallery's theme switcher is there for exactly the reason the accent
+  switcher is: a component that hard-coded something looks fine until you
+  change the thing it hard-coded. A panel that reads as a panel on opaque slate
+  can vanish on a translucent one.
+- **A retuned look.** The `-paint` companions are the case that made this a
+  section. Lifting them meant every surface a theme grades needs a flat
+  companion beside it, and both themes had to be edited in the same commit as
+  the tokens — edit one and the other hands a gradient straight to
+  `background-color`, which is not a subtle failure but it is an invisible one
+  from the theme you happened to be looking at.
+
 **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
@@ -672,6 +741,16 @@ non-empty value, and every property it declares is already declared in
 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.
 
+The section above is checked from the other side by the same file: a token that
+*any* theme restates must be restated by *every* theme, unless that theme
+inherits an answer already — the main-theme default is inert, or the token
+aliases another the theme did restate, and the check follows the alias chain
+rather than taking the two reasons on trust. So a token one theme has an opinion
+about cannot be a token another theme forgot. What no test can check is the
+third bullet, the look you did not look at: a component can paint under all
+three themes and still be wrong under two of them, and the only instrument for
+that is the theme switcher in the gallery.
+
 ## Adding a component
 
 1. Which rule justifies it? If none, write the rule first or stop.
@@ -681,7 +760,11 @@ vacuously while no theme exists, and binds the moment the first file lands.
    [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.
+5. Then check it with the theme switcher, under all three — the language,
+   `flat` and `glass`. Translucent surfaces and a 16px corner break different
+   things than opaque ones do, and a component is not done until it reads right
+   under each. See [Themes](#themes).
+6. `npm run build` and commit `dist/axi.css` with your source change.
 
 ### A style only reachable through a layer will be re-invented
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@axiapps/axi-design",
-  "version": "1.41.0",
+  "version": "1.43.0",
   "description": "The design language for the axi suite — flat and outlined, dark, drawn in saturated ink.",
   "type": "module",
   "license": "MIT",

package/src/shells.css

@@ -708,7 +708,44 @@
 .axi-card:hover .axi-card__go { color: var(--axi-text); }
 
 /* ---------- drawer ---------- */
+/* A scrim's layer is not a property of the scrim. It is "directly below the
+   thing I dismiss", and this language has two things that get dismissed at two
+   different rungs, so the scrim has two.
+
+   The default is the drawer-and-modal rung at 50, which is where
+   --axi-scrim's own value was tuned (its token comment reads "behind a
+   drawer"). `.axi-scrim--sheet` is the same scrim one rung below the sheet at
+   45.
+
+   Without that modifier a sheet cannot be scrimmed at all, and the failure is
+   not cosmetic - it is a dead interface. Both elements are `position: fixed` in
+   the same stacking context with no isolation between them, so at 50 over 45
+   the scrim covers the sheet completely: measured with
+   `document.elementFromPoint` at the centre of an open sheet, the element
+   returned is the scrim. Every click lands on the dismiss handler instead of on
+   the content, so the sheet opens and then does nothing.
+
+   The sheet still wants a scrim even though it is opaque and covers the view,
+   for two reasons the sheet's own note explains. --axi-sheet-top pushes it down
+   under an app's titlebar, so a strip of live page stays visible above it and
+   wants darkening; and the scrim is the click-to-dismiss target for that strip,
+   which is a function rather than an appearance.
+
+   A sheet that opens a modal or a drawer is unaffected: those land at 50 and
+   51, above both the sheet and its scrim, which is the ordering the sheet's own
+   comment argues for. That is why this is a second rung and not a change to the
+   first - moving the scrim below 45 outright would put it under the drawer it
+   was measured for.
+
+   No motion here, deliberately. This language has no transition vocabulary -
+   no duration or easing tokens - and rule 11 is a restriction on work
+   indicators rather than a system for animating chrome. A consumer that fades
+   a scrim in owns that animation, and owns keeping its keyframes off the fill:
+   an enter/exit class that also sets a background is a colour literal standing
+   on top of --axi-scrim, which is how the one consumer here had quietly
+   replaced the token with rgba(10, 14, 18, .85). */
 .axi-scrim { position: fixed; inset: 0; z-index: 50; background: var(--axi-scrim); backdrop-filter: var(--axi-surface-filter); border: 0; }
+.axi-scrim--sheet { z-index: 44; }
 .axi-drawer {
   position: fixed; top: 0; right: 0; bottom: 0; z-index: 51;
   width: min(var(--axi-drawer-width, 560px), 100vw);

package/src/tokens.css

@@ -50,6 +50,63 @@
      own token, and a theme that goes translucent restates it near-opaque
      without giving up the tint on everything that merely sits still. */
   --axi-surface-float: var(--axi-surface);
+  /* --- a surface as a single paint --- */
+  /* The three surface tokens above, each reduced to one flat <color>.
+
+     They exist because a surface token is allowed to hold a gradient - rule 1's
+     one relief, which is how a glass theme exists at all - and a token holding
+     a gradient can only ever BE a background. `fill` takes <paint> and not
+     <image>. `color-mix()` takes colours and nothing else. `background-color`
+     and `border-color` take a colour. So every consumer that wanted a
+     surface-coloured chart fill, or a surface mixed some way toward the accent,
+     had nothing in this language to ask for.
+
+     Nothing in this package noticed, because every component here paints a
+     surface through the `background` shorthand, where an image is welcome. The
+     cost landed downstream, and the way it lands is silent: an invalid `fill`
+     is dropped at computed-value time, and `fill` inherits, so the element
+     adopts its ancestor's paint rather than showing anything wrong. Measured in
+     axibridge under the flat theme - a chart's brush slide and its bar cursor
+     both computed rgb(0, 0, 0), and a heat ramp built on color-mix() lost its
+     fill altogether. The app had papered over the glass half by pinning two
+     flat values of its own by eye, and had no way to paper over flat.
+
+     Why a companion rather than splitting each surface into a colour and an
+     `-image` half, the way --axi-ground is split. That was tried first and
+     measured. It works for the ground because the ground is OPAQUE: the colour
+     is the page and the image is light added over it. It does not transfer to a
+     translucent surface, where the gradient is not light on a fill, it IS the
+     fill - alpha and all. Painting a glass panel as an absolute gradient over a
+     flat base composites the two and takes the panel from .55 to .77 opacity,
+     which is 15 RGB steps of visible change. Fitting a base and a modulation
+     that reproduce the original to within 2 steps is possible, and the fit
+     lands on rgba(28, 41, 65, .361) - a set of constants no one can maintain,
+     carrying an alpha .12 below the surface it is meant to be a reduction of,
+     which would make a chart fill read as a different material from the panel
+     beside it. A translucent surface genuinely is an image, and "that surface
+     as one flat paint" is genuinely a second thing derived from it.
+
+     What the value has to be is not a judgement each theme makes fresh: it is
+     the midpoint of that theme's gradient, the colour the gradient is a spread
+     around. Both shipped themes confirm it independently - flat's two midpoints
+     come out at exactly the #1a1f2e and #222838 its own notes call "axibridge's
+     flat values", and glass's two land within three per channel, at an
+     identical alpha, of the pair axibridge had already pinned by eye. The
+     colour was always there; it was never a token.
+
+     Aliased here because the main theme's surfaces are flat colours already, so
+     there is nothing to reduce. A theme that puts an image in a surface token
+     must restate that token's companion, or the alias hands the image straight
+     back - themes.test.mjs asserts exactly that, and it is the only way this
+     token can go wrong. Note the float's companion follows --axi-surface-paint
+     and NOT --axi-surface-float: the float's own default is var(--axi-surface),
+     so aliasing the float would walk the chain back into a theme's gradient in
+     any theme that restates the surface and leaves the float alone - which is
+     what flat does. */
+  --axi-surface-paint: var(--axi-surface);
+  --axi-surface-raised-paint: var(--axi-surface-raised);
+  --axi-surface-float-paint: var(--axi-surface-paint);
+
   --axi-ink-line: #0c0e12;        /* the outline every raised element is drawn with */
   /* The tone a shape is made of when it is made of the line ink rather than
      outlined in it - the tooltip, the titlebar strip, the switch's slug. Holds