Appearance
Utility & Error Pages
The pages nobody designs until they need them. Twelve ship, and none of them uses the admin shell.
The catalogue
| Page | Path | Status code | Shell |
|---|---|---|---|
| 404 Not found | html/pages/utility/404.html | 404 | util-open |
| 403 Forbidden | html/pages/utility/403.html | 403 | util-open |
| 500 Server error | html/pages/utility/500.html | 500 | util-open |
| 503 Maintenance | html/pages/utility/maintenance.html | 503 | util-open |
| Offline | html/pages/utility/offline.html | — | util-open |
| Coming soon | html/pages/utility/coming-soon.html | 200 | util-open |
| Pricing | html/pages/utility/pricing.html | 200 | public-open |
| FAQ | html/pages/utility/faq.html | 200 | public-open |
| Help centre | html/pages/utility/help.html | 200 | public-open |
| Terms & privacy | html/pages/utility/legal.html | 200 | public-open |
| Changelog | html/pages/utility/changelog.html | 200 | public-open |
| Status | html/pages/utility/status.html | 200 | public-open |
Source lives in html/_src/utility-*.html; the paths above are build outputs. Edit the source and run npm run build:html.
Six of these were a table row before they were a page. The catalogue carried no status column, so all twelve read as built while pricing, FAQ, help, legal, changelog and status sent readers to a 404.
npm run check:inventorynow fails the build when a listed path does not resolve, which is what turning those six into real pages had to satisfy.
Which shell each page uses
| Shell partial | Pages | What it is |
|---|---|---|
util-open / util-close | 404, 403, 500, maintenance, offline, coming soon | <head> and an open <body>. No chrome, no adminvora.js. |
public-open / public-close | Pricing, FAQ, help, legal, changelog, status | .av-public — a sticky bar, a 1080px centred <main>, a footer. No sidebar. |
Both are deliberate, for two different reasons.
An error page must not depend on the app — see Error pages must not depend on the app. A 500 renders when the thing that draws the sidebar is what broke, and a maintenance page renders when there is no session to draw a sidebar for. util-close.html therefore ends the document without loading the runtime; everything on those six pages is markup and CSS, and each page's small behaviour is an inline <script> of its own.
The six public pages are pre-login. Pricing, the FAQ, the help centre, the legal texts, the changelog and the status page are what a product shows somebody who has not signed in yet — there is no workspace to be inside and no sidebar to collapse. A person reading your terms of service is not in your application.
What they are not is a second design system. Every block on them is a component the admin already ships — .av-card, .av-badge, .av-btn, .av-table, .av-timeline, .av-option-list, the same tokens, the same presets, the same light and dark modes. Re-theme once and both follow. That is the same argument the storefront pages settled, and it is why src/scss/layout/_public.scss is a bar, a centred main and a footer: the page rhythm is one rule.
scss
/* src/scss/layout/_public.scss — the same rhythm the app shell gives
`.av-content > .container-fluid`, at --av-space-8 rather than --av-space-4,
because a marketing page breathes and a dashboard packs. Inside :where() the
ancestor contributes nothing, so a component that wants to sit flush against
its neighbour still can. */
:where(.av-public__main) > * + * { margin-block-start: var(--av-space-8); }
/* The reading measure, for a page that is prose rather than panels. The legal
texts set it; pricing and status do not. */
.av-public__main--narrow { max-inline-size: 760px; }.av-footer is the one shell part not reused, and for a concrete reason: its first declaration is grid-area: footer, which belongs to the shell's grid and means nothing outside it. A class whose first line is a grid area is a class that belongs to one grid. .av-public__foot is the public equivalent.
Error pages
One template, six configurations. This is html/_src/utility-404.html, with the build's {{ root }} placeholders already resolved.
html
<main class="av-error" id="main">
<a href="../../../index.html" class="av-brand av-error__brand">
<img class="av-brand__mark" src="../../../src/img/logo-mark.svg" alt="" width="32" height="32">
<span class="av-brand__text">AdminVora</span>
</a>
<div class="av-error__inner">
<!-- The numeral is decorative; the <h1> carries the meaning. -->
<p class="av-error__code" aria-hidden="true">404</p>
<h1 class="av-error__title">Page not found</h1>
<p class="av-error__text">
The page you are looking for does not exist or has been moved.
Check the address, or head back to somewhere familiar.
</p>
<div class="av-error__actions">
<a class="av-btn av-btn--primary av-btn--lg av-btn--pill" href="../dashboards/analytics.html">
<svg class="av-icon av-icon--sm" aria-hidden="true" viewBox="0 0 24 24">
<path d="M4 11l8-7 8 7"/><path d="M6 10v10h12V10"/>
</svg>
Go to dashboard
</a>
<button class="av-btn av-btn--outline av-btn--lg av-btn--pill" type="button" id="goBack">
Go back
</button>
</div>
<p class="av-error__help">
Still stuck? <a href="../auth/login.html">Sign in again</a>.
</p>
</div>
</main>
<script>
// No inline handlers (CSP); this page deliberately loads no other script.
document.getElementById('goBack').addEventListener('click', function () { history.back(); });
</script>Icons are inline <svg> with a viewBox and aria-hidden="true". There is no sprite in this build and no <use href="#…"> to point at — see Iconography.
The three openers
.av-error__inner opens with one or two of these, and which ones depend on whether the page has a status code to state.
| Opener | Used by | What it is |
|---|---|---|
.av-error__code | 404, 403, 500 | <p class="av-error__code" aria-hidden="true">404</p> |
.av-error__status | maintenance, offline | A pill: a pulsing .av-error__dot and a phrase |
.av-error__badge | maintenance, offline, coming soon | A 72px circle holding one .av-icon |
html
<!-- Maintenance uses the warning default; offline adds --danger. -->
<p class="av-error__status av-error__status--danger">
<span class="av-error__dot" aria-hidden="true"></span>
No connection
</p>
<span class="av-error__badge" aria-hidden="true">
<svg class="av-icon" viewBox="0 0 24 24">
<path d="M12 3l2.2 5.6L20 10l-4.4 3.6L16.8 20 12 16.9 7.2 20l1.2-6.4L4 10l5.8-1.4L12 3z"/>
</svg>
</span>The dot animation is av-pulse, declared in _error-page.scss beside the only rule that uses it. @keyframes names are global, so a component owns its own rather than borrowing one.
Content per page
| Page | Opener | Title | Actions |
|---|---|---|---|
| 404 | 404 | Page not found | Go to dashboard · Go back |
| 403 | 403 | Access denied | Go to dashboard · Sign in as someone else |
| 503 | pill + badge | We are upgrading a few things | Check again · View status page |
| 500 | 500 | Something went wrong | Try again · Go to dashboard |
| Offline | pill + badge | You are offline | Retry now · Go to dashboard |
| Coming soon | badge | Something new is on the way | Notify me (email field) |
Every one of them offers a way forward. "Access denied" that only says no is a dead end with a brand on it, so the 403 names the reader's current role in .av-error__help — they now know what to ask their administrator for.
Error pages must not depend on the app
An error page that loads the full application bundle will fail during the exact outage it exists to handle.
| Rule | Reason | How it is met here |
|---|---|---|
| No application JavaScript | The bundle may be what failed | util-close.html omits adminvora.js |
| No API calls | The API may be what failed | Every figure is in the markup |
| Static file, servable directly | The application may be down | Plain HTML in html/pages/utility/ |
| Theme correct before first paint | A flash of the wrong mode is a second failure | The shared head partial keeps the synchronous boot script |
That last row is the one that gets lost. These pages share html/_partials/head.html with every other page rather than carrying a hand-trimmed <head>, because a hand-copied boot script quietly stops applying the stored preset the next time the real one changes.
For a genuinely zero-request outage page, inline the compiled stylesheet into that copy of the file:
html
<style>/* contents of src/css/adminvora.css */</style>Then serve it from the web server rather than the application:
nginx
error_page 500 502 503 504 /500.html;
location = /500.html { root /var/www/static; internal; }Support reference
utility-500.html prints its reference as markup:
html
<p class="av-error__help">
If this keeps happening, quote reference
<code class="av-kbd">INC-4F2A91</code> when you contact support.
</p>A reference turns "it's broken" into a one-query support ticket. It is the single most valuable thing an error page can show.
To make it copyable, remember which shell you are in. [data-av-clipboard] is a runtime module and the error pages do not load the runtime, so on those six pages write the four lines yourself:
html
<code class="av-kbd" id="ref">INC-4F2A91</code>
<button class="av-btn av-btn--sm av-btn--outline" type="button" id="copyRef">Copy reference</button>
<script>
document.getElementById('copyRef').addEventListener('click', function () {
navigator.clipboard.writeText(document.getElementById('ref').textContent.trim());
});
</script>On a page that does load the runtime, use the module instead. Its value is a selector, not the text, so the copied string and the rendered string cannot drift apart:
html
<code class="av-kbd" id="ref">INC-4F2A91</code>
<button class="av-btn av-btn--sm av-btn--outline" type="button"
data-av-clipboard="#ref">Copy reference</button>Warning — never display a stack trace, SQL query, file path or framework version to an end user. Those belong in your logs. In production,
APP_DEBUGmust befalse.
Maintenance and offline
utility-maintenance.html states the return time in the copy and gives two ways out:
html
<div class="av-error__actions">
<button class="av-btn av-btn--primary av-btn--lg av-btn--pill" type="button" id="retry">
<svg class="av-icon av-icon--sm" aria-hidden="true" viewBox="0 0 24 24">
<path d="M4 12a8 8 0 1 0 2.5-5.8"/><path d="M4 4v4h4"/>
</svg>
Check again
</button>
<a class="av-btn av-btn--outline av-btn--lg av-btn--pill" href="../utility/status.html">
View status page
</a>
</div>
<script>
document.getElementById('retry').addEventListener('click', function () { location.reload(); });
</script>The window is written out as 04:00 UTC rather than rendered from a timestamp, because the page cannot use [data-av-relative-time] — that is a runtime module and this page has no runtime. If you want the visitor's own timezone, the page is already carrying an inline script; add four lines to it and select on time[datetime] rather than inventing a data-av-* hook nothing else reads:
js
document.querySelectorAll('main time[datetime]').forEach((el) => {
const d = new Date(el.getAttribute('datetime'));
el.textContent = d.toLocaleString(navigator.language, { dateStyle: 'medium', timeStyle: 'short' });
});Serve maintenance with 503 and a Retry-After header so search engines and monitoring do not treat it as a permanent failure:
HTTP/1.1 503 Service Unavailable
Retry-After: 1800The offline page is the same template with --danger on the status pill. AdminVora ships no service worker — it is a static template, and registering one is a decision about your deployment — so if you want the offline page to actually appear, this is the smallest thing that does it:
js
// service-worker.js — yours to add; nothing in this template registers one.
const CACHE = 'adminvora-shell-v1';
const SHELL = ['/html/pages/utility/offline.html', '/src/css/adminvora.css'];
self.addEventListener('install', (e) => {
e.waitUntil(caches.open(CACHE).then((c) => c.addAll(SHELL)));
});
self.addEventListener('fetch', (e) => {
if (e.request.mode !== 'navigate') return;
e.respondWith(fetch(e.request).catch(() => caches.match('/html/pages/utility/offline.html')));
});Inside the app — where the runtime is loaded — connection changes are a toast:
js
addEventListener('online', () => AdminVora.toast.success('Back online'));
addEventListener('offline', () => AdminVora.toast.warning(
'You are offline. Changes will be saved when you reconnect.', { duration: 0 }));duration: 0 keeps it until dismissed. AdminVora.toast is one of the ten public members; see Feedback & Overlays.
Pricing
The public pricing page uses [data-av-plans] — the same contract the in-app upgrade screen uses, so the two cannot quote different numbers.
html
<div class="av-plans" data-av-plans data-av-state="monthly" data-av-currency="EUR">
<div class="av-plans__cycle">
<div class="av-segmented" role="radiogroup" aria-label="Billing cycle">
<label>
<input type="radio" name="av-cycle" value="monthly" data-av-cycle="monthly" checked>
Monthly
</label>
<label>
<input type="radio" name="av-cycle" value="yearly" data-av-cycle="yearly">
Annual
</label>
</div>
<span class="av-plan-save">Two months free on annual billing</span>
</div>
<div class="av-plan-grid">
<section class="av-pricing-card av-pricing-card--featured">
<span class="av-pricing-card__ribbon">Most chosen</span>
<h2 class="av-pricing-card__name">Growth</h2>
<p class="av-pricing-card__price">
<span data-av-plan-price data-av-price-monthly="4900" data-av-price-yearly="4083">€49.00</span>
<span class="av-pricing-card__period" data-av-plan-period>/month</span>
</p>
<p class="av-pricing-card__note">For a team that has stopped sharing one login.</p>
<ul class="av-pricing-card__features">
<li>3 workspaces, 15 seats</li>
<li>Roles, permissions and audit log</li>
</ul>
<a class="av-btn av-btn--primary av-pricing-card__cta" href="../auth/login.html#signup">
Start free trial
</a>
</section>
</div>
</div>Three rules are load-bearing here.
Both prices are in the markup. data-av-price-monthly and data-av-price-yearly are integer minor units, and the annual figure is authored rather than divided by twelve in the browser. "Monthly over twelve, less the discount" is a pricing decision; computing it client-side produces a number that disagrees with the invoice by a rounding cent.
The rendered price is Intl, never hand-formatting. The module reads data-av-currency off the group and formats through AdminVora.utils.formatCurrency.
The period label changes with the cycle. [data-av-plan-period] defaults to /month and /month, billed yearly; override per card with data-av-period-monthly / data-av-period-yearly. Switching the radio also announces the change through AdminVora.a11y, because a price that silently rewrites itself is a change a screen-reader user never hears.
The comparison table says words, not ticks
html
<div class="av-card">
<div class="av-table-wrap">
<table class="av-table">
<caption class="av-visually-hidden">Feature comparison across the three plans</caption>
<thead>
<tr>
<th scope="col">Feature</th>
<th scope="col">Starter</th><th scope="col">Growth</th><th scope="col">Scale</th>
</tr>
</thead>
<tbody>
<tr><th scope="row">Seats</th><td>3</td><td>15</td><td>50</td></tr>
<tr><th scope="row">SSO and SCIM</th><td>Not included</td><td>Not included</td><td>Yes</td></tr>
</tbody>
</table>
</div>
</div>A tick and a cross need visually-hidden text to mean anything to a screen reader, and a legend to mean anything to a sighted reader in a hurry. Writing "Yes" and "Not included" removes both problems and one component. Every row is a row header (<th scope="row">), so a cell read out of context still says which feature it belongs to.
FAQ
The questions are disclosures, and the topic chips are initNotifFilters — the same module the notifications drawer and the audit log use. There is no FAQ module.
html
<div class="av-stack-4" data-av-notif-filter-group data-av-notif-noun="question">
<div class="av-facets__chips" role="group" aria-label="Filter questions by topic">
<button class="av-filter-chip" type="button" data-av-notif-filter="all" aria-pressed="true">All</button>
<button class="av-filter-chip" type="button" data-av-notif-filter="billing" aria-pressed="false">Billing</button>
</div>
<div class="av-faq">
<p class="av-faq__topic" data-av-notif-group>Billing</p>
<div class="av-faq__item" data-av-notif-item data-av-notif-kind="billing">
<button class="av-faq__q" type="button" data-av-collapse
aria-expanded="false" aria-controls="faq-1">
<span>How does the free trial work?</span>
<svg class="av-icon av-icon--sm av-disclosure__caret" aria-hidden="true" viewBox="0 0 24 24">
<path d="M6 9l6 6 6-6"/>
</svg>
</button>
<div class="av-faq__a av-disclosure__panel" id="faq-1" data-av-state="collapsed">
<p>Fourteen days, every feature, no card.</p>
</div>
</div>
</div>
</div>data-av-notif-noun="question" is why the filter announcement says "questions" rather than "notifications". A module hard-coded to its first caller's noun is the one thing a generalised module gets wrong in a way only a screen-reader user ever hears.
[data-av-collapse] pairs aria-expanded on the button with data-av-state on the panel it names through aria-controls. A question that opens without the attribute changing is a picture of an accordion rather than one.
One card holding rows, not a card per question: twenty cards read as twenty things to decide between when it is one list to scan.
Add structured data for search engines:
html
<script type="application/ld+json">
{
"@context": "https://schema.org",
"@type": "FAQPage",
"mainEntity": [{
"@type": "Question",
"name": "How does the free trial work?",
"acceptedAnswer": { "@type": "Answer", "text": "Fourteen days, every feature, no card." }
}]
}
</script>Help centre
Topics are .av-kit-tile links laid out in .av-grid--stats. The search control is not a search box:
html
<button class="av-search-trigger" type="button" data-av-palette-open
aria-label="Search pages and commands">
<svg class="av-icon av-icon--sm" aria-hidden="true" viewBox="0 0 24 24">
<circle cx="10.5" cy="10.5" r="6.5"/><path d="M15.5 15.5L21 21"/>
</svg>
<span class="av-search-trigger__text">Search pages and commands</span>
<span class="av-search-trigger__kbd"><kbd class="av-kbd">Ctrl</kbd><kbd class="av-kbd">K</kbd></span>
</button>[data-av-palette-open] opens the command palette, which already searches every page in the product from one table. A help centre whose search filters nothing is the dead-control defect on the page people reach when something has already gone wrong.
Changelog
.av-timeline, not a list of cards: the dates are the spine of the page, and a card per release makes twelve boxes to compare when it is one column to scan. The version is a badge because it is a label, not a heading.
html
<ol class="av-timeline" role="list">
<li class="av-timeline__item av-timeline__item--success">
<span class="av-timeline__marker" aria-hidden="true">
<svg class="av-icon av-icon--xs" viewBox="0 0 24 24"><path d="M5 12l5 5L20 7"/></svg>
</span>
<div class="av-timeline__body">
<p class="av-timeline__title">
<span class="av-badge av-badge--success">1.4.0</span>
Filters, saved views and CSV export on every table
</p>
<p class="av-timeline__meta">21 August 2026</p>
<p>
The filter state lives in the URL, so a filtered table is a link you can send, and the
export writes the filtered set rather than the page you are looking at.
</p>
</div>
</li>
</ol>--success, --info and --warning colour the marker. Every entry says what it changes for somebody using the product; internal refactors belong in the repository.
Status
The headline state is one role="status" alert; the per-service detail is an option list.
html
<div class="av-alert av-alert--success-soft" role="status">
<svg class="av-icon av-alert__icon" aria-hidden="true" viewBox="0 0 24 24">
<circle cx="12" cy="12" r="9"/><path d="M8.5 12.3l2.4 2.4 4.6-4.9"/>
</svg>
<div class="av-alert__body">
<p class="av-alert__title">No incidents in progress</p>
<p class="av-alert__text">
99.98% availability over the last 90 days, measured as successful requests rather than
as pings.
</p>
</div>
</div>
<ul class="av-option-list">
<li class="av-option">
<div class="av-option__body">
<span class="av-status-dot av-status-dot--away" aria-hidden="true"></span>
<div>
<p class="av-option__title">Exports</p>
<p class="av-option__text">CSV and attachment exports, queued</p>
</div>
</div>
<span class="av-badge av-badge--warning-soft">Degraded · 99.62%</span>
</li>
</ul>The dot is decorative and the badge carries the words, so the state survives being read aloud and survives a reader who cannot separate amber from green. Degraded is not down — a service answering slowly enough that people notice needs its own state, or every slow week gets reported as an outage.
Incident history is .av-log, kept rather than cleared:
html
<ol class="av-log" role="list">
<li class="av-log__date">August 2026</li>
<li class="av-log__item">
<span class="av-log__mark av-log__mark--warning" aria-hidden="true">
<svg class="av-icon av-icon--xs" viewBox="0 0 24 24">
<path d="M12 4l9 16H3l9-16z"/><path d="M12 10v4"/>
</svg>
</span>
<div class="av-log__body">
<p class="av-log__title">Exports queued for up to 20 minutes</p>
<p class="av-log__text">
Exports completed throughout; none was lost. Worker concurrency raised, and queue depth is
now alerted on before it is visible.
</p>
</div>
<span class="av-log__meta">4 Aug · 38 min</span>
</li>
</ol>A status page that only shows today is a status page nobody can use to decide whether to trust it.
Legal pages
Legal is the one public page that sets the narrow measure. "narrow": true in the page's front matter puts .av-public__main--narrow on <main> and caps it at 760px, because this is the one place in an admin template where long-form reading typography matters.
html
<!--av
{
"title": "Terms and privacy",
"out": "pages/utility/legal.html",
"navUnlisted": true,
"narrow": true
}
av-->The jump rail is [data-av-scrollspy]:
html
<nav class="av-jump" data-av-scrollspy aria-label="On this page">
<a class="av-jump__link" href="#terms">Terms of service</a>
<a class="av-jump__link" href="#privacy">Privacy</a>
<a class="av-jump__link" href="#processors">Sub-processors</a>
</nav>The module sets aria-current="true" on the link whose section the reader is in — the half a purely visual highlight leaves out. A legal page is the one place people arrive looking for a single clause, so the rail matters more here than on a page somebody reads top to bottom.
What the page holds is a table, not paragraphs, wherever the answer is a lookup:
html
<table class="av-table">
<caption class="av-visually-hidden">Personal data held, purpose, and retention</caption>
<thead>
<tr><th scope="col">What</th><th scope="col">Why</th><th scope="col">How long</th></tr>
</thead>
<tbody>
<tr>
<th scope="row">Name and email</th>
<td>To let you sign in and to address you</td>
<td>While the account exists, then 30 days</td>
</tr>
</tbody>
</table>Keep the sub-processor list in the document rather than on a page that can change quietly.
Checklist
- [ ] Error pages load no application JavaScript, and each page's behaviour is its own inline script
- [ ] Error pages are servable directly by the web server
- [ ] Correct HTTP status codes (404, 403, 500, 503 +
Retry-After) - [ ] Large numerals are
aria-hidden; the<h1>carries the meaning - [ ] Every error page offers a way forward, not just an apology
- [ ] A support reference is shown, and copyable without the runtime where there is none
- [ ] No stack traces, SQL or file paths in production
- [ ] Icons are inline
<svg>witharia-hidden="true"— there is no sprite to reference - [ ] Both prices are authored as integer minor units; nothing is divided by twelve in the browser
- [ ] Comparison cells say "Yes" / "Not included" rather than a tick that needs a legend
- [ ] FAQ questions use
[data-av-collapse], soaria-expandedactually changes - [ ] Status colour is never the only carrier — the badge says the word
- [ ] Legal pages set
"narrow": trueand use[data-av-scrollspy]for the jump rail
Read next: Static HTML.