@axiapps/axi-design 1.12.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,6 +16,20 @@
 :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 */
@@ -143,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;

package/dist/themes/glass.css

@@ -3,13 +3,26 @@
 
 [data-axi-theme="glass"] {
   --axi-ground: #0a0c10;
-  --axi-surface: rgba(255, 255, 255, .09);
-  --axi-surface-raised: rgba(255, 255, 255, .15);
-  --axi-ink-line: #242b38;
+  --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-rule: rgba(255, 255, 255, .17);
-  --axi-scrim: rgba(6, 7, 9, .55);
-  --axi-surface-filter: blur(14px) saturate(140%);
+  --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
 
@@ -474,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.12.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/tokens.css

@@ -12,6 +12,20 @@
 :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 */