Appearance
Component Reference Pages
The UI kit is the browsable half of this documentation: every component rendered live, next to the exact markup that rendered it. It lives under html/pages/ui/ and is reachable from the UI kit section of the sidebar, from the command palette, and from index.html.
These pages exist so that reading about a component and using one are the same action. A reader opens the page, finds the variant that matches what they are building, presses Copy, and pastes. There is no step in between where they translate prose into markup and get it slightly wrong.
The pages
| Page | Covers |
|---|---|
| Overview | The index, the install snippet, and the naming conventions |
| Foundations | Semantic colour, ramps, every preset, type, spacing, radius, elevation, motion |
| Buttons | Emphasis, status roles, sizes, icons, states, layout, class reference |
| Forms | Boxed and underline fields, input groups, toggles, choice cards, live validation |
| Data display | Badges, avatars, cards, stat cards, progress, lists, timeline, money, skeletons |
| Layout | The shell, sidebar, topbar, page header, grid helpers, split panes, theme axes |
| Tables | Headers and scope, the overflow wrapper, numeric columns, totals, the data grid |
| Navigation | Breadcrumbs, tabs, dropdowns, pagination, disclosure, command palette |
| Feedback | Alerts, toasts, modals, confirm dialogs, tooltips, live announcements |
| Charts | Ten types from one hook, coloured from the tokens so a preset change re-themes them |
| Icons | 187 inline stroke icons, click to copy |
| Animated icons | The CSS-only motion set — see Animated Icons |
Every page opens with a jump bar linking to its own sections, so a long page is still navigable without a second grid track for a side rail:
html
<nav class="av-jump av-jump--sticky" data-av-scrollspy aria-label="On this page">
<a class="av-jump__link" href="#emphasis">Emphasis</a>
<a class="av-jump__link" href="#sizes">Sizes</a>
</nav>.av-jump alone is a row of chips that wraps. .av-jump--sticky pins it to the top of the scroll area as one row that scrolls sideways, and lands a jumped-to section below it rather than under it. [data-av-scrollspy] sets aria-current="true" on the link for the section in view, keeps that link visible in a sideways-scrolling bar, and picks the last link once the page reaches its end.
Writing an example
Examples are not written twice. A demo beside a hand-maintained snippet is two copies of one thing, and the copy nobody looks at is the one that rots — a snippet that no longer matches the demo next to it is worse than no snippet, because it is trusted.
tools/build-html.mjs provides one construct that emits both from a single block:
html
{{< Title | A note about when to use it | layout }}
<button class="av-btn av-btn--primary" type="button">Primary</button>
{{/< }}All three head fields are optional:
| Field | Default | Meaning |
|---|---|---|
| Title | none | The <h3> above the example. Omit for an unlabelled one. |
| Note | none | One sentence under the title. Backticked spans become <code>. |
| Layout | row | row, stack or plain — see below. |
The build renders that into a preview, a Code toggle, a Copy button, and a <pre> holding the same markup, HTML-escaped:
html
<div class="av-example">
<div class="av-example__head">…title, note, tools…</div>
<div class="av-example__preview av-example__preview--row">…live markup…</div>
<pre class="av-code av-example__code" id="av-ex-1" hidden><code>…escaped markup…</code></pre>
</div>Layout is declared in the head, never in the markup
row lays the preview out as a wrapping flex row, stack as a vertical grid, and plain leaves the children to flow as written.
Put the layout in the head rather than wrapping the example in a container. A snippet the reader pastes should be the component and nothing else; a stray <div class="av-demo-row"> in the copied source is exactly the kind of thing that reaches production and stays there.
Expansion runs last
Examples are expanded after includes, conditionals and variable substitution. That ordering is deliberate:
- The code panel shows what a reader can actually paste —
{{ root }}has already resolved to a real path rather than a template tag they would have to know about. - The earlier passes never encounter
{{<, so the build's stray-tag guard still catches a mistyped marker instead of shipping it into the page.
The head is one line
The head is matched non-greedily and confined to a single line. Both halves matter: notes are prose about CSS and routinely contain a brace — the reset's `* { margin: 0 }` — so the head cannot simply be "anything but }"; and without the line anchor a malformed opener would swallow the body and the next example with it.
Runtime behaviour
initExamples() and initIconCopy() are content modules, registered in AdminVora.init(), so they survive a route change in the SPA starter kits.
| Hook | Does |
|---|---|
[data-av-example-toggle] | Reveals the panel named by aria-controls; keeps aria-expanded in step and swaps the label between Code and Hide |
[data-av-example-copy] | Copies the text of [data-av-example-target], announces the result, and shows Copied for two seconds |
[data-av-icon-copy] | Copies the cell's rendered <svg> — the element itself, not a string stored beside it |
Copying works in three places that disagree
Over HTTPS, over http://localhost, and from a file:// URL opened straight off disk — which is how this template is meant to be openable, and where navigator.clipboard is simply absent. copyText() tries the Clipboard API, falls back to a detached <textarea> and document.execCommand('copy'), and reports failure rather than swallowing it. A Copy button that lies is worse than one that admits it could not.
When the clipboard is unavailable the button also reveals the source panel before saying "Press Ctrl+C" — that instruction is useless against text the reader cannot see.
Adding a page
- Create
html/_src/ui-<name>.htmlwith an<!--av … av-->header whosenavmatches a sidebar row. - Add the row to
html/_partials/sidebar.htmlunder the UI kit title. The build fails on anavvalue no row reads, so a typo cannot ship as a silently dead active state. - Add the built path to
PAGESintests/lib/server.mjs— that list is hand-maintained, and a page missing from it is invisible to the entire gate. - Add a tile to the overview page and an entry to
html/_partials/palette.html. - Run
npm run build:html && npm test, thennpm run test:visual:updateonce the new baselines have been reviewed.
See also
- Component Index — every component, its class, and its status
- Animated Icons — the CSS-only motion set