@axiapps/axi-design 1.41.0 → 1.42.0

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

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`,
@@ -631,7 +650,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** —

package/package.json

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

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