@axiapps/axi-design 1.7.1 → 1.9.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,15 +1,22 @@
 {
   "name": "@axiapps/axi-design",
-  "version": "1.7.1",
+  "version": "1.9.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" },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/darkharasho/axi-design.git"
+  },
   "homepage": "https://darkharasho.github.io/axi-design/",
-  "engines": { "node": ">=22" },
+  "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" },
+  "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",
@@ -34,5 +41,7 @@
     "build": "node scripts/build.mjs",
     "test": "vitest run"
   },
-  "devDependencies": { "vitest": "^2.1.0" }
+  "devDependencies": {
+    "vitest": "^2.1.0"
+  }
 }

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/shells.css

@@ -120,6 +120,28 @@
 .axi-menu__pop label:hover { background: var(--axi-ground); color: var(--axi-text); }
 .axi-menu__pop input { margin: 3px 0 0; accent-color: var(--axi-accent); }
 
+/* ---------- tooltip ---------- */
+/* One line of ink on the darkest surface in the language, so it reads over
+   anything it lands on. The class draws the box only; coordinates come from
+   the consumer's script (measure the trigger, set left/top — gallery.js is
+   the reference wiring). Two contracts travel with it: the element is
+   appended to <body>, never inside the component it annotates, because
+   position: fixed re-anchors to any transformed ancestor and rule 4 makes
+   every hovered ancestor transformed; and it never carries information that
+   exists nowhere else, because a keyboard or touch user may never see it. */
+.axi-tooltip {
+  position: fixed;
+  z-index: 99999;
+  padding: 5px 8px;
+  background: var(--axi-ink-line);
+  color: var(--axi-text);
+  border: var(--axi-border-hairline) solid var(--axi-rule);
+  border-radius: var(--axi-radius-sm);
+  font: var(--axi-t-micro);
+  white-space: nowrap;
+  pointer-events: none;
+}
+
 /* ---------- card ---------- */
 .axi-card {
   position: relative; overflow: hidden;