@axiapps/axi-design 1.8.0 → 1.10.0

package/docs/superpowers/specs/2026-09-23-axi-docs-site-design.md

@@ -0,0 +1,333 @@
+# axi-design documentation site — design
+
+**Date:** 2026-09-23
+**Status:** approved, ready for planning
+**Scope:** round one of two. This spec covers the documentation site only. Adding
+missing elements (modal, alert, breadcrumb, pagination, accordion, checkbox,
+radio, textarea, progress, toast, avatar, spinner, …) is round two and gets its
+own spec.
+
+## Intent
+
+Today `axi-design` publishes a single `index.html` that scrolls through six
+sections of examples. It proves the components exist; it does not explain them,
+cannot be deep-linked, and has no mechanism preventing a component from going
+undocumented. This project turns that page into a documentation site in the
+mould of Bootstrap's — per-component pages, narrative guides, search — built
+entirely out of axi's own components.
+
+### Audiences, all three weighted
+
+1. **The author, across the suite.** Building an app, needs the exact class
+   names and copyable markup in seconds. Optimises for density, search and
+   deep links.
+2. **An LLM agent writing axi-styled UI.** Needs the complete class inventory,
+   the knob surface, and the rules it must not break. Optimises for
+   completeness and machine-readable structure (`llms.txt`).
+3. **An outside adopter arriving from npm.** Needs to see what it looks like
+   and decide. Optimises for a landing page that shows rather than tells.
+
+### Success criteria
+
+- Every `.axi-*` class in `src/` is reachable from a documentation page, and
+  this is enforced by a test rather than by discipline.
+- The markup shown in a code block is, by construction, the markup that
+  produced the demo beside it. Drift is structurally impossible.
+- The site's own chrome uses only axi components plus a quarantined
+  `.docs-*` layer. The site is evidence the language can build a real site.
+- `docs/RULES.md` remains the single source of truth for the language; the
+  site renders it rather than restating it.
+- Nothing a consumer downloads changes. `dist/axi.css`, the npm tarball and
+  every published `/vN/axi.css` are untouched by this work.
+
+### Non-goals
+
+- No new components, no changes to any file in `src/`. Gaps the work exposes
+  are recorded for round two, not filled.
+- No light theme, no i18n, no versioned documentation (the site documents the
+  current version; only the CSS artifacts are versioned, as today).
+- No runtime dependency, ever. The only new dependency is `marked`, build-time
+  and `devDependencies` only.
+
+## Approach
+
+Rejected: a static site generator (11ty/VitePress). It would theme the docs in
+its own design system, which for a design language forfeits the site's main
+argument, and it imports a toolchain into a repo with one devDependency.
+
+Rejected: hand-written HTML per page. No forcing function keeping components
+documented, and the shared chrome gets copy-pasted into thirty files — a cost
+that compounds exactly when round two doubles the page count.
+
+**Chosen:** a generator owned by this repo, driven by a component manifest, with
+Markdown for narrative prose. The manifest gives enforcement and machine-readable
+output; Markdown keeps the guides pleasant enough to actually write.
+
+## Site map
+
+```
+/                       Landing — the look, the pitch, install in three lines
+/start/                 Getting started: the three consumption modes, set an accent
+/rules/                 docs/RULES.md, rendered
+/theming/               Tokens, the accent list, the per-instance knob table
+/components/            Index: every component grouped by layer, with preview tiles
+/components/<id>/       One page per component family (~30 pages)
+/gallery/               The kitchen sink — today's index.html, everything on one scroll
+/llms.txt               Exhaustive machine-readable reference
+/search.json            Client-side search index
+/vN/axi.css             Unchanged; staged from git tags exactly as today
+```
+
+`/gallery/` is retained deliberately. It is the only view in which the system
+can be judged as a whole, which thirty separate pages actively obscure. It stops
+being the front door and becomes the smoke test.
+
+`/rules/` renders `docs/RULES.md` through `marked` into `.axi-prose`. There is no
+second copy. RULES.md continues to ship in the npm tarball and continues to be
+what `tests/tokens.test.mjs` is written against.
+
+## The manifest
+
+```
+docs/manifest/
+  index.mjs        combines the layer modules, validates entry shape
+  primitives.mjs   layout.mjs   shells.mjs   data.mjs   prose.mjs   utilities.mjs
+  knobs.mjs        the per-instance knob table, as data
+```
+
+`.mjs` rather than JSON so example markup can be a readable template literal and
+entries can carry comments.
+
+### Entry shape
+
+```js
+{
+  id: 'meter',                      // URL segment; /components/meter/
+  name: 'Meter',
+  layer: 'data',                    // sidebar group; see note below
+  classes: ['.axi-meter', '.axi-meter__fill', '.axi-meter-list', …],
+  summary: 'One or two sentences. Used on the page, the index tile and llms.txt.',
+  rules: [1, 2],                    // clause numbers in docs/RULES.md
+  knobs: ['--axi-meter-v', '--axi-meter-h', '--axi-series'],
+  notes: `Optional Markdown for anything the summary cannot carry.`,
+  examples: [
+    { title: 'A single meter', note: 'Optional one-liner, right-aligned', html: `…` },
+  ],
+}
+```
+
+**`layer` is a documentation concern, not a source-file fact.** The `src/` split
+is by cascade order, not by category, and the two genuinely differ:
+
+| Class | Lives in | Documented under |
+|---|---|---|
+| `.axi-panel` | `primitives.css` | Layout |
+| `.axi-quote` | `shells.css` | Prose |
+| `.axi-notice`, `.axi-tooltip`, `.axi-eyebrow`, `.axi-sigil` | `shells.css` | Primitives |
+| `.axi-sr-only` | `base.css` | Utilities |
+
+`layer` is therefore declared per entry and never inferred from the file. A
+`utilities` group exists for classes that are real and documented but belong to
+no visual family.
+
+### Single-sourcing of examples
+
+Each `examples[].html` string is rendered twice by the generator: raw into the
+live demo, and HTML-escaped-then-highlighted into the code block beneath it.
+This is the central mechanism of the design — the copyable code cannot drift
+from the rendered demo because there is only one string.
+
+## The generator
+
+`scripts/site.mjs`, new, separate from `scripts/build.mjs`. `build.mjs` continues
+to build the shipped artifact and is not modified except where noted under
+"README knob table". Different lifecycles, and nothing in the site generator can
+affect what a consumer downloads.
+
+```
+docs/site/
+  shell.mjs      page chrome: mast, sidebar, TOC, footer
+  render.mjs     component-page and index-page renderers
+  markdown.mjs   marked wrapper → .axi-prose
+  highlight.mjs  build-time HTML tokeniser
+  docs.css       docs-only chrome, .docs-* prefix
+  search.js      client-side search over search.json
+  copy.js        code-block copy buttons
+```
+
+Markdown pages may embed generated content through a placeholder line — a
+lone `<!-- axi:knobs -->` or `<!-- axi:accents -->` in the source — which the
+generator replaces with the rendered table. This is how `/theming/` shows the
+knob and accent tables without a hand-maintained second copy, and it is the
+same mechanism as the README markers. An unrecognised `axi:` placeholder is a
+build error rather than a silent passthrough.
+
+Outputs to `_site/`: directory-style URLs (`_site/components/meter/index.html`),
+plus `search.json`, `llms.txt`, and copies of `dist/` and `docs/site/*.{css,js}`.
+
+### Base-path handling
+
+The site is served from `darkharasho.github.io/axi-design/`, not from a domain
+root, while local preview is served from `/`. The generator takes a single
+`BASE` constant (`/axi-design/` for Pages, `/` for `npm run serve`) and every
+emitted href passes through one `url()` helper. A test asserts no emitted page
+contains a raw `href="/` or `src="/` outside that helper. This is the most
+likely thing to ship silently broken, so it is checked directly.
+
+### Syntax highlighting
+
+Build-time, hand-rolled in `highlight.mjs`, roughly 30 lines. HTML only — the
+one language the samples are written in. Four token classes, coloured from
+existing tokens:
+
+| Token | Class | Ink |
+|---|---|---|
+| Tag name | `.t-tag` | `--axi-meta` |
+| Attribute name | `.t-attr` | `--axi-accent` |
+| Attribute value | `.t-str` | `--axi-ok` |
+| Punctuation | `.t-punc` | `--axi-text-faint` |
+
+A Prism/Shiki dependency is not justified for HTML, and would be a runtime cost
+paid by every visitor for a transform that can happen once at build time.
+
+### Docs-only CSS is quarantined
+
+`docs/site/docs.css` holds the sidebar, TOC, code block and example-block
+styles under a `.docs-*` prefix. It is never read by `build.mjs`, never enters
+`dist/`, and is not in the npm `files` list.
+
+Deliberate side effect: **`docs.css` is the shopping list for round two.**
+Anything in it that proves generally useful becomes a candidate for promotion
+into `src/`, having earned its place by being needed rather than by appearing
+on another framework's feature list.
+
+## Page anatomy
+
+### Component page
+
+Three columns: sidebar (grouped by `layer`, current page filled solid in the
+accent — the language has no soft states, so "selected" is a block of ink),
+content, and an "On this page" TOC. Below the layout breakpoint the TOC is
+dropped and the sidebar collapses into a disclosure in the mast.
+
+Content order:
+
+1. `.axi-eyebrow` with the layer name
+2. Title
+3. Lede — the `summary` field
+4. Class list as `.axi-chip--meta` chips, so the names being looked for appear
+   immediately below the title
+5. `notes`, if present, rendered as `.axi-prose`
+6. Examples — for each: title, optional right-aligned note, demo in a
+   panel-weight block, code block tucked against the panel's offset so the two
+   read as one object, copy button in the code block's corner
+7. **Knobs** — table sourced from `knobs.mjs`, filtered to this entry's `knobs`
+8. **Rules this answers** — each clause in `rules` rendered as `.axi-notice`
+   with the clause number in the icon slot, deep-linking to `/rules/#rule-<n>`.
+   `marked` derives heading ids from heading text, which would make the anchor
+   depend on the wording of a rule's title and break the link whenever a rule
+   is reworded. The Markdown renderer therefore overrides heading ids for
+   `## <n>. …` headings in RULES.md to the stable form `rule-<n>`.
+
+Section 8 is what distinguishes this from a component list: every page closes by
+pointing at the clauses that dictate why the component looks the way it does.
+
+### Chrome
+
+The mast is `.axi-mast` / `.axi-brand` / `.axi-sigil` / `.axi-tabs` /
+`.axi-search` / `.axi-select`, entirely existing components. The package version
+sits in `.axi-brand__name`'s `<small>`, read from `package.json` at build time.
+The accent switcher is the existing `gallery.js` behaviour, generalised to
+every page and driven by `accents.json`. `gallery.js` is split accordingly: the
+accent-switching portion moves to `docs/site/accent.js` and is loaded by every
+page, while the demo-specific behaviour (menu, drawer, tooltip positioning)
+stays in `gallery.js`, which is loaded only by `/gallery/`.
+
+### Landing page
+
+One job: show, not tell. A hero composed of real components — panel, card with
+its strip, meter, chip row — with the live accent switcher, the three-line
+install directly beneath, and two buttons: "Get started" and "Components". The
+philosophy gets one paragraph and a link to `/rules/`, not a wall of text.
+
+## The README knob table becomes generated
+
+`docs/manifest/knobs.mjs` becomes the source of truth for the per-instance knob
+table. `README.md` carries the table between HTML comment markers, regenerated
+by the build, with a test asserting the file on disk matches what the manifest
+produces. Today that table can drift from `src/` silently; after this it cannot.
+This is the one place the work touches `build.mjs`.
+
+## Enforcement
+
+New `tests/manifest.test.mjs`:
+
+1. Every `.axi-*` class defined in `src/` appears in some entry's `classes`.
+   An undocumented component fails the build. In round two, a new element
+   cannot land without its page.
+2. Every class used in any example's `html` exists in `src/`. Catches typos in
+   the docs and doc pages that outlive their CSS.
+3. Every `--axi-*` custom property read with a fallback in `src/` appears in
+   `knobs.mjs`.
+4. `README.md`'s knob table matches the table generated from `knobs.mjs`.
+5. Entry shape: unique `id`s, non-empty `summary`, `layer` from the known set,
+   `rules` referencing clause numbers that exist in `RULES.md`.
+
+New `tests/site.test.mjs`:
+
+6. The generator emits every expected page for a given manifest.
+7. Example HTML is escaped in code blocks and never executed as markup there.
+8. Highlighting round-trips: stripping the emitted `<span>`s and unescaping
+   returns the original source string exactly.
+9. No emitted page contains a raw absolute `href="/` or `src="/`.
+
+Existing `tests/tokens.test.mjs`, `tests/build.test.mjs` and
+`tests/accents.test.mjs` are unchanged.
+
+Per repository convention, vitest runs with `--maxWorkers=2`.
+
+## Build and deploy
+
+```
+npm run build    scripts/build.mjs   src/*.css       → dist/axi.css, dist/accents.css
+npm run docs     scripts/site.mjs    manifest + md   → _site/
+npm run serve    scripts/serve.mjs   ~25 lines, no dependency, local preview at /
+npm test         vitest run
+```
+
+`.github/workflows/pages.yml`: the current
+`cp -r index.html gallery.js dist _site/` is replaced by `npm run docs`, which
+builds `_site/` itself. The existing per-tag staging loop follows unchanged.
+The guarantee that every published `/vN/axi.css` keeps resolving is untouched,
+because those artifacts are read from git tags and not from the site build.
+
+`.gitignore` gains `_site/`.
+
+## Implementation sequence
+
+Each step is independently verifiable, and the second is expected to fail
+loudly — that is its purpose.
+
+1. Generator skeleton, shell, `docs.css`, one hardcoded component page.
+2. `data.mjs` manifest + enforcement test 1. **Expect failures** naming
+   undocumented classes (`.axi-axis`, `.axi-legend`, `.axi-badge-count`,
+   `.axi-sigil`, `.axi-eyebrow` are the anticipated ones). Group them rather
+   than forcing them into a layer they do not belong to.
+3. Remaining manifest layers: primitives, layout, shells, prose, utilities.
+4. `knobs.mjs`, the knobs section, and the generated README table.
+5. Markdown pipeline: `/start/`, `/theming/`, `/rules/`.
+6. Landing page; move `index.html` to `/gallery/`.
+7. Search index and client search; `llms.txt`.
+8. `pages.yml`, `.gitignore`, `npm run serve`.
+
+## Risks
+
+- **Base-path breakage** — the site works locally and 404s on Pages. Mitigated
+  by the single `url()` helper and test 9.
+- **Manifest tedium** — thirty entries with examples is the bulk of the work.
+  Mitigated by porting the existing markup out of `index.html`, which is
+  already written and already correct.
+- **Enforcement test 1 becoming an obstacle** — if a class legitimately should
+  not be documented, the answer is an explicit `utilities` entry, never an
+  exclusion list in the test. An exclusion list is the escape hatch this
+  repository's existing tests are written specifically to avoid.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@axiapps/axi-design",
-  "version": "1.8.0",
+  "version": "1.10.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

@@ -59,6 +59,8 @@ a { color: inherit; }
   .axi-pill:hover,
   .axi-pill[aria-pressed="true"]:hover,
   .axi-select:hover,
+  .axi-picker__btn:hover,
+  .axi-picker__btn[aria-expanded="true"],
   .axi-card:hover,
   .axi-drawer__close:hover {
     transform: none !important;

package/src/data.css

@@ -183,6 +183,42 @@
   background: var(--axi-series, var(--axi-accent));
 }
 
+/* ---------- ticks ---------- */
+/* A run of yes/no along a timeline: attended or missed, passed or failed,
+   shipped or skipped. This is rule 9 read the other way round - a bar has a
+   length because a quantity has one, and "no" has no length at all. Drawn as
+   a bar it has to be faked with a stub, and a stub reads as "a little bit",
+   which is the same lie as a faded fill. So every event here is one mark of
+   the same size, and what changes between them is only which ink it is drawn
+   in: rule 10's two series, the accent for the fact and the neutral ramp for
+   its absence.
+
+   Neither mark is outlined, which is the one place this departs from the
+   filled/empty pair the language reaches for first. At the size a run of
+   twenty sits in a table row the outline IS the mark - three pixels of edge
+   around one pixel of middle - so the pair would differ in nothing the eye
+   can resolve. A strip drawn large enough to outline is a bar chart, and
+   .axi-bars already is one.
+
+   Marks are a fixed width and never flex: a run of fourteen and a run of
+   three share a column in a table, and the short one has to read as a short
+   run rather than as fourteen fatter events. */
+.axi-ticks {
+  display: inline-flex;
+  align-items: stretch;
+  gap: var(--axi-ticks-gap, 3px);
+  height: var(--axi-tick-h, 15px);
+}
+.axi-ticks__tick {
+  flex: none;
+  width: var(--axi-tick-w, 5px);
+  background: var(--axi-rule);
+  border-radius: var(--axi-radius-sm);
+}
+.axi-ticks__tick--on {
+  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

package/src/primitives.css

@@ -234,8 +234,11 @@
 /* ---------- select ---------- */
 /* The closed box is ours everywhere: strip the native control and draw the
    caret, so a select sits alongside the other controls as just another
-   outlined chip instead of announcing the OS. */
-.axi-select {
+   outlined chip instead of announcing the OS. .axi-picker__btn is the same
+   box worn by a button instead of a <select>; the two share every
+   declaration here so a dropdown reads the same whichever half opens it. */
+.axi-select,
+.axi-picker__btn {
   appearance: none;
   padding: 10px 30px 10px 9px;
   border: var(--axi-border-control) solid var(--axi-ink-line);
@@ -256,7 +259,13 @@
   background-repeat: no-repeat;
   transition: transform .1s, box-shadow .1s;
 }
-.axi-select:hover {
+/* The open trigger keeps the lift. Rule 4 gives the raise to a pointer, but a
+   disclosure that drops back flat the moment the pointer moves into the list
+   it opened severs the two: the lift is what says this box and that popover
+   are one control. */
+.axi-select:hover,
+.axi-picker__btn:hover,
+.axi-picker__btn[aria-expanded='true'] {
   color: var(--axi-text);
   box-shadow: var(--axi-offset-control) var(--axi-offset-control) 0 var(--axi-ink-line);
   transform: translate(-2px, -2px);
@@ -265,7 +274,9 @@
 /* The popup stays OS chrome until a browser lets us style it. Where one does
    (Chromium's base-select), the list is drawn with the same outline and offset
    block as our own popovers, so both dropdown kinds read as one family; where
-   it does not, the closed box above is still ours and the list is native. */
+   it does not, the closed box above is still ours and the list is native -
+   and if that native list is not good enough, .axi-picker below draws the
+   whole thing. */
 @supports (appearance: base-select) {
   /* base-select draws its own ::picker-icon, so the hand-drawn caret above
      would be a second arrow. */
@@ -299,3 +310,98 @@
   .axi-select option:checked { color: var(--axi-text); }
   .axi-select option::checkmark { content: "\2713"; color: var(--axi-accent); font-weight: 900; }
 }
+
+/* ---------- picker ---------- */
+/* The select's other half. Above, the native popup is left as OS chrome
+   wherever `appearance: base-select` is missing - and that is most places
+   today, including every Electron built on a Chromium older than the
+   property. What lands there is a raised list the language cannot reach: no
+   ink outline, no offset block, its own selection colour instead of the
+   accent. That is rule 3 broken by a box we do not own, so the fix is to stop
+   asking the OS to draw it. .axi-picker is a button and a popover wearing the
+   closed box and the list styling from the @supports branch above, so the two
+   kinds are the same dropdown and a consumer picks by what the platform has.
+
+   Prefer the native <select> where it works: it comes with keyboard handling,
+   typeahead, and a popup that can escape the window. This is what you use
+   when it does not.
+
+   Markup contract - the listbox pattern, and the popover carries the panel
+   weight because it is a raised surface, not a control:
+
+     <div class="axi-picker">
+       <button class="axi-picker__btn" aria-haspopup="listbox"
+               aria-expanded="false" aria-controls="months">Jul 2026</button>
+       <div class="axi-picker__pop" id="months" role="listbox" hidden>
+         <button class="axi-picker__opt" role="option" aria-selected="true">
+           Jul 2026
+         </button>
+       </div>
+     </div>
+
+   Like the menu and the tooltip, the language ships no script: `hidden`,
+   `aria-expanded` and `aria-selected` are the whole state, and the consumer
+   toggles them. gallery.js is the reference wiring, arrow keys and Escape
+   included. */
+.axi-picker { position: relative; display: inline-flex; }
+.axi-picker__btn {
+  display: inline-flex; align-items: center;
+  width: 100%;
+  text-align: left;
+}
+.axi-picker__pop {
+  /* Above .axi-mast's z-index: 40, for the same reason .axi-menu__pop is. */
+  position: absolute; top: calc(100% + 9px); left: 0; z-index: 41;
+  /* Never narrower than the box it came out of, and no wider than its
+     longest row needs. A list that shrinks to the text is a list that has
+     moved, and the eye has to find the column again. */
+  min-width: 100%;
+  max-height: 340px; overflow-y: auto;
+  padding: 6px;
+  background: var(--axi-surface-raised);
+  border: var(--axi-border-panel) solid var(--axi-ink-line);
+  border-radius: var(--axi-radius);
+  /* The block falls outside the popover's own box. An ancestor that clips -
+     a scrolling pane, a panel with overflow: hidden - eats it, and the only
+     shadow on the screen is the one that goes missing. */
+  box-shadow: var(--axi-offset-panel) var(--axi-offset-panel) 0 var(--axi-ink-line);
+}
+.axi-picker__pop[hidden] { display: none; }
+/* A popover cannot always live beside its trigger. Inside a pane that scrolls
+   or a panel that clips, `position: absolute` puts the list where the
+   overflow can eat it - and the offset block falls outside the popover's box,
+   so the block is the first thing to go. The way out is the tooltip's
+   contract: append the popover to <body> and set left/top from script, having
+   measured the trigger. The box is unchanged; only who positions it moves. */
+.axi-picker__pop--fixed { position: fixed; }
+.axi-picker__opt {
+  display: flex; align-items: center; gap: 9px;
+  width: 100%;
+  padding: 8px 9px;
+  border: 0;
+  border-radius: var(--axi-radius-sm);
+  background: transparent;
+  color: var(--axi-text-dim);
+  font: var(--axi-t-label);
+  font-size: 12.5px;
+  letter-spacing: var(--axi-ls-label);
+  text-transform: uppercase;
+  text-align: left;
+  cursor: pointer;
+}
+/* The tick is in every row, inked only in the chosen one. Give it to the
+   selected row alone and every label shifts by its width as the choice moves,
+   which turns picking an option into the list twitching. */
+.axi-picker__opt::before {
+  content: "\2713";
+  color: transparent;
+  font-weight: 900;
+}
+.axi-picker__opt:hover, .axi-picker__opt:focus {
+  background: var(--axi-ground); color: var(--axi-text);
+}
+/* The page-wide focus ring sits 2px outside its element; inside a popover
+   this tight that is 2px into the neighbouring row, so pull it back in. */
+.axi-picker__opt:focus-visible { outline-offset: -3px; }
+.axi-picker__opt[aria-selected='true'] { color: var(--axi-text); }
+.axi-picker__opt[aria-selected='true']::before { color: var(--axi-accent); }