@axiapps/axi-design 1.6.0

package/docs/RULES.md

@@ -0,0 +1,275 @@
+# The axi design language
+
+Flat and outlined. Every fill is a saturated ink at full strength, every raised
+element is drawn with a near-black outline and a hard offset block instead of a
+blur.
+
+These are the rules. A component that cannot be justified by one of them either
+needs a new rule written for it, or does not belong in the system.
+
+## 1. No gradients on surfaces
+
+Flat fills only. The two exceptions in the codebase are both a gradient used
+to draw a *shape*, with no soft transition anywhere in them: the select caret
+(two `linear-gradient`s meeting to make a triangle) and `.axi-plot`'s
+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, and always will be.
+
+## 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
+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.
+
+## 3. Every raised element is outlined and blocked
+
+An `--axi-ink-line` border plus a hard offset shadow, never a blur.
+
+Two weight steps, and only two:
+
+| Step | Border | Offset |
+|---|---|---|
+| Panel | `--axi-border-panel` (4px) | `--axi-offset-panel` (6px) |
+| Control | `--axi-border-control` (3px) | `--axi-offset-control` (3px) |
+
+A third step is how a system stops looking like one system.
+
+There is one weight outside the table, and it is deliberately not a step:
+`--axi-border-hairline` (2px), used only inside `.axi-prose` — for inline
+code, table rules and the list bullet — where either form step reads as too
+heavy for a line of running text. It is a prose rule weight, never an outline
+on a raised thing.
+
+**What is mechanically enforced.** `tests/tokens.test.mjs` enforces both
+columns:
+
+- *Border* — no literal border/outline weight may appear in any component
+  file: not a `px` value, not another length unit (`rem`, `em`, ...), and not
+  a `thin`/`medium`/`thick` keyword. A width has to come through
+  `--axi-border-panel`, `--axi-border-control` or `--axi-border-hairline`.
+  `outline`/`outline-width` are checked the same way as `border`
+  (`outline-offset` and `outline-color` are not weight properties and are
+  untouched).
+- *Offset* — every `box-shadow` in a component file must be exactly
+  `<offset> <offset> 0 var(--axi-ink-line)`, with the offset drawn from an
+  enumerated list of four tokens: the two resting steps above, plus the two
+  hover deepenings rule 4 describes (`--axi-offset-panel-hover` 10px,
+  `--axi-offset-control-hover` 6px). That is what rules out a blur, a spread,
+  an invented offset and a shadow in any colour but the ink line.
+  `filter: drop-shadow(...)` and `text-shadow` — the two other CSS properties
+  that can draw the same blurred look — are forbidden outright, since nothing
+  in this language legitimately reaches for either.
+- *No local escape hatch* — the form tokens themselves
+  (`--axi-border-panel`, `--axi-border-control`, `--axi-border-hairline`,
+  `--axi-offset-panel`, `--axi-offset-control`, and their `-hover` variants)
+  may be **declared** only in `tokens.css`. A component file redeclaring one
+  of these on itself would change the value the border/offset checks above
+  are silently trusting, without changing the `var()` text those checks read
+  — that is the escape hatch, and it is what the mechanical checks above
+  cannot see on their own, so it is checked directly instead.
+
+Adding a fifth legal block means adding a token *and* adding it to `OFFSETS`
+in the test — there is no escape hatch that admits a bare literal, local
+redeclaration included.
+
+**Colour literal scan, precisely.** The colour check in the same file only
+scans the *value* of a declaration whose property can legally carry a colour
+(an allowlist: `color`, `background`/`background-image`, the `border*-color`
+family, `outline-color`, `box-shadow`, `text-shadow`, `filter`, `fill`,
+`stroke`, `caret-color`, `column-rule-color`, `text-decoration-color`,
+`accent-color`, `scrollbar-color`). A selector (`.card:not(.plum)`) or an
+at-rule prelude (`@supports (color: ...)`) never reaches the scan at all,
+because neither one's text starts with a colour-carrying property name — this
+is why a pseudo-class's colon is harmless. A bare named colour (`gold`,
+`tan`, `linen`, ...) is only trusted inside the plain value: never inside a
+quoted string or a `url(...)`, since those routinely contain a colour *word*
+with no colour *meaning* (a font stack, a `content` string, a texture
+filename, a cursor list). Hex and the colour functions (`#fff`, `oklch(...)`,
+...) have no other meaning in CSS, so they are still caught even inside a
+string or `url(...)` — this is what catches a colour hard-coded into a
+data-URI SVG, which would otherwise be a free pass for exactly the same
+reason the string/url() exemption exists for named colours. This is a
+deliberate asymmetry: it costs the (rare, deliberate) case of a bare named
+colour smuggled inside a data-URI SVG, in exchange for never blocking a font
+stack, a filename or a `content` string again.
+
+Radii are the one part of the form that is **not** enforced: `--axi-radius`
+and `--axi-radius-sm` exist, but controls carry a literal `8px` (and `9px`,
+`5px`, `4px` appear elsewhere). Treat the radius scale as convention, not
+contract, until it is tokenised.
+
+## 4. Hover lifts
+
+The lift is per form step, not one universal number: a control has no resting
+shadow, so a control's hover both moves it and draws its block for the first
+time — `translate(-2px, -2px)` together with gaining the `--axi-offset-control`
+(3px) block from nothing. A panel already carries its 6px block at rest, so its
+hover only needs to deepen it — `translate(-3px, -3px)` with the block growing
+from 6px to 10px (`--axi-offset-panel-hover`). Applying the panel's flat `-3px` to a control would lift it
+by exactly the depth of its own 3px block, leaving the lower-right edge where
+it started — that reads as the element growing, not lifting.
+
+There is a third case the two-step framing misses: a *control that already
+rests on a block* — `.axi-btn--primary`, a pressed `.axi-pill`. Translating it
+without deepening its block moves element and block together and leaves the
+lower-right edge exactly where it was, which is the same "grows rather than
+lifts" failure. Those deepen 3px to 6px (`--axi-offset-control-hover`) while
+keeping the control's `translate(-2px, -2px)`.
+
+Nothing in this language fades, glows or pulses. The movement reads in
+peripheral vision and costs no colour.
+
+Every lift is turned off under `@media (prefers-reduced-motion: reduce)`, in
+`base.css`, once, for every consumer. Resting appearance is untouched: the
+diamond still rotates, because a rotation that never changes is geometry and
+not motion.
+
+## 5. Filled means status, outlined means annotation
+
+A filled chip asserts a value about the thing. An outlined chip in the cool ink
+is commentary *about* the thing — a maintainer's judgment, a source, a caveat.
+A reader must be able to tell which they are looking at before reading either.
+
+The same rule governs coloured strips on cards: a strip must encode real data.
+A strip that carries "category" is decoration impersonating data, and it takes
+the first position the eye lands on.
+
+And where the strip goes is part of the rule. Status colour **caps** the thing
+it judges — a short bar across the head of the card, above the value — rather
+than framing it down the left edge. A full-height stripe runs the height of the
+box, so it reads as the box's border: five cards in a row become five coloured
+frames, and the colour stops saying anything about any one number. A cap sits
+directly over the reading it is a verdict on, identifies it once, and then gets
+out of the way. Under rule 3 the cap is drawn at the panel weight; the card
+itself keeps its plain ink outline at the control weight.
+
+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
+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
+full ink edge at the control weight, because an off switch inside a panel is a
+surface on a surface and without the edge the track disappears and all you can
+see is a slug floating in the card.
+
+## 6. One cool ink is reserved for meta
+
+`--axi-meta` marks metadata and annotation, and may never carry a status
+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.
+
+## 7. The diamond is the family motif
+
+A 45°-rotated outlined square. Bullet, status dot, language marker, and scaled
+up behind a glyph, the brand sigil.
+
+## 8. A table is the panel's interior
+
+Forty rows of numbers are not forty raised things. A table is drawn in rules —
+`--axi-rule` for the row lines, `--axi-border-hairline` for their weight — and
+never in outlines or blocks: the panel around it is the raised element, and the
+rows are what is inside it. Outlining the rows turns a list into a grid of
+boxes and costs the eye the vertical run down a column that makes a table worth
+using.
+
+One fill is allowed, in the rank column, and only where the rank is real — a
+podium position the data earned. A row *number* is not a rank, and filling it
+spends the brightest thing on screen on the fact that a list has a first line.
+
+The hover on a row is the neutral ramp, not an ink, for the same reason: moving
+the cursor down a table is not a series of status changes.
+
+## 9. A quantity is drawn as length, never intensity
+
+A proportion is a bar: the track is the ground, the fill is the value, and the
+fill is one ink at full strength. This is rule 2 applied to data — a bar faded
+to 30% to mean "30%" encodes the number twice, once legibly and once not, and
+the illegible copy is the one the eye reads first.
+
+The corollary is that this language does not draw a heatmap. Intensity-by-tint
+is the one chart type that cannot be built without the thing rule 2 forbids, so
+a distribution is drawn as bars, or as a table sorted by the value, or not at
+all.
+
+## 10. A chart's ink is the accent
+
+One series is the accent. A second, for comparison, is the neutral ramp —
+`--axi-text-faint` against the accent reads instantly as "this one, versus
+that one", and costs no new colour.
+
+Beyond two, stop and ask whether the data owns its own palette. A profession,
+a team, a map colour is domain data: it comes in per-instance through
+`--axi-series`, the way a card strip does, and it is the data's colour rather
+than the system's. If the data does *not* own a palette, a nine-colour chart is
+nine arbitrary inks competing with the five that already mean something —
+`--axi-ok`, `--axi-warn`, `--axi-danger`, `--axi-meta` and the accent keep
+their meanings inside a chart, so nothing else may borrow them for a category.
+
+The status inks still mean status inside a plot: a line drawn in `--axi-danger`
+is asserting that the quantity is bad, not that it is the third series.
+
+## 11. An indicator of work animates a composited property
+
+Spinners, progress strips and pulses almost always report on something
+expensive — a parse, a build, an upload. If the work blocks the main thread,
+anything animated by layout or paint freezes with it, and a frozen spinner is
+worse than no spinner: it is the app telling the reader it has crashed at the
+exact moment it is working hardest.
+
+So an indicator that reports on work may animate only `transform` and
+`opacity`, which the compositor runs off the main thread. No animated `width`,
+`left`, `background-position` or `background-color`. This is the one rule here
+that is about honesty rather than composition, and it is not negotiable for
+anything that claims to show liveness.
+
+Motion elsewhere is still rationed by rule 4.
+
+## Tokens
+
+Three layers, in `src/tokens.css` — the only file permitted to contain a colour
+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`
+- **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
+  themed.
+- **Form** — outline and offset steps, radii, measures (`--axi-page`,
+  `--axi-page-narrow`, `--axi-page-wide`, `--axi-gutter`) and the type scale.
+  Overriding these means leaving the language, not theming it.
+
+Per-instance knobs (`--axi-pill-fill`, `--axi-grid-min`, `--axi-page-pad`, …)
+are a separate surface from these tokens: they are set on one element, or on
+an ancestor, with a `style=""` attribute rather than in `:root`. The full list
+is [the consumer API table in the README](../README.md#per-instance-knobs).
+
+### Theming an app
+
+```css
+:root { --axi-accent: #b06bff; }
+```
+
+If an app picks an accent dark enough that near-black text on it fails
+contrast, it also sets `--axi-accent-ink: var(--axi-text)`. It should not edit
+components.
+
+## Light mode
+
+Not shipped. The system is *structured* for it: no component contains a colour
+literal, so a light theme is a second palette block, not a rewrite. It is not
+a token swap either — the saturated inks that read as vivid on near-black go
+washed out on white and would need retuning.
+
+## Adding a component
+
+1. Which rule justifies it? If none, write the rule first or stop.
+2. Build it from the existing primitives. A shell that redefines `.axi-panel`
+   instead of using it will drift the first time the panel changes.
+3. No colour literals. No third form step.
+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.

package/package.json

@@ -0,0 +1,35 @@
+{
+  "name": "@axiapps/axi-design",
+  "version": "1.6.0",
+  "description": "The design language for the axi suite — flat and outlined, dark, drawn in saturated ink.",
+  "type": "module",
+  "license": "MIT",
+  "author": "darkharasho",
+  "repository": { "type": "git", "url": "git+https://github.com/darkharasho/axi-design.git" },
+  "homepage": "https://darkharasho.github.io/axi-design/",
+  "engines": { "node": ">=22" },
+  "//publishConfig": "A scoped package defaults to a restricted publish, and a restricted design language is no use to the apps that consume it. Pinned here rather than passed as --access public on the command line, so it cannot be forgotten on a later release.",
+  "publishConfig": { "access": "public" },
+  "//exports": "Two entry points, and both are stylesheets. Consumers import the path rather than the package root because there is no JavaScript here to be a default export - `import '@axiapps/axi-design/axi.css'` says what it does, and a bare `import '@axiapps/axi-design'` resolving to a stylesheet would not. ./tokens.css is the palette without the components, for an app that already draws its own components through its own variables and wants to point them at ours: it is the whole language for a consumer like that, and copying the token block by hand is the one way those values are guaranteed to drift.",
+  "exports": {
+    "./axi.css": "./dist/axi.css",
+    "./tokens.css": "./src/tokens.css",
+    "./package.json": "./package.json"
+  },
+  "//sideEffects": "A stylesheet is nothing but a side effect. Without this a bundler treating the import as dead code would drop the whole design language from a production build.",
+  "sideEffects": [
+    "*.css"
+  ],
+  "//files": "dist/ is the artifact; src/ and docs/ ride along because RULES.md is the reason any of it is shaped the way it is, and a consumer reading a component wants it next to them. No tests, no gallery. LICENSE and README are included by npm regardless of this list.",
+  "files": [
+    "dist",
+    "src",
+    "docs",
+    "README.md"
+  ],
+  "scripts": {
+    "build": "node scripts/build.mjs",
+    "test": "vitest run"
+  },
+  "devDependencies": { "vitest": "^2.1.0" }
+}

package/src/base.css

@@ -0,0 +1,66 @@
+/* axi design language - base.
+   Element-level defaults every axi property inherits. Nothing here is a
+   component; if it needs a class, it belongs in a later layer. */
+
+*, *::before, *::after { box-sizing: border-box; }
+
+/* Dark is the only theme shipped today. Declaring the scheme means form
+   controls, scrollbars and the like come up dark from the first paint rather
+   than flashing light, and it is the one line a light theme will flip. */
+html { color-scheme: dark; }
+
+body {
+  margin: 0;
+  background: var(--axi-ground);
+  color: var(--axi-text);
+  font: var(--axi-t-body);
+  -webkit-font-smoothing: antialiased;
+}
+
+/* Links inherit their colour by default: in this language a link is usually
+   inside something that has already chosen an ink, and a globally accented
+   link would fight every card title and nav item. Components opt into the
+   accent where a link should read as one. */
+a { color: inherit; }
+
+/* The focus ring is accent-coloured and thick enough to read against a
+   near-black outline, which a 1px ring does not. It is drawn entirely with
+   `outline`, which follows whatever radius the element already has: a
+   `border-radius` here would reshape the focused element itself, which was
+   harmless for our components only because each one's own radius happens to
+   land later in the build ORDER, and visibly wrong for an unclassed
+   checkbox or link. */
+:focus-visible {
+  outline: var(--axi-border-control) solid var(--axi-accent);
+  outline-offset: 2px;
+}
+
+.axi-sr-only {
+  position: absolute; width: 1px; height: 1px; padding: 0; margin: -1px;
+  overflow: hidden; clip: rect(0 0 0 0); white-space: nowrap; border: 0;
+}
+
+/* Everything this language animates is the hover lift, and the lift is the
+   one thing a reader who has asked for less motion is asking not to see.
+   Neutralise the movement, not the appearance: the resting transforms - the
+   diamond's rotation, the sigil, the search glyph's centring - are geometry
+   rather than motion and are deliberately untouched, so nothing looks
+   different until you point at it. The !important is what lets this sit in
+   the base layer and still outrank component hover rules that come later in
+   the build ORDER at equal specificity. */
+@media (prefers-reduced-motion: reduce) {
+  *, *::before, *::after {
+    transition-duration: .01ms !important;
+    animation-duration: .01ms !important;
+    animation-iteration-count: 1 !important;
+    scroll-behavior: auto !important;
+  }
+  .axi-btn:hover,
+  .axi-pill:hover,
+  .axi-pill[aria-pressed="true"]:hover,
+  .axi-select:hover,
+  .axi-card:hover,
+  .axi-drawer__close:hover {
+    transform: none !important;
+  }
+}

package/src/data.css

@@ -0,0 +1,243 @@
+/* axi design language - data.
+   Numbers, and the shapes numbers are drawn as. Everything here is panel
+   INTERIOR: a table, a meter and a plot all live inside a .axi-panel, and
+   none of them is a raised thing in its own right, so none of them carries a
+   block. They are drawn in rules (--axi-rule) and in the ink line, which is
+   what keeps a screen of forty metrics from reading as forty floating cards.
+
+   Three rules govern the file - docs/RULES.md 8, 9 and 10:
+   a table is the panel's interior; a quantity is drawn as length, never as
+   intensity; and a chart's ink is the accent, with the neutral ramp for
+   comparison and a domain palette only where the data owns its own colours. */
+
+/* ---------- stat tile ---------- */
+/* One number and its name. Flat on the ground inside its panel, so it takes
+   an outline and no block - it is content, not something raised off the
+   surface it sits on. The number stays in --axi-text unless it has a real
+   state: rule 5 applies to a figure exactly as it applies to a chip, and a
+   tile coloured for emphasis is decoration impersonating status. */
+.axi-stat {
+  padding: 12px 14px;
+  background: var(--axi-ground);
+  border: var(--axi-border-control) solid var(--axi-ink-line);
+  border-radius: 8px;
+}
+.axi-stat__n {
+  display: block;
+  font: var(--axi-t-h1);
+  letter-spacing: var(--axi-ls-h1);
+  color: var(--axi-text);
+  font-variant-numeric: tabular-nums;
+}
+.axi-stat__k {
+  display: block;
+  margin-top: 5px;
+  font: var(--axi-t-micro);
+  letter-spacing: var(--axi-ls-micro);
+  text-transform: uppercase;
+  color: var(--axi-text-faint);
+}
+.axi-stat--accent .axi-stat__n { color: var(--axi-accent); }
+.axi-stat--ok .axi-stat__n { color: var(--axi-ok); }
+.axi-stat--warn .axi-stat__n { color: var(--axi-warn); }
+.axi-stat--danger .axi-stat__n { color: var(--axi-danger); }
+/* The one tile that annotates instead of asserting: a count of something the
+   app knows *about* the data rather than a measurement of it. */
+.axi-stat--meta .axi-stat__n { color: var(--axi-meta); }
+
+/* ---------- table ---------- */
+/* Rule 8. Rows are separated by rules, never outlined and never blocked: the
+   panel is the raised thing and the table is what is inside it. The header
+   rule is the control weight so the head reads as a lid on the column; the
+   row rules are the hairline, which is exactly the case --axi-border-hairline
+   exists for - a line inside running content, where either form step would
+   turn a list of numbers into a grid of boxes. */
+.axi-table {
+  width: 100%;
+  border-collapse: collapse;
+  font-variant-numeric: tabular-nums;
+}
+/* Numbers right, names left. Set on the element rather than asked of every
+   consumer, because a numeric column aligned left is unreadable and it is
+   the mistake every hand-built table makes. */
+.axi-table th,
+.axi-table td { text-align: right; white-space: nowrap; }
+.axi-table th:first-child,
+.axi-table td:first-child { text-align: left; }
+.axi-table th {
+  padding: 0 10px 10px;
+  font: var(--axi-t-micro);
+  letter-spacing: var(--axi-ls-micro);
+  text-transform: uppercase;
+  color: var(--axi-text-faint);
+  border-bottom: var(--axi-border-control) solid var(--axi-rule);
+}
+.axi-table td {
+  padding: 9px 10px;
+  font: var(--axi-t-small);
+  font-weight: 700;
+  color: var(--axi-text-dim);
+  border-bottom: var(--axi-border-hairline) solid var(--axi-rule);
+}
+/* The row under the cursor comes forward on the neutral ramp. Not an ink:
+   hovering a row is not a status, and forty rows that each flash a colour on
+   the way past the one you want is the tinted-everything failure rule 2 is
+   about. */
+.axi-table tbody tr:hover td { background: var(--axi-surface-raised); color: var(--axi-text); }
+/* The measured value in a row, as opposed to its supporting numbers. */
+.axi-table__num { color: var(--axi-text); }
+/* A name cell: an icon, a diamond or a rank beside the label. */
+.axi-table__who { display: flex; align-items: center; gap: 9px; }
+/* Rank is the only fill a table gets, and only where the position is real -
+   a podium, not a row number. An outlined rank is the ordinary case. */
+.axi-table__rank {
+  width: 22px; height: 22px; flex: none;
+  display: grid; place-items: center;
+  border: var(--axi-border-control) solid var(--axi-ink-line);
+  border-radius: var(--axi-radius-sm);
+  background: var(--axi-ground);
+  font: var(--axi-t-micro);
+  color: var(--axi-text-faint);
+}
+.axi-table__rank--top { background: var(--axi-accent); color: var(--axi-accent-ink); }
+
+/* ---------- meter ---------- */
+/* Rule 9: a proportion is a length. The track is the ground, the fill is the
+   value, and the fill is one ink at full strength - a tinted or faded bar is
+   the same lie as a tinted surface, and it is unreadable at the small sizes a
+   table of them is actually used at.
+   A meter holds one fill (a value) or several (a composition). There is no
+   divider between adjacent fills: two saturated inks already separate
+   themselves, and a line between them would be a third form step. */
+.axi-meter {
+  display: flex;
+  height: var(--axi-meter-h, 12px);
+  background: var(--axi-ground);
+  border: var(--axi-border-control) solid var(--axi-ink-line);
+  border-radius: var(--axi-radius-sm);
+  overflow: hidden;
+}
+.axi-meter__fill {
+  flex: none;
+  height: 100%;
+  width: var(--axi-meter-v, 0%);
+  background: var(--axi-series, var(--axi-accent));
+}
+
+/* A labelled run of meters: the shape almost every "who did most of X" view
+   in an axi property turns out to be. Three columns, so the names, the bars
+   and the values each line up down the list; both outer columns are knobs
+   because a list of account names and a list of boon names disagree about
+   how much room a label needs. */
+.axi-meter-list {
+  display: grid;
+  grid-template-columns: var(--axi-meter-label, 132px) 1fr var(--axi-meter-value, 62px);
+  align-items: center;
+  gap: 9px 12px;
+}
+.axi-meter-list__name {
+  overflow: hidden; text-overflow: ellipsis; white-space: nowrap;
+  font: var(--axi-t-small);
+  font-weight: 700;
+  color: var(--axi-text-dim);
+}
+.axi-meter-list__value {
+  text-align: right;
+  font: var(--axi-t-micro);
+  letter-spacing: var(--axi-ls-micro);
+  color: var(--axi-text);
+  font-variant-numeric: tabular-nums;
+}
+
+/* ---------- bars ---------- */
+/* The same rule stood on end. The baseline is drawn at the control weight
+   because it is an axis - the one line in a chart that is structure rather
+   than data - and every column is outlined in the ink line so a short column
+   is still a shape and not a smear. Columns share their baseline with it, so
+   they drop their own bottom border rather than doubling it. */
+.axi-bars {
+  display: flex;
+  align-items: flex-end;
+  gap: var(--axi-bars-gap, 6px);
+  height: var(--axi-plot-h, 180px);
+  border-bottom: var(--axi-border-control) solid var(--axi-ink-line);
+}
+.axi-bars__col {
+  flex: 1 1 0;
+  min-width: 4px;
+  height: var(--axi-bar-v, 0%);
+  display: flex;
+  flex-direction: column-reverse;
+  overflow: hidden;
+  background: var(--axi-series, var(--axi-accent));
+  border: var(--axi-border-control) solid var(--axi-ink-line);
+  border-bottom: 0;
+  border-radius: var(--axi-radius-sm) var(--axi-radius-sm) 0 0;
+}
+/* A stacked column. The parts are laid out from the baseline up, in source
+   order, so the markup reads bottom-to-top the way the chart does. */
+.axi-bars__part {
+  flex: none;
+  width: 100%;
+  height: var(--axi-bar-part, 0%);
+  background: var(--axi-series, var(--axi-accent));
+}
+
+/* ---------- plot ---------- */
+/* A frame for a line or an area, with its horizontal rules drawn in. The
+   rules are hard stops in a repeating gradient, which is the select caret's
+   exception to rule 1 - a gradient used to draw a shape, with no soft
+   transition anywhere in it - and the only way to get N evenly spaced rules
+   without asking every consumer to emit N empty divs. */
+.axi-plot {
+  position: relative;
+  height: var(--axi-plot-h, 180px);
+  background-color: var(--axi-ground);
+  background-image: repeating-linear-gradient(
+    to top,
+    var(--axi-rule) 0 var(--axi-border-hairline),
+    transparent var(--axi-border-hairline) calc(100% / var(--axi-plot-rows, 4))
+  );
+  border: var(--axi-border-control) solid var(--axi-ink-line);
+  border-radius: var(--axi-radius-sm);
+  overflow: hidden;
+}
+/* The geometry itself is the consumer's - this language does not compute a
+   path - but its ink and weight are ours, so a line in an axi property is
+   the same line everywhere. */
+.axi-plot__svg { position: absolute; inset: 0; width: 100%; height: 100%; }
+.axi-plot__line {
+  fill: none;
+  stroke: var(--axi-series, var(--axi-accent));
+  stroke-width: var(--axi-border-control);
+  stroke-linejoin: round;
+  stroke-linecap: round;
+  vector-effect: non-scaling-stroke;
+}
+/* An area is the region under a line, filled at full strength like every
+   other fill in this language. It is opaque, so two overlapping areas are
+   not a chart this system draws - that is what the second line, or a second
+   plot, is for. */
+.axi-plot__area { fill: var(--axi-series, var(--axi-accent)); stroke: none; }
+
+/* ---------- axis and legend ---------- */
+/* The x labels under a plot. There is no y-axis component: the scale of a
+   chart belongs in the label above it, in words, where it is readable at a
+   glance and survives being screenshotted into Discord. */
+.axi-axis {
+  display: flex;
+  justify-content: space-between;
+  margin-top: 8px;
+  font: var(--axi-t-micro);
+  letter-spacing: var(--axi-ls-micro);
+  text-transform: uppercase;
+  color: var(--axi-text-faint);
+}
+.axi-legend { display: flex; flex-wrap: wrap; gap: 7px 16px; }
+.axi-legend__key {
+  display: inline-flex; align-items: center; gap: 8px;
+  font: var(--axi-t-micro);
+  letter-spacing: var(--axi-ls-micro);
+  text-transform: uppercase;
+  color: var(--axi-text-dim);
+}

package/src/layout.css

@@ -0,0 +1,47 @@
+/* axi design language - layout.
+   Three measures, one grid, two spacing helpers. Deliberately small: a
+   layout system large enough to express any page is a framework, and every
+   property here can reach for plain CSS grid the moment it needs something
+   these do not cover. */
+
+/* The page wrapper. --axi-page is the default because most axi surfaces are
+   browsing views; the two modifiers exist because prose and dense catalogs
+   genuinely disagree about measure, and hard-coding either default made one
+   of them wrong. */
+.axi-page {
+  max-width: var(--axi-page);
+  margin-inline: auto;
+  /* The gutter is a knob because measures nest: a --narrow prose column or a
+     --wide grid placed inside a page that has already paid the gutter would
+     otherwise pay it twice, with no way to say so but an inline
+     `padding-inline: 0`. Set --axi-page-pad: 0 on the inner one. */
+  padding-inline: var(--axi-page-pad, var(--axi-gutter));
+}
+/* Prose. Beyond this measure a line of body text gets hard to track back to
+   the start of the next one. */
+.axi-page--narrow { max-width: var(--axi-page-narrow); }
+/* Dense card grids, where width spent on margins is a column not shown. */
+.axi-page--wide { max-width: var(--axi-page-wide); }
+
+/* Auto-fill card grid. The minimum column width is per-instance rather than
+   global: a grid of ten app cards and a grid of sixty catalog entries want
+   genuinely different minimums, and both are this same component. */
+.axi-grid {
+  display: grid;
+  grid-template-columns: repeat(auto-fill, minmax(var(--axi-grid-min, 300px), 1fr));
+  gap: var(--axi-gutter);
+}
+
+/* Vertical rhythm between siblings, set per-instance. */
+.axi-stack { display: flex; flex-direction: column; gap: var(--axi-stack-gap, 12px); }
+/* A horizontal run that wraps rather than overflowing. */
+.axi-row { display: flex; align-items: center; flex-wrap: wrap; gap: var(--axi-row-gap, 10px); }
+
+@media (max-width: 640px) {
+  /* The fallback must match the resting rule's (var(--axi-gutter), 18px) -
+     README.md documents --axi-page-pad's fallback as --axi-gutter, and a
+     literal here silently ignores a consumer's --axi-gutter override on
+     mobile, which is the one viewport where the gutter matters most. */
+  .axi-page { padding-inline: var(--axi-page-pad, var(--axi-gutter)); }
+  .axi-grid { grid-template-columns: 1fr; }
+}