@axiapps/axi-design 1.11.0 → 1.13.0

package/README.md

@@ -67,13 +67,16 @@ import '@axiapps/axi-design/themes/glass.css'
 <html data-axi-theme="glass">
 ```
 
-`glass` keeps the outline, the hard block and every ink exactly as they are,
-and repaints the surface layer: translucent panels over a colder ground, with
-popovers, drawers and modals blurring what sits behind them. Remove the
-attribute and you are back on the main theme with no other change — a theme
-restates tokens and never adds a component, so nothing in your markup knows
-which one is on. That is the point: the look is maintained here rather than
-copied into your app as a custom theme that then has to be kept in step.
+`glass` repaints the material: translucent panels lit from the top-left over a
+near-black page with three wide colour washes on it, hairline edges, rounded
+corners and a soft drop instead of the main theme's hard offset block, with
+popovers, drawers and modals blurring what sits behind them. The five saturated
+inks, the measure and the type are untouched — they are the language, not the
+paint. Remove the attribute and you are back on the main theme with no other
+change: a theme restates tokens and never adds a component, so nothing in your
+markup knows which one is on. That is the point — the look is maintained here
+rather than copied into your app as a custom theme that then has to be kept in
+step.
 
 The main theme is the language and a theme is a repaint of it — [the
 rules](docs/RULES.md#themes) say what a theme may and may not do.

package/dist/axi.css

@@ -16,9 +16,32 @@
 :root {
   /* --- surface & text --- */
   --axi-ground: #15181d;          /* the page itself */
+  /* An image layer painted over the ground colour, on the page and nowhere
+     else. The second toll the Themes section describes, and it exists for the
+     same reason --axi-surface-filter does: a glass theme wants the page lit
+     from a few directions, and it does not get to introduce a gradient any
+     more than it got to introduce a blur. Declared here inert (`none`), read
+     unconditionally by body, and restated by the theme.
+
+     Why a second token rather than letting a theme put the gradient in
+     --axi-ground itself: --axi-ground is read as `background-color` by the
+     plot and the select, where an image value is invalid and drops out, and
+     as the flat fill of the masthead, the tooltip row and a dozen inset
+     shapes, where a page-positioned radial would render as an arbitrary
+     wedge of colour. The ground stays a colour. This is the page's light. */
+  --axi-ground-image: none;
   --axi-surface: #222731;         /* a panel raised off the page */
   --axi-surface-raised: #2b313d;  /* a chip or popover raised off a panel */
   --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
+     --axi-ink-line today, which is why it reads as the same decision and is
+     not: one is the colour a shape's EDGE is drawn in, the other the colour a
+     shape is FILLED with. They only have to diverge once - a theme that
+     outlines in a light colour so its page can go near-black - for the
+     conflated spelling to turn the tooltip into a pale box. Same split as
+     --axi-ink-on-fill below, on the other side of the same token. */
+  --axi-ground-deep: var(--axi-ink-line);
   --axi-rule: #3a4250;            /* internal rules, inside an outlined panel */
   --axi-text: #f4f6f9;
   --axi-text-dim: #a7b0be;
@@ -134,7 +157,13 @@ html { color-scheme: dark; }
 
 body {
   margin: 0;
-  background: var(--axi-ground);
+  /* Longhands rather than the shorthand: the ground is a colour and the light
+     over it is an image, and `background:` would make setting either one
+     reset the other. Fixed so a theme's light stays put as the page scrolls
+     instead of stretching to the document's height. */
+  background-color: var(--axi-ground);
+  background-image: var(--axi-ground-image);
+  background-attachment: fixed;
   color: var(--axi-text);
   font: var(--axi-t-body);
   -webkit-font-smoothing: antialiased;
@@ -342,7 +371,7 @@ a { color: inherit; }
   top: 2px; bottom: 2px; left: 2px;
   width: var(--axi-switch-knob, 16px);
   border-radius: var(--axi-radius-sm);
-  background: var(--axi-ink-line);
+  background: var(--axi-ground-deep);
   transition: transform .1s;
 }
 /* The travel is the track's inner width less the slug and its two insets.
@@ -922,7 +951,7 @@ textarea.axi-input {
      argument with one. */
   z-index: 70;
   padding: 5px 8px;
-  background: var(--axi-ink-line);
+  background: var(--axi-ground-deep);
   color: var(--axi-text);
   border: var(--axi-border-hairline) solid var(--axi-rule);
   border-radius: var(--axi-radius-sm);
@@ -1071,7 +1100,7 @@ textarea.axi-input {
   flex: none;
   display: flex; align-items: center; gap: 12px;
   height: 38px; padding-left: 14px;
-  background: var(--axi-ink-line);
+  background: var(--axi-ground-deep);
   border-bottom: var(--axi-border-control) solid var(--axi-ink-line);
   font: var(--axi-t-micro);
   letter-spacing: var(--axi-ls-micro);

package/dist/themes/glass.css

@@ -2,10 +2,27 @@
    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%);
+  --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-raised: linear-gradient(145deg, rgba(86, 99, 130, .5), rgba(44, 52, 71, .38));
+  --axi-surface-filter: blur(18px) saturate(140%);
+  --axi-ink-line: rgba(180, 200, 255, .16);
+  --axi-rule: rgba(180, 200, 255, .14);
+  --axi-ground-deep: #0c0e12;
+  --axi-accent-ink: #0c0e12;
+  --axi-ink-on-fill: #0c0e12;
+  --axi-text: #f2f5fb;
+  --axi-text-dim: #b3bdd0;
+  --axi-text-faint: #7f8aa0;
+  --axi-scrim: rgba(4, 6, 12, .66);
+  --axi-shadow-panel: 0 18px 44px rgba(0, 0, 0, .55), inset 0 1px 0 rgba(255, 255, 255, .14);
+  --axi-shadow-control: 0 6px 16px rgba(0, 0, 0, .45), inset 0 1px 0 rgba(255, 255, 255, .12);
+  --axi-shadow-panel-hover: 0 26px 60px rgba(0, 0, 0, .6), inset 0 1px 0 rgba(255, 255, 255, .2);
+  --axi-shadow-control-hover: 0 10px 24px rgba(0, 0, 0, .5), inset 0 1px 0 rgba(255, 255, 255, .18);
+  --axi-border-panel: 1px;
+  --axi-border-control: 1px;
+  --axi-border-hairline: 1px;
+  --axi-radius: 16px;
+  --axi-radius-sm: 10px;
 }

package/docs/RULES.md

@@ -16,10 +16,11 @@ 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 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.
+themselves — and `--axi-ground-image`, the page's own light, which is declared
+inert in `tokens.css` and read only by `body`; see [Themes](#themes). That 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
 
@@ -28,13 +29,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.
+A theme gets the same carve-out as rule 1: it may hold the *surface layer* at
+partial opacity, because a translucent surface is that surface's own definition
+rather than a colour laid over the ground. That layer is the two surfaces and
+the lines that bound and divide them — `--axi-ink-line` and `--axi-rule` — for
+the same reason: the edge of a translucent panel is as much the panel as its
+face, and an opaque hairline around a pane of glass is a picture frame.
+
+The five saturated 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. The neutral text ramp is likewise a theme's to restate but not to
+fade: a theme picks where `--axi-text-dim` sits, it does not write text at 60%.
 
 ## 3. Every raised element is outlined and blocked
 
@@ -62,11 +69,20 @@ 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.
+`.axi-tooltip` is filled with the line ink 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.
+
+It spells that fill `--axi-ground-deep`, not `--axi-ink-line`, and so do the
+two smaller shapes made of the same tone — the titlebar strip and the switch's
+slug. The token holds the line ink today and is a different decision from it:
+one is the colour a shape's edge is drawn in, the other the colour a shape is
+filled with. A theme that outlines in a light colour so its page can go
+near-black relights the first and leaves the second, and the tooltip stays a
+dark box with light words on it instead of becoming a pale box with pale ones.
+Anything else that comes to be made of this tone reads the same token.
 
 **What is mechanically enforced.** `tests/tokens.test.mjs` enforces both
 columns:
@@ -180,7 +196,7 @@ element becomes the containing block for any `position: fixed` descendant.
 An overlay positioned in viewport coordinates — `.axi-tooltip` is the one
 this language ships — must therefore live as a child of `<body>`, never
 inside the component it annotates, or the first hover lift re-anchors it.
-The class draws only the box (ink-line ground, hairline rule border, micro
+The class draws only the box (`--axi-ground-deep` ground, hairline rule border, micro
 type); measuring the trigger and setting `left`/`top` is the consumer's
 half, and `gallery.js` is the reference wiring.
 
@@ -213,7 +229,7 @@ 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
+status and is empty otherwise; the slug that moves is `--axi-ground-deep` in both
 states, so on and off differ in what colour is *in* the slot and never in how
 bright the moving part is. It carries no block — a block belongs to things you
 press, and a switch is a slot with something sitting in it — but it keeps a
@@ -347,8 +363,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-ink-line`, `--axi-rule`, `--axi-text`, `--axi-text-dim`,
-  `--axi-text-faint`, `--axi-scrim`
+  `--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
@@ -465,13 +481,47 @@ 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.
+the language rather than part of the theme. `--axi-ground-image` is the second
+of these, on the same terms: the page's light, inert at `none`, read by `body`
+and nowhere else. 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.
+
+### What a theme may restate
+
+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.
+
+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** —
+`--axi-shadow-*`, `--axi-border-*`, `--axi-radius` and `--axi-radius-sm`. Rule 3
+requires that a raised element read as raised and an outlined one as outlined.
+A hard offset block in the line ink is how the main theme answers that; a soft
+drop with an inset top highlight is a different answer to the same question,
+and a translucent panel wearing an opaque theme's block does not look like
+glass, it looks like a bug. The block and the corner are how a theme says what
+its material is.
+
+What is **not** a theme's to restate, and each for its own reason:
+
+- **The five saturated fills.** `--axi-accent`, `--axi-meta`, `--axi-ok`,
+  `--axi-warn`, `--axi-danger` carry meaning (rules 5, 6, 9, 10). Their `-ink`
+  companions are not on this list: `--axi-accent-ink` and `--axi-ink-on-fill`
+  are the colour a word is written in when it sits on a fill, and a theme that
+  lightens the outline has to be able to hold them dark.
+- **The offset scale.** `--axi-offset-*` is what the main theme's block is
+  composed *from*. A theme restates the composed `--axi-shadow-*` wholesale or
+  leaves it; retuning the offsets underneath would leave the two spellings of
+  "the block" disagreeing.
+- **The measure.** `--axi-page`, `--axi-gutter`. Where the text wraps is not a
+  look, and moving it would reflow every page rather than repaint it.
+- **The type.** `--axi-sans`, `--axi-mono`, `--axi-t-*`, `--axi-ls-*`. The same
+  call, harder: the type scale is the voice.
+
+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.
 
 **What is mechanically enforced.** `tests/themes.test.mjs` reads every
 `dist/themes/*.css` and checks the mirror rather than trusting it: the file

package/package.json

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

package/src/base.css

@@ -11,7 +11,13 @@ html { color-scheme: dark; }
 
 body {
   margin: 0;
-  background: var(--axi-ground);
+  /* Longhands rather than the shorthand: the ground is a colour and the light
+     over it is an image, and `background:` would make setting either one
+     reset the other. Fixed so a theme's light stays put as the page scrolls
+     instead of stretching to the document's height. */
+  background-color: var(--axi-ground);
+  background-image: var(--axi-ground-image);
+  background-attachment: fixed;
   color: var(--axi-text);
   font: var(--axi-t-body);
   -webkit-font-smoothing: antialiased;

package/src/primitives.css

@@ -149,7 +149,7 @@
   top: 2px; bottom: 2px; left: 2px;
   width: var(--axi-switch-knob, 16px);
   border-radius: var(--axi-radius-sm);
-  background: var(--axi-ink-line);
+  background: var(--axi-ground-deep);
   transition: transform .1s;
 }
 /* The travel is the track's inner width less the slug and its two insets.

package/src/shells.css

@@ -140,7 +140,7 @@
      argument with one. */
   z-index: 70;
   padding: 5px 8px;
-  background: var(--axi-ink-line);
+  background: var(--axi-ground-deep);
   color: var(--axi-text);
   border: var(--axi-border-hairline) solid var(--axi-rule);
   border-radius: var(--axi-radius-sm);
@@ -289,7 +289,7 @@
   flex: none;
   display: flex; align-items: center; gap: 12px;
   height: 38px; padding-left: 14px;
-  background: var(--axi-ink-line);
+  background: var(--axi-ground-deep);
   border-bottom: var(--axi-border-control) solid var(--axi-ink-line);
   font: var(--axi-t-micro);
   letter-spacing: var(--axi-ls-micro);

package/src/tokens.css

@@ -12,9 +12,32 @@
 :root {
   /* --- surface & text --- */
   --axi-ground: #15181d;          /* the page itself */
+  /* An image layer painted over the ground colour, on the page and nowhere
+     else. The second toll the Themes section describes, and it exists for the
+     same reason --axi-surface-filter does: a glass theme wants the page lit
+     from a few directions, and it does not get to introduce a gradient any
+     more than it got to introduce a blur. Declared here inert (`none`), read
+     unconditionally by body, and restated by the theme.
+
+     Why a second token rather than letting a theme put the gradient in
+     --axi-ground itself: --axi-ground is read as `background-color` by the
+     plot and the select, where an image value is invalid and drops out, and
+     as the flat fill of the masthead, the tooltip row and a dozen inset
+     shapes, where a page-positioned radial would render as an arbitrary
+     wedge of colour. The ground stays a colour. This is the page's light. */
+  --axi-ground-image: none;
   --axi-surface: #222731;         /* a panel raised off the page */
   --axi-surface-raised: #2b313d;  /* a chip or popover raised off a panel */
   --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
+     --axi-ink-line today, which is why it reads as the same decision and is
+     not: one is the colour a shape's EDGE is drawn in, the other the colour a
+     shape is FILLED with. They only have to diverge once - a theme that
+     outlines in a light colour so its page can go near-black - for the
+     conflated spelling to turn the tooltip into a pale box. Same split as
+     --axi-ink-on-fill below, on the other side of the same token. */
+  --axi-ground-deep: var(--axi-ink-line);
   --axi-rule: #3a4250;            /* internal rules, inside an outlined panel */
   --axi-text: #f4f6f9;
   --axi-text-dim: #a7b0be;