@axiapps/axi-design 1.21.0 → 1.23.0

package/README.md

@@ -139,6 +139,7 @@ not "what does the system look like". Everything else is
 | `--axi-check-fill` | the fill a checked `.axi-check` takes, and the colour of a checked `.axi-radio`'s diamond | `var(--axi-accent)` | `<input type="checkbox" class="axi-check" style="--axi-check-fill: var(--axi-danger)">` |
 | `--axi-textarea-h` | the minimum height of a `<textarea class="axi-input">` | `90px` | `<textarea class="axi-input" style="--axi-textarea-h: 200px">` |
 | `--axi-well-pad` | the padding inside an `.axi-well` | `10px` | `<div class="axi-well" style="--axi-well-pad: 18px">` |
+| `--axi-well-radius` | an `.axi-well`'s corner radius, for a well used at reading scale rather than page scale | `var(--axi-radius)` | `<div class="axi-well" style="--axi-well-radius: var(--axi-radius-sm)">` |
 | `--axi-rail-w` | an `.axi-rail`'s width, for labels longer than the default holds | `208px` | `<aside class="axi-rail" style="--axi-rail-w: 260px">` |
 | `--axi-rail-pad` | the padding inside an `.axi-rail` | `10px` | `<aside class="axi-rail" style="--axi-rail-pad: 6px">` |
 | `--axi-avatar-size` | the size of an `.axi-avatar` square | `40px` | `<span class="axi-avatar" style="--axi-avatar-size: 28px">MS</span>` |

package/dist/axi.css

@@ -304,6 +304,36 @@ a { color: inherit; }
    on the other surface that needs it. */
 .axi-panel--float { background: var(--axi-surface-float); }
 
+/* A panel that stands in a grid of its own kind rather than alone on the page.
+   Same surface, one form step down: the control border and the control block,
+   so a row of six tiles does not read as six page regions arguing with the
+   page that holds them.
+
+   This is the form ramp doing work a hue would otherwise be asked to do. A
+   tile beside a tile is level; a tile beside a plain .axi-panel is outranked -
+   which is how a grid of readings says "this one is first" without spending
+   the accent on it, and the accent is not available for that anyway (it means
+   the thing you picked, and nobody picks a winner, the data does).
+
+   Padding reads the panel's own knob so a consumer overriding --axi-panel-pad
+   does not have to know which of the two it is looking at, at the tighter
+   figure a tile wants. */
+.axi-panel--tile {
+  border-width: var(--axi-border-control);
+  box-shadow: var(--axi-shadow-control);
+  padding: var(--axi-panel-pad, 12px);
+}
+/* A tile you can press moves under the press, the way every other control in
+   the language does. Keyed off what the tile already is rather than a second
+   class: a tile that is a button, a link, or a div wearing the button role has
+   said so once, and should not have to say it again for the shadow. The role
+   selector is there because it is what a pressable div in real markup actually
+   carries - the alternative is a consumer with a keyboard handler and no
+   hover, which is the worse half of the bargain. */
+a.axi-panel--tile:hover,
+button.axi-panel--tile:hover,
+.axi-panel--tile[role='button']:hover { box-shadow: var(--axi-shadow-control-hover); }
+
 /* ---------- well ---------- */
 /* The panel's inverse: a field sunk into the surface around it rather than
    raised off it. No block, because a recess casts nothing, and the rule rather
@@ -314,7 +344,13 @@ a { color: inherit; }
 .axi-well {
   background: var(--axi-well-fill);
   border: var(--axi-border-control) solid var(--axi-well-line);
-  border-radius: var(--axi-radius);
+  /* A knob rather than a fixed radius, unlike the panel's, because a well is
+     the one form in the language that is used at two scales: a field the size
+     of a page column, and a recess the size of a single reading. At reading
+     scale the large radius is the wrong one - it is the radius everything else
+     that small already declines - so those instances say --axi-radius-sm here
+     rather than reaching for a modifier or a second class. */
+  border-radius: var(--axi-well-radius, var(--axi-radius));
   /* Tighter than a panel's 26px: a well is a container for objects that carry
      their own padding, not a page margin. */
   padding: var(--axi-well-pad, 10px);
@@ -1183,7 +1219,11 @@ textarea.axi-input {
   font-size: 14px; font-weight: 900;
   border: var(--axi-border-control) solid var(--axi-ink-line);
 }
-.axi-notice p { margin: 0; font: var(--axi-t-small); color: var(--axi-text-dim); }
+/* :where() around the element, here and on the card's and the quote's copy,
+   for the reason spelled out over `.axi-table :where(thead th)` in data.css: a
+   slot that holds a consumer's words must not out-rank the ink the consumer
+   puts on them. */
+.axi-notice :where(p) { margin: 0; font: var(--axi-t-small); color: var(--axi-text-dim); }
 .axi-notice b { color: var(--axi-accent); font-weight: 800; }
 
 /* ---------- toolbar ---------- */
@@ -1452,7 +1492,7 @@ textarea.axi-input {
   color: var(--axi-text-faint);
   letter-spacing: .08em; text-transform: uppercase;
 }
-.axi-card p { margin: 0; font: var(--axi-t-small); color: var(--axi-text-dim); }
+.axi-card :where(p) { margin: 0; font: var(--axi-t-small); color: var(--axi-text-dim); }
 /* Pushed to the bottom so that in an equalised grid row every card's meta
    strip lands on the same line and the rules read as continuous across the
    grid. The cost is empty space on cards with less content. */
@@ -1515,7 +1555,7 @@ textarea.axi-input {
   background: var(--axi-ground);
   border-radius: 0 var(--axi-radius-sm) var(--axi-radius-sm) 0;
 }
-.axi-quote p { margin: 0; font-size: 13px; font-style: italic; color: var(--axi-text-dim); line-height: 1.5; }
+.axi-quote :where(p) { margin: 0; font-size: 13px; font-style: italic; color: var(--axi-text-dim); line-height: 1.5; }
 .axi-quote cite {
   display: block; margin-top: 7px;
   font-style: normal; font-size: 11.5px; font-weight: 700;
@@ -1845,8 +1885,14 @@ textarea.axi-input {
 /* `thead th`, not `th`. A row's name is a `<th scope="row">` - that is what
    tells a screen reader which cell labels the row - and it is a name, not a
    column heading: uppercase micro type down the first column would shout every
-   row's label at the reader. A row header takes the cell treatment below. */
-.axi-table thead th {
+   row's label at the reader. A row header takes the cell treatment below.
+
+   The element part is wrapped in :where() so this rule weighs one class, not a
+   class and a type. A base rule that out-ranks the component's own modifiers is
+   a base rule nothing can correct: at (0,1,1) this beat `.axi-table__num` and
+   every ink class a consumer could put on a cell, so the column that carries
+   the measured value was silently still the dim one. */
+.axi-table :where(thead th) {
   padding: 0 10px 10px;
   font: var(--axi-t-micro);
   letter-spacing: var(--axi-ls-micro);
@@ -1854,8 +1900,7 @@ textarea.axi-input {
   color: var(--axi-text-faint);
   border-bottom: var(--axi-border-control) solid var(--axi-rule);
 }
-.axi-table td,
-.axi-table tbody th {
+.axi-table :where(td, tbody th) {
   padding: 9px 10px;
   font: var(--axi-t-small);
   font-weight: 700;
@@ -2311,3 +2356,59 @@ textarea.axi-input {
 }
 
 .axi-prose img { max-width: 100%; height: auto; border-radius: var(--axi-radius-sm); }
+
+/* --- utilities.css --- */
+/* axi design language - utilities.
+   Two families of single-purpose class, and the file is last in the cascade
+   because that is the whole point of it: a utility has to be able to overrule
+   the component it sits inside, and it is not allowed to buy that with
+   !important or with a padded selector.
+
+   Why the language needs them at all. Rules 5 and 6 draw a distinction the
+   reader is expected to make at a glance - a filled status against a cool ink
+   that is commentary - and until now the only way to say either was to be a
+   component that said it for you. Real markup is full of places that are not
+   components: a number in a sentence, a word in a legend, a value beside a
+   label. An app with no way to say "this reading is bad" in those places will
+   reach for a colour literal, and at that moment the theme stops reaching it.
+   So the language names the meanings, and the app spends them by name.
+
+   What they deliberately are not. An ink sets colour and nothing else - no
+   size, no weight, no spacing, no surface - and an edge sets border-colour
+   without asserting that there is a border. Neither is a shorthand for a
+   component: a status that belongs to a whole object still wants the chip or
+   the cap that rule 5 describes, because an object's verdict should be a shape
+   the eye finds, not a recoloured word inside it. These are for the marks
+   inside those shapes.
+
+   And there is no fill family. Under rule 2 colour at partial opacity over the
+   ground is not available, and an opaque status fill behind arbitrary text is a
+   chip - which the language already ships. A surface stays a surface token. */
+
+/* The five meanings. Ordered as rule 5 orders them: the three statuses, then
+   the cool ink that is not a status, then the accent - which means "the thing
+   you picked" and never "good". */
+.axi-ink-ok { color: var(--axi-ok); }
+.axi-ink-warn { color: var(--axi-warn); }
+.axi-ink-danger { color: var(--axi-danger); }
+.axi-ink-meta { color: var(--axi-meta); }
+.axi-ink-accent { color: var(--axi-accent); }
+
+/* The three neutral steps. `plain` rather than `text` so that reading the class
+   list does not suggest it does something to the text other than ink it, and so
+   the three read as one scale. */
+.axi-ink-plain { color: var(--axi-text); }
+.axi-ink-dim { color: var(--axi-text-dim); }
+.axi-ink-faint { color: var(--axi-text-faint); }
+
+/* Edges. `rule` and `line` are the two neutral weights of meaning, not of
+   width: --axi-rule is the quiet separator inside a surface, --axi-ink-line the
+   full ink a raised thing is outlined in. Width stays with whoever drew the
+   border. */
+.axi-edge-ok { border-color: var(--axi-ok); }
+.axi-edge-warn { border-color: var(--axi-warn); }
+.axi-edge-danger { border-color: var(--axi-danger); }
+.axi-edge-meta { border-color: var(--axi-meta); }
+.axi-edge-accent { border-color: var(--axi-accent); }
+.axi-edge-rule { border-color: var(--axi-rule); }
+.axi-edge-line { border-color: var(--axi-ink-line); }

package/docs/RULES.md

@@ -243,6 +243,30 @@ see is a slug floating in the card.
 meaning. It is the only ink guaranteed not to mean "how bad is this" — which is
 what makes it readable as commentary at a glance.
 
+### Saying a meaning outside a component
+
+Rules 5 and 6 are about marks, not only about components. A number inside a
+sentence, a word in a legend, a value beside its label — each of these can be a
+status or can be commentary, and a reader is entitled to see which. So the five
+meanings are available as inks: `.axi-ink-ok`, `.axi-ink-warn`,
+`.axi-ink-danger`, `.axi-ink-meta`, `.axi-ink-accent`, with the three neutral
+steps as `.axi-ink-plain`, `.axi-ink-dim` and `.axi-ink-faint`, and the same
+list again as `.axi-edge-*` for a border's colour.
+
+An ink colours a mark. It is not a way to skip the chip or the status cap, which
+are what rule 5 asks for when the verdict belongs to a whole object: a shape the
+eye finds beats a recoloured word inside a paragraph. Reach for an ink when
+there is no object, only a mark.
+
+They live in `src/utilities.css`, last in the cascade, which is how a single
+class overrules the component it sits inside without `!important`. That places
+an obligation on components in the other direction: **a component's base rules
+may not out-rank its own modifiers.** A rule written `.axi-table td` weighs a
+class and a type, so it silently defeats both `.axi-table__num` and any ink a
+consumer puts on the cell — the fix is `:where()` around the element, which
+spends no specificity. Where a component holds a consumer's content, wrap the
+element part.
+
 ## 7. The diamond is the family motif
 
 A 45°-rotated outlined square. Bullet, status dot, language marker, and scaled

package/package.json

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

package/src/data.css

@@ -67,8 +67,14 @@
 /* `thead th`, not `th`. A row's name is a `<th scope="row">` - that is what
    tells a screen reader which cell labels the row - and it is a name, not a
    column heading: uppercase micro type down the first column would shout every
-   row's label at the reader. A row header takes the cell treatment below. */
-.axi-table thead th {
+   row's label at the reader. A row header takes the cell treatment below.
+
+   The element part is wrapped in :where() so this rule weighs one class, not a
+   class and a type. A base rule that out-ranks the component's own modifiers is
+   a base rule nothing can correct: at (0,1,1) this beat `.axi-table__num` and
+   every ink class a consumer could put on a cell, so the column that carries
+   the measured value was silently still the dim one. */
+.axi-table :where(thead th) {
   padding: 0 10px 10px;
   font: var(--axi-t-micro);
   letter-spacing: var(--axi-ls-micro);
@@ -76,8 +82,7 @@
   color: var(--axi-text-faint);
   border-bottom: var(--axi-border-control) solid var(--axi-rule);
 }
-.axi-table td,
-.axi-table tbody th {
+.axi-table :where(td, tbody th) {
   padding: 9px 10px;
   font: var(--axi-t-small);
   font-weight: 700;

package/src/primitives.css

@@ -38,6 +38,36 @@
    on the other surface that needs it. */
 .axi-panel--float { background: var(--axi-surface-float); }
 
+/* A panel that stands in a grid of its own kind rather than alone on the page.
+   Same surface, one form step down: the control border and the control block,
+   so a row of six tiles does not read as six page regions arguing with the
+   page that holds them.
+
+   This is the form ramp doing work a hue would otherwise be asked to do. A
+   tile beside a tile is level; a tile beside a plain .axi-panel is outranked -
+   which is how a grid of readings says "this one is first" without spending
+   the accent on it, and the accent is not available for that anyway (it means
+   the thing you picked, and nobody picks a winner, the data does).
+
+   Padding reads the panel's own knob so a consumer overriding --axi-panel-pad
+   does not have to know which of the two it is looking at, at the tighter
+   figure a tile wants. */
+.axi-panel--tile {
+  border-width: var(--axi-border-control);
+  box-shadow: var(--axi-shadow-control);
+  padding: var(--axi-panel-pad, 12px);
+}
+/* A tile you can press moves under the press, the way every other control in
+   the language does. Keyed off what the tile already is rather than a second
+   class: a tile that is a button, a link, or a div wearing the button role has
+   said so once, and should not have to say it again for the shadow. The role
+   selector is there because it is what a pressable div in real markup actually
+   carries - the alternative is a consumer with a keyboard handler and no
+   hover, which is the worse half of the bargain. */
+a.axi-panel--tile:hover,
+button.axi-panel--tile:hover,
+.axi-panel--tile[role='button']:hover { box-shadow: var(--axi-shadow-control-hover); }
+
 /* ---------- well ---------- */
 /* The panel's inverse: a field sunk into the surface around it rather than
    raised off it. No block, because a recess casts nothing, and the rule rather
@@ -48,7 +78,13 @@
 .axi-well {
   background: var(--axi-well-fill);
   border: var(--axi-border-control) solid var(--axi-well-line);
-  border-radius: var(--axi-radius);
+  /* A knob rather than a fixed radius, unlike the panel's, because a well is
+     the one form in the language that is used at two scales: a field the size
+     of a page column, and a recess the size of a single reading. At reading
+     scale the large radius is the wrong one - it is the radius everything else
+     that small already declines - so those instances say --axi-radius-sm here
+     rather than reaching for a modifier or a second class. */
+  border-radius: var(--axi-well-radius, var(--axi-radius));
   /* Tighter than a panel's 26px: a well is a container for objects that carry
      their own padding, not a page margin. */
   padding: var(--axi-well-pad, 10px);

package/src/shells.css

@@ -264,7 +264,11 @@
   font-size: 14px; font-weight: 900;
   border: var(--axi-border-control) solid var(--axi-ink-line);
 }
-.axi-notice p { margin: 0; font: var(--axi-t-small); color: var(--axi-text-dim); }
+/* :where() around the element, here and on the card's and the quote's copy,
+   for the reason spelled out over `.axi-table :where(thead th)` in data.css: a
+   slot that holds a consumer's words must not out-rank the ink the consumer
+   puts on them. */
+.axi-notice :where(p) { margin: 0; font: var(--axi-t-small); color: var(--axi-text-dim); }
 .axi-notice b { color: var(--axi-accent); font-weight: 800; }
 
 /* ---------- toolbar ---------- */
@@ -533,7 +537,7 @@
   color: var(--axi-text-faint);
   letter-spacing: .08em; text-transform: uppercase;
 }
-.axi-card p { margin: 0; font: var(--axi-t-small); color: var(--axi-text-dim); }
+.axi-card :where(p) { margin: 0; font: var(--axi-t-small); color: var(--axi-text-dim); }
 /* Pushed to the bottom so that in an equalised grid row every card's meta
    strip lands on the same line and the rules read as continuous across the
    grid. The cost is empty space on cards with less content. */
@@ -596,7 +600,7 @@
   background: var(--axi-ground);
   border-radius: 0 var(--axi-radius-sm) var(--axi-radius-sm) 0;
 }
-.axi-quote p { margin: 0; font-size: 13px; font-style: italic; color: var(--axi-text-dim); line-height: 1.5; }
+.axi-quote :where(p) { margin: 0; font-size: 13px; font-style: italic; color: var(--axi-text-dim); line-height: 1.5; }
 .axi-quote cite {
   display: block; margin-top: 7px;
   font-style: normal; font-size: 11.5px; font-weight: 700;

package/src/utilities.css

@@ -0,0 +1,54 @@
+/* axi design language - utilities.
+   Two families of single-purpose class, and the file is last in the cascade
+   because that is the whole point of it: a utility has to be able to overrule
+   the component it sits inside, and it is not allowed to buy that with
+   !important or with a padded selector.
+
+   Why the language needs them at all. Rules 5 and 6 draw a distinction the
+   reader is expected to make at a glance - a filled status against a cool ink
+   that is commentary - and until now the only way to say either was to be a
+   component that said it for you. Real markup is full of places that are not
+   components: a number in a sentence, a word in a legend, a value beside a
+   label. An app with no way to say "this reading is bad" in those places will
+   reach for a colour literal, and at that moment the theme stops reaching it.
+   So the language names the meanings, and the app spends them by name.
+
+   What they deliberately are not. An ink sets colour and nothing else - no
+   size, no weight, no spacing, no surface - and an edge sets border-colour
+   without asserting that there is a border. Neither is a shorthand for a
+   component: a status that belongs to a whole object still wants the chip or
+   the cap that rule 5 describes, because an object's verdict should be a shape
+   the eye finds, not a recoloured word inside it. These are for the marks
+   inside those shapes.
+
+   And there is no fill family. Under rule 2 colour at partial opacity over the
+   ground is not available, and an opaque status fill behind arbitrary text is a
+   chip - which the language already ships. A surface stays a surface token. */
+
+/* The five meanings. Ordered as rule 5 orders them: the three statuses, then
+   the cool ink that is not a status, then the accent - which means "the thing
+   you picked" and never "good". */
+.axi-ink-ok { color: var(--axi-ok); }
+.axi-ink-warn { color: var(--axi-warn); }
+.axi-ink-danger { color: var(--axi-danger); }
+.axi-ink-meta { color: var(--axi-meta); }
+.axi-ink-accent { color: var(--axi-accent); }
+
+/* The three neutral steps. `plain` rather than `text` so that reading the class
+   list does not suggest it does something to the text other than ink it, and so
+   the three read as one scale. */
+.axi-ink-plain { color: var(--axi-text); }
+.axi-ink-dim { color: var(--axi-text-dim); }
+.axi-ink-faint { color: var(--axi-text-faint); }
+
+/* Edges. `rule` and `line` are the two neutral weights of meaning, not of
+   width: --axi-rule is the quiet separator inside a surface, --axi-ink-line the
+   full ink a raised thing is outlined in. Width stays with whoever drew the
+   border. */
+.axi-edge-ok { border-color: var(--axi-ok); }
+.axi-edge-warn { border-color: var(--axi-warn); }
+.axi-edge-danger { border-color: var(--axi-danger); }
+.axi-edge-meta { border-color: var(--axi-meta); }
+.axi-edge-accent { border-color: var(--axi-accent); }
+.axi-edge-rule { border-color: var(--axi-rule); }
+.axi-edge-line { border-color: var(--axi-ink-line); }