@axiapps/axi-design 1.42.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

@@ -2016,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/docs/RULES.md

@@ -548,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` |
@@ -572,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
@@ -684,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
@@ -693,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.
@@ -702,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.42.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);