Skip to content

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 ​

PageCovers
OverviewThe index, the install snippet, and the naming conventions
FoundationsSemantic colour, ramps, every preset, type, spacing, radius, elevation, motion
ButtonsEmphasis, status roles, sizes, icons, states, layout, class reference
FormsBoxed and underline fields, input groups, toggles, choice cards, live validation
Data displayBadges, avatars, cards, stat cards, progress, lists, timeline, money, skeletons
LayoutThe shell, sidebar, topbar, page header, grid helpers, split panes, theme axes
TablesHeaders and scope, the overflow wrapper, numeric columns, totals, the data grid
NavigationBreadcrumbs, tabs, dropdowns, pagination, disclosure, command palette
FeedbackAlerts, toasts, modals, confirm dialogs, tooltips, live announcements
ChartsTen types from one hook, coloured from the tokens so a preset change re-themes them
Icons187 inline stroke icons, click to copy
Animated iconsThe 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:

FieldDefaultMeaning
TitlenoneThe <h3> above the example. Omit for an unlabelled one.
NotenoneOne sentence under the title. Backticked spans become <code>.
Layoutrowrow, 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.

HookDoes
[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 ​

  1. Create html/_src/ui-<name>.html with an <!--av … av--> header whose nav matches a sidebar row.
  2. Add the row to html/_partials/sidebar.html under the UI kit title. The build fails on a nav value no row reads, so a typo cannot ship as a silently dead active state.
  3. Add the built path to PAGES in tests/lib/server.mjs — that list is hand-maintained, and a page missing from it is invisible to the entire gate.
  4. Add a tile to the overview page and an entry to html/_partials/palette.html.
  5. Run npm run build:html && npm test, then npm run test:visual:update once the new baselines have been reviewed.

See also ​

Documentation for @creativeigniter/adminvora