Appearance
CLI & Scripts
Every script in package.json, what it does, and when to run it.
Commands you will use day to day come first; the gates near the end are what npm run lint and CI run for you.
Daily use
| Command | Purpose |
|---|---|
npm run dev | Static file server at http://localhost:5173. No HMR and no watch — the build is explicit, so re-run npm run build:html or npm run build:css and refresh. |
npm run build | tokens → CSS → check:tokens → HTML assembly. Does not produce dist/; that is build:dist. |
npm run build:dist | Assembles dist/, the redistributable bundle every starter kit copies. |
npm run serve | The same static server as dev, under the name a deployment script expects. Identical behaviour — kept because "serve" is what half of package.json conventions call it. |
npm run lint | Runs lint:css, lint:tokens, check:components, check:hooks, check:globals, check:bundle, check:scss-api, check:config-keys, check:demo-dates, check:page-classes, check:inline-styles, check:scripts, check:licenses, check:docs-classes, check:inventory, check:docs-refs, check:facets, check:icons, check:customizer, check:breadcrumbs, check:integrations, check:layouts, check:runtime-split, check:scss-source, check:kit-coverage and check:api-surface in sequence. |
npm test | The full browser gate: pages, dropdowns, charts, select, mask, lightbox, uploader, map, tabulator, virtual, RTL, contrast, starters, visual. Not a watcher — it runs once and exits. |
Setup & assets
| Command | Purpose |
|---|---|
npm run setup | One-shot post-clone setup: vendor + images + build + hooks. Idempotent. |
npm run hooks | Points git at .githooks/, whose pre-push refuses a direct push to main. setup runs it. |
npm run tokens | Runs tools/build-tokens.mjs → src/css/tokens.css. The values live in the generator; there is no tokens/**/*.json layer yet, and no .d.ts or Figma output. |
npm run vendor | Copies pinned third-party files from node_modules into src/vendor/, verifies SHA-256 checksums, and regenerates NOTICE.md. |
npm run vendor:audit | Re-checksums src/vendor/ against the manifest without copying. Fails on drift. Runs in CI. |
npm run vendor:update | Bumps a vendored library, recomputes its checksum and rewrites the manifest. |
npm run images | Draws the placeholder product wells into src/img/products/ from tools/placeholders.manifest.json. One transparent SVG per product, carrying a photo glyph and the product's name; the tinted well underneath is painted from tokens, so a well themes itself. |
npm run images:audit | Regenerates every well in memory and fails on any drift — a hand-edited file, a missing one, or a file on disk the manifest does not list. That last direction is the one that ships. Runs in CI. |
Build targets
| Command | Output |
|---|---|
npm run build:css | src/scss/** → src/css/adminvora.css and .min.css. No RTL build: direction is handled at runtime by [dir="rtl"] rules, not a second stylesheet. |
npm run build:html | Assembles html/_src/** + html/_partials/** → html/pages/** and html/_qa/. The built pages are gitignored; npm run setup and npm run build produce them. |
npm run build:dist | Assembles dist/ — the compiled bundle, its vendored dependencies, LICENSE.md and NOTICE.md. Warns if LICENSE.md still holds __…__ placeholders. |
npm run build:dist:release | The same assembly, but refuses on an unfilled licence placeholder rather than warning. pack:starters runs it, so an incomplete licence cannot reach a release zip. |
npm run build:html-dist | Assembles html-dist/ — the demo pages as something a customer can open. Runs build:dist first, then rewrites every src/** link in the built pages to a bundled assets/ copy of it, and fails if a single reference does not resolve. html/ on its own links a source tree that does not ship. |
npm run build:demo | The same as build:html-dist, into html-dist-demo/ instead, with the paid-only files pruned — the SCSS source and the unminified tokens.css. This is the folder that goes on a public demo URL; html-dist/ is the one a customer receives. |
npm run build:site | Assembles landing-dist/ — the marketing site in landing-website/, plus one copy of dist/ under assets/. Accepts --demo=, --docs= and --buy= to point its links at wherever those are hosted; the defaults are relative, so one folder works on any static host. |
npm run site:shots | Regenerates the marketing site's screenshots from html-dist-demo/ with Playwright, light and dark. build:landing runs it every time, so the shots always show the current demo; they are generated files, gitignored, and build:site fails if they are missing. |
npm run build:landing | The whole deployable: build:demo → site:shots → build:site → docs:build --base=/docs/ --site=… → assemble-landing. Produces landing-dist/ with demo/ and docs/ inside it, plus sitemap.xml, robots.txt and llms.txt, with every demo page marked noindex, and refuses to finish if the docs were built without the right --base — a mistake that is invisible locally and unstyles every docs page on the host. |
npm run deploy | Maintainers only: builds landing-dist/ and mirrors it to adminvora.net over SSH (tools/deploy.sh). Shows the changes and asks before uploading; -- --dry-run uploads nothing, -- --no-build reuses the folder on disk. See docs/internal/deploy.md. |
Useful flags
None of these flags are implemented. build:css compiles the whole stylesheet and takes only --min. Per-preset and per-component builds arrive with the Vite pipeline.
bash
# Build a single theme preset (smaller CSS for a white-label deploy)
npm run build:css -- --preset=aurora
# Build with only the components you use (comma-separated, no spaces)
npm run build:css -- --components=card,table,form,modal,sidebar,topbar,button,badge
# Build without the Customizer panel (production white-label)
npm run build -- --no-customizer
# Emit legacy physical-property fallbacks for Safari < 15
npm run build:css -- --legacy-logicalQuality gates
| Command | Purpose |
|---|---|
npm run test:pages | Every page in both modes: no console errors, one <h1>, no horizontal overflow at 320px, no off-origin request, no text painted in its own background colour. |
npm run test:rtl | Every page under dir="rtl" — nothing overflowing, nothing escaping either viewport edge. |
npm run test:nav-layouts | Every data-av-layout arrangement on a representative page set — every menu link reachable, no overflow at 1440px or 320px, a bar opens one panel at a time and restores the column's open groups on exit. |
npm run test:pagination | The bar, over all eleven grids that paginate. No button uses the disabled property — it leaves the tab order and the browser blurs it, so Next onto the last page destroyed the focus of the control that took you there. aria-disabled is asserted to be enforced rather than decorative: a listener is bound to the disabled button and must never fire, because initActions stops the click in the capture phase at document. The obvious version of that check — click it and assert the page did not move — passes with or without the guard, since Previous is only disabled on page one where paging back is a no-op anyway; it was written that way, watched failing, did not fail, and was replaced. Also: focus stays inside the bar across the rebuild a page change causes and at the last page, the three variants compute differently rather than merely carrying different class names, each __pages is a named <nav>, the reduced variants' status readout is aria-live, and the printed count is checked against the rows actually visible. |
npm run test:contrast | All every preset × 2 modes must clear 4.5:1, measured from what the browser resolves rather than from the generator's own maths. |
npm run test:starters | Scaffolds all eight kits and checks no __AV_…__ placeholder survived. Needs build:dist first. |
npm run test:html-dist | Serves the assembled html-dist/ and checks the deliverable a customer receives: the stylesheet applies, the runtime boots, nothing is fetched from outside the folder, tokens.css has folded into adminvora.css, and a lazily-loaded vendor still arrives over http. Needs build:html-dist first. |
npm run test:site | Serves landing-dist/ and holds the marketing site to the product's own list: no console errors, one non-empty <h1>, no horizontal overflow at 1440px or 320px, nothing fetched from outside the folder, the stylesheet actually painted, the runtime booted, and the five prices matching what the licence documentation says. Six pages × two modes × two widths. Needs build:site first. |
npm run test:demo | test:html-dist against html-dist-demo/ rather than html-dist/, so the folder that goes on the public URL is checked as the deliverable it is. Needs build:demo first. |
npm run test:package | Unpacks the artefacts into a clean directory and serves them. Run it after npm run pack; it is not in the npm test chain, for the same reason test:docs-dist is not — it needs a build the chain does not do. The archives are opened by an implementation that is not ours (unzip, or .NET's System.IO.Compression via PowerShell) and the suite fails rather than falling back to a reader written beside the writer, because agreement between two things authored together proves nothing. Checks digests against manifest.json and SHA256SUMS.txt, that dist.zip round-trips byte-for-byte rather than merely by filename, that re-packing reproduces the same digests, and that one page per section boots, is styled, and fetches nothing from outside the extracted folder — with the six util-open pages asserted in the opposite direction, since they must render when the bundle is what broke. |
npm run test:docs-dist | Crawls all 87 built pages (86 documents plus the generated 404) on a server that does no path guessing, at whatever base they were built for: every internal link must carry its .html, the app must mount exactly once, no page may render an empty content column, and nothing may be fetched from outside the folder. Catches the two faults that are invisible on a dev server — extensionless URLs only some hosts resolve, and a stale build that hydrates twice. Needs docs:build first. |
npm run test:docs-delivery | Builds and crawls the docs twice, once for each hosting contract they claim: /docs-dist/ (a subfolder of a server whose root is the repository) and / (the domain root). VitePress writes root-absolute asset URLs, so a build is only valid at the base it was built for — served anywhere else you get a fully-formed page with no styling, which reads as broken CSS rather than as a path problem. Both contracts were buildable and the crawl was already base-aware; only the root case was ever run. Leaves docs-dist/ built for the domain root, the usual case. Does not cover file://, which no base value can make work. |
npm run test:docs-offline | Opens all 88 pages of docs-offline/ over file:// — the way a customer opens the documentation inside full.zip, by double-clicking it — and requires every one to arrive styled, measured from computed style rather than from the presence of a <link> tag. Also opens the unrewritten docs-dist/ build over file:// as a control that must fail: if the untreated build looks styled too, the measurement distinguishes nothing and the suite reports that instead of a pass. Follows one sidebar link to prove navigation works with no router running. Needs docs:build and docs:offline first; not in the npm test chain, for the same reason test:docs-dist is not. |
npm run docs:audit | Measures the complete built documentation, a representative first-load dependency graph and the lazy local-search index in raw and per-file gzip sizes. Needs docs:build first; pass a path under docs-dist/ to sample another page. |
npm run docs:audit:runtime | Measures five cold loads of a representative built documentation page under a repeatable mid-range profile (390×844, 4× CPU slowdown, constrained 4G). Reports parsing, first interactive hydration response, first lazy-search open, browser CPU, blocking time and heap medians. Needs docs:build first; pass a path under docs-dist/ to sample another page. |
npm run test:visual | Screenshot regression across every page in light and dark, with the clock, timezone and locale pinned. |
npm run test:visual:update | Accepts new snapshots. Review the diff in tests/visual/__diff__/ before committing. |
npm run lint:css | The SCSS hard rules from the coding standards: every rule inside a @layer, max specificity 0-3-0, no ids, no !important outside @layer utilities, no numeric z-index, logical properties, tokens only — plus no new class defined in two component partials, since both land in one layer at the same specificity and @use order silently picks the winner. Existing duplicates are held in tools/duplicate-classes.baseline.json; re-record with node tools/lint-css.mjs --update-duplicates. |
npm run lint:tokens | Alias of check:tokens, under the name lint calls it by. |
npm run check:tokens | Fails on any var(--av-…) that nothing defines and that has no fallback. |
npm run check:scripts | Holds this page to package.json in both directions — see the note at the top. |
npm run check:licenses | The attribution page must name exactly the packages the vendor manifest pins — nothing missing, nothing invented, versions and licences matching. It found the page listing about thirty-five libraries, of which the build contains none but eight. |
npm run check:docs-classes | Every class name in a docs HTML sample must be one adminvora.css defines. A ratchet: the count is committed in tools/docs-classes.baseline.json and may only fall. Add --list to see them, --update after real work. |
npm run check:docs-refs | The non-class half of sample validity: icon sprite ids (no sprite ships in this build, so a sample pointing a use element at one renders an empty box) and public API members (the runtime exposes ten; the docs call thirteen more that have never existed). A ratchet like check:docs-classes, baselined in tools/docs-refs.baseline.json. --list to see them, --update after real work. |
npm run inventory | Prints what this repository actually ships — pages, components, presets, kits, vendored libraries, browser suites, docs pages — each derived from the artefact that owns it. --json for the machine-readable form. |
npm run check:inventory | Holds every public count in README.md, the docs overview pages and CLAUDE.md to npm run inventory, and every advertised demo path to a file that exists. A claim whose sentence has been reworded fails rather than passing quietly, because a gate that loses its anchor stops checking without saying so. |
npm run check:facets | Every .av-facets__count must equal the number of cards carrying that facet value. The count is hand-written on purpose — it is visible before a line of JavaScript runs, and a filter rail that is blank until a script fills it in is what this template exists not to ship — so the gate is what keeps it honest. A rail that miscounts the list beside it is the unread-badge defect one component along: a number with more than one writer. |
npm run check:icons | Verifies that the copyable icon gallery's headline and category counts agree with its source, names are unique kebab-case identifiers, labels match, and every glyph keeps the inline 24 × 24 accessibility and presentation contract. Runs inside lint. |
npm run check:customizer | Every control in the Customizer must move something. Checks that each name="av-<key>" and data-av-pref names a key AdminVora.theme.set() accepts — an unknown one throws, and it throws after load, where tests/pages.mjs never sees it — that the attribute the control writes is selected by a rule in src/css/ (both stylesheets: the navigation-surface and corner axes live in tokens.css, not adminvora.css), that each radio group carries exactly one data-av-default, and that no switch carries one, since the branch of sync() that reads it only walks radios. Runs inside lint. |
npm run check:breadcrumbs | Holds every <ol class="av-breadcrumb"> in html/_src and html/_partials to the four rules the page-header documentation states: the list carries an accessible name, the last crumb carries aria-current="page", the last crumb is not a link to the page it is already on, and no earlier crumb claims aria-current. axe sees none of these — aria-current is valid anywhere, a self-link is a well-formed link, and an unnamed <ol> breaks no WCAG rule on its own. Runs inside lint. |
npm run check:layouts | data-av-layout has three writers — src/scss/layout/_nav-layouts.scss, the overview table in docs/04-theming/04-layout-modes.md, and the hand-maintained LAYOUTS array in tests/nav-layouts.mjs — and this requires all three to name the same set. The third is the dangerous one, and the hazard is on record one file along: tests/lib/server.mjs's PAGES list means a page missing from it is invisible to the whole gate. Here an arrangement missing from LAYOUTS is never opened, never measured for overflow and never checked in RTL, and the suite still passes having tested nine of ten. Reads the Overview section only — the data-av-nav-skin table below it has identical rows, and reading the whole file harvested plain, tint and ink as layouts on the gate's first run. Comments are stripped, so an arrangement discussed near its own rules does not vouch for itself. Runs inside lint. |
npm run check:runtime-split | The two halves of the runtime have to stay two halves. src/js/adminvora.js is the component runtime a customer installs; src/demo/demo.js is the demo screens' own scripted behaviour, which ships with the pages and not with the bundle. This fails if the runtime names any of the 36 demo controllers, if the demo file reaches for a closure-private name that is not on the declared _internal seam, if the seam grants something nobody takes, if either of the two boot events (av:content, av:boot) loses its emitter or its subscriber, or if a controller is defined and never called — a screen that is quietly inert while the build is green. Comments and string literals are stripped by a scanner rather than a regular expression, because the regular-expression version desynchronised on a quote inside a regex literal and read twenty-six live screens as dead. Runs inside lint. |
npm run check:scss-source | The SCSS source ships in dist/scss/, so it is a public API and this holds the build to it. A relocated copy of src/scss/ is compiled in a temporary directory and compared byte-for-byte with src/css/adminvora.css — relocated, because a partial that only resolves thanks to where this repository puts it would compile here and fail in the customer's project, and byte-for-byte, because a tree that compiles to different CSS than the file shipped beside it is the quieter half of the same defect. It also fails if any partial is unreachable from adminvora.scss (a file a customer can edit with no effect), if build:dist stops copying the tree or the bundle README stops naming it, if a !default declaration appears anywhere (which would make @use … with (…) configure something the documentation says configures nothing), or if docs/02-architecture/08-scss-source.md drifts from the tree — the layer order, the per-directory partial counts, the utilities/ listing and every abstracts/ mixin and variable signature are checked in both directions, because a helper customers can see is public API whether or not anyone meant it to be. Runs inside lint. |
npm run check:kit-coverage | How much of the component system the UI kit actually demonstrates, held to a recorded number in both directions. It exists because the kit's landing page said "Every component AdminVora ships, shown working" while showing 94 of 252 blocks — a claim on a buyer-facing page that no other gate could see, since check:components asks whether the component index overclaims and check:page-classes asks whether a class resolves to a rule. Neither asks the question a person browsing the kit is asking. A block is the stem of a class in src/scss/components/, counted as demonstrated when its name appears in an html/_src/ui-*.html source as a whole identifier or as a BEM stem — not …, because _ is a word character and that test reported three live components as dead CSS. It is not a burn-down to 252: some components only mean anything in place, and a kit demonstrating every block would be unreadable. The number is here so that it is known and stated. Re-record with --update. Runs inside lint. |
npm run check:api-surface | An AdminVora.<name> in the documentation must be a member the runtime actually publishes. A ratchet: the remaining mentions of members that do not exist may only fall. |
npm run ci | lint + build + build:dist + vendor:audit + test. |
npm run test:a11y | axe-core sweep over every page in both colour modes, WCAG 2.1 AA. Ratchet baseline in tools/a11y.baseline.json; re-record with npm run test:a11y:update. |
npm run test:a11y:update | Re-record the accessibility baseline after real work. |
The visual suite photographs a representative page set in light and dark, plus the component QA page under every preset. Contrast is checked across every preset and mode.
Documentation site
| Command | Purpose |
|---|---|
npm run docs:dev | VitePress dev server for /docs at :5174 |
npm run docs:build | Static docs site → docs-dist/, built for the domain root. Add -- --base=<folder> to serve it from a subfolder — see below |
npm run docs:preview | Serve the built docs-dist/ at :5174, at the right root. Use this rather than pointing another static server at the folder |
npm run docs:offline | Rewrites docs-dist/ into docs-offline/ with relative asset URLs, so the folder opens by double-click with no server. This is the copy that ships inside full.zip, because a buyer who unzips it opens docs/index.html. Sidebar sections are forced open and the controls that cannot work without JavaScript (search, the appearance toggle, the carets) are removed rather than left dead. Every rewritten URL is resolved against the filesystem, so a missed reference fails the build instead of shipping. Needs a root-base docs:build first — it refuses a subfolder build. |
npm run docs:links | Validates every internal Markdown link and anchor. Runs in CI. |
npm run test:charts | Scrolls every page so the lazily-mounted charts build, then checks each one drew real geometry. A chart that throws mid-render leaves an empty <svg> and no page error. |
npm run test:select | The enhanced select must stay an enhancement: the native <select> survives and still validates, the label reaches the control that takes focus, a keyboard choice writes through to the native value, the dropdown is anchored outside every scroll container, and destroy()/init() round-trip cleanly. |
npm run test:mask | Masks must format without corrupting: the two card groupings chosen by issuer prefix, locale separator and radix on currency, fixed characters inserted by a pattern, upper-casing, a real clipboard paste, and the input event that validation downstream depends on. |
npm run test:lightbox | The lightbox opens, Escape closes it, the overlay takes the shared scrim token, and destroy() removes the overlay it appended to <body>. A lightbox that cannot be escaped is a full-screen trap. |
npm run test:uploader | The dropzone stays an enhancement: an input still carries the name, the label reaches the control FilePond builds, type and size are refused locally rather than by the server after the transfer, and destroy() can find a control whose original element the vendor removed. |
npm run test:map | The map draws its markers, its controls take a focus ring, its surface is a token — and it requests nothing off-origin, because this build ships no default tile provider. |
npm run test:tabulator | The advanced grid takes its rows from the server-rendered table, groups and totals them, is claimed by one module rather than two, restores the table on destroy() — and never loads on a page that did not ask for it. |
npm run test:editor | Quill mounts over a real textarea and writes back to it, an emptied editor submits nothing rather than <p><br></p>, a hidden required field does not stop the form dead, every toolbar control has an accessible name, and the toolbar and surface are token-painted in dark mode — including the inline-SVG icons, which the theming sweep could not see until this suite was written. |
npm run test:code-editor | CodeMirror mounts over a real textarea and writes back to it on every keystroke, the textarea is hidden only once the editor is up and comes back on destroy(), broken JSON is reported, and every colour in the editor — the vendor's own eight highlight literals included — resolves to a token. |
npm run test:virtual | Only a window of the 10,000 rows is mounted, every rendered row is painted where its aria-rowindex says it is at the top, the middle and the bottom of the scroll, and the paged alternative the virtual view owes a screen reader still works in both directions. |
npm run test:teardown | What AdminVora.destroy(root) does, and what it deliberately does not: the data-av-init claims are released and all three module-level IntersectionObservers are disconnected, while the listeners delegated from document keep working — the second half asserted in the positive, so improving it fails the suite and forces the known-limitations page to change with it. |
npm run test:asset-base | window.__AV_ASSET_BASE__ is honoured, proved from the path the server was actually asked for rather than from a value read back out of the page. Three runs: no global set, the vendor resolves beside the runtime; the global set to a directory that deliberately does not exist, the vendor request moves there and nothing is fetched from the default path; the same value without its trailing slash, which must mean the same directory rather than the one above it. The control run is not optional — without it an override that broke all vendor loading would pass by accident. |
npm run test:account | A masked secret is absent from the document until it is revealed rather than hidden with CSS; a half-checked column reports indeterminate and aria-checked="mixed"; the annual price is read from the markup rather than divided by twelve in the browser; and filtering the catalogue hides items rather than rebuilding the grid. |
npm run test:buttons | A busy button, photographed. The spinner has to put ink on the button and move between two frames — the button that prompted this suite had a spinner that was rendered, sized and animating while being transparent, painted behind the gradient and pinned to the corner, so nothing short of pixels can tell the two apart. Plus: the state is announced (aria-busy), focus stays on the button (aria-disabled, never the disabled property, which blurs it), the width is pinned before the label changes, and an element label comes back as the same node rather than rebuilt. |
npm run test:access | The user-management cluster. Every effective outcome on the permissions grid is recomputed by the suite itself from the role grant and the chosen exception, so a consistent bug cannot agree with itself; the allowed and exception figures must equal the rows counted; an exception that agrees with the role is not an exception, because counting checked radios is the obvious implementation and it overstates how much special treatment an account has; the grid is a real <table> with row and column headers and every override group carries a name; and on the user page one element prints the status while the session count follows the session rows through a sign-out. |
npm run test:projects | The projects cluster. Health on the overview is recomputed by the suite itself from each milestone's state and its slip against the baseline plan, so a self-consistent bug cannot agree with itself; the badge's colour must follow its word; the milestone count, the progress bar and the slip note all come out of the same pass and must move together when a milestone completes; a completed phase's slip is history and must not make the project late; status and health are separate writers, so putting the project on hold moves one badge and leaves the other alone; the second task list on the page drives only itself; and a task row's accessible names follow its title through completion and rename. |
npm run test:blog | The blog cluster. The desk's attention column and the figure above it are recomputed by the suite from each row's recorded idle days and the thresholds the page declares, so a self-consistent bug cannot agree with itself; a scheduled post idle past the draft threshold must stay silent, because it is waiting on purpose; the headline counts every row including the ones pagination has hidden; the feed's category filter shows exactly the cards carrying that category; the comment queue writes its own count and calls a comment a comment; and on the composer the readiness checklist is resolved field by field — an over-long field or an empty advisory one must never block publishing, an empty required one must, a click on the blocked button must not submit, and emptying the rich-text editor must reach the panel, which it can only do if the editor tells the form it has written to it. |
npm run test:crm | The CRM cluster. The pipeline's four figures and every weighted cell are recomputed by the suite from each deal's value and the probability the page prints in its own stage legend, so a self-consistent bug cannot agree with itself; a won deal must be in neither the pipeline nor the forecast and must show no weight of its own; the average open deal is checked against the right divisor and the wrong one, because including closed deals is invisible in every sum and decisive there; committed must be a subset of open. On the qualification board a grade is resolved as the worst of four answers rather than their sum — the board carries a lead with three yeses and a no, which the obvious implementation calls nearly qualified — a refusal and an unasked question must not arrive as the same chip, every chip must say its answer in words rather than in colour, and the most-forgotten question is an argmax the suite takes itself. And the account list keeps its contract columns while the customer list keeps its purchase ones, because the alert saying they are different pages is true only while that holds. |
npm run test:msgs | The messages drawer: the conversation rail is a real ARIA tablist driving exactly one thread, Enter sends and a typed tag arrives as characters rather than markup, a sent message lands before the typing indicator, a quick reply fills the field rather than sending it, and the unread count has one writer — the bell badge, the trigger’s accessible name, the header pill and each tile’s own name all have to agree after every change. |
npm run test:cart | The basket, where a printed number has a second writer: every [data-av-cart-out] target agrees after every change — the storefront prints the item count twice, on the topbar badge and beside the drawer's own title, so reading one of them proves nothing — the count is units rather than lines, it is derived rather than accumulated so removing a line puts it back exactly, the subtotal matches the line totals and the grand total adds up, and a basket of one reads “1 item”. It also drives the basket across the free-delivery threshold in both directions and holds the promise to the charge: above it the delivery line must read Free and the total must not include it, below it the charge must come back and the meter must say how much further there is to go — and the run fails if it only ever saw one side, because then half of that check is a branch nothing entered. |
npm run test:mail | The mail app's five mailboxes. It exists because they shipped as href="#inbox", href="#starred" and so on — pointing at ids that do not exist, with nothing reading them: five controls that were focusable, announced, carried an aria-current="page" that never moved, and did nothing at all. Now each shows its own messages, Starred is derived from the star rather than stored (or starring would not move a message into it), an empty mailbox says so in both panes, browsing does not mark anything read, and Archive moves a message rather than deleting it. |
npm run test:quick-actions | The controls that ride on a product photograph: the quick actions are painted on an opaque surface rather than --ghost (a ghost button has no contrast guarantee over a picture the customer supplied), hovering and focusing name them, and the wishlist heart's tooltip follows its pressed state while the panel is still open — asserted on the keyboard path, because a synthetic click fires pointerenter on the button's inner <path> afterwards and re-places the tooltip whether or not anything wrote it. Plus the nested sidebar menu, which was inert everywhere except the rail. |
npm run test:grid-filters | The filter builder, saved views and CSV export: a condition narrows the table to exactly the rows the column's own data-av-values say it should, an enum's options come from the rows rather than a list typed beside them, the URL is the view (it survives a reload and the back button undoes it), and the export writes the filtered set as values rather than rendered strings — with a leading =, +, - or @ neutralised, because those are executed as formulas by Excel and Sheets the moment the file is opened. |
npm run test:import | The CSV import wizard: a quoted field containing the delimiter, a newline or a doubled quote is one field (split(',') is the single most common CSV bug and reports nothing when it happens), the delimiter is sniffed rather than assumed, 1.234,56 is one thousand two hundred and thirty-four, a row missing a required field is reported and skipped rather than imported with a hole in it, nothing is written until Import, and a cell containing <img onerror> lands as text — a CSV is a file somebody was handed. |
npm run test:shortcuts | Keyboard shortcuts on every page rather than one: a chord (g o) navigates, a pending prefix is shown on screen and announced (a key that silently arms a sequence is indistinguishable from a dead one), the chord times out and Escape cancels it, the ? help list is generated from the bindings so it can never document a key that stopped working, nothing fires while a dialog is open, and nothing is stolen from someone typing in a field. |
npm run test:avatar | The avatar cropper: a photograph too small by dimension is refused (a 40×40 PNG passes every byte-count check and is useless as an avatar), Save is aria-disabled rather than disabled and does nothing until there is something to save, the framing cannot be pushed off its own crop circle, closing forgets — and above all the saved file is the picture on screen, checked by framing one half of a two-tone image and reading the pixel back off the avatar. |
npm run test:auth | Every [data-av-auth-nav] control must change either the pane or the URL — the basic and illustration variants carry sign-in and sign-up only, and "Forgot password?" was cancelling its own navigation and then doing nothing. Also: deep links open the flow they name, a hidden pane holds no focus, and every flow keeps one labelled form. |
npm run test:motion | The motion axis tells the truth. data-av-motion="reduced" and prefers-reduced-motion: reduce must produce identical computed motion, element for element, on every page checked — they are one condition in the runtime, in the token layer and in the lightbox, so a rule that answers one and forgets the other is a switch that only half works. That is what shipped: the axis zeroed every transition, because transitions interpolate duration tokens, and reached no @keyframes at all, so "Reduce motion" left the skeleton shimmering and the spinners spinning. The suite refuses to compare a page that does not move by default, and requires at least one running @keyframes among what moves, because an equality between two still pages passes for the wrong reason. |
npm run test:touch | What a finger can hit, and what it leaves behind. Every control's effective target — a wrapping or for=-linked label counts, because the label is what a thumb lands on — must meet --av-size-touch-min under a coarse pointer, and --av-lift must be zero on a hoverless one, because :hover keeps matching after a tap and a card that rises stays risen. The third assertion is the one that keeps the other two honest: the same pages are measured again with a fine pointer and a minimum number of controls must come back smaller, so a @media (pointer: coarse) block that stopped matching fails loudly instead of passing while testing the desktop stylesheet. Links are out of scope by decision, not oversight — a link that should be a target should be a button. |
npm run test:dropdowns | Opens every dropdown on every page and asks elementFromPoint what is on top. Catches a menu that renders correctly and is painted over or clipped. |
npm run check:components | Checks the component index against src/: a row marked 🟢 stable must name a class or hook the source actually defines. Runs inside lint. |
npm run check:page-classes | Every av- class used in a page source resolves to a rule in the compiled CSS, a hook the runtime reads, or a listed identifier. Catches markup written against a class that was never defined — which renders as an unstyled block and throws nothing. |
npm run check:hooks | The mirror of check:page-classes: every data-av-* authored in the markup must have a reader — the attribute string, the dataset key it maps to, a prefix a module builds at runtime, or a test suite. Catches a hook that looks wired up and does nothing. Three destructive confirmations shipped carrying data-av-confirm-type while the runtime reads data-av-confirm-require-input, so the type-to-confirm step was never asked for. Runs inside lint. |
npm run check:inline-styles | A ratchet on inline style= in authored markup. The house rule permits exactly two forms — a style JavaScript sets at runtime, and a custom property carrying a per-instance value the stylesheet reads — so this counts the thing the rule forbids: a plain CSS declaration in a style attribute, per source file, against tools/inline-styles.baseline.json. A file that gets worse fails, and a file that gets better fails too, asking for the baseline to be lowered: 187 declarations came out of one batch and nothing else stops them going back a page at a time. Comments are stripped before matching, because a gate that reads commentary measures what the code says about itself. <pre> is deliberately not stripped — it would be the one place a real inline style could hide. Its first assertion is that it measured anything at all, since an empty scan sums to zero and agrees with any baseline. Re-record with --update. Runs inside lint. |
npm run check:globals | check:hooks pointed at the window object. The runtime owns exactly one global — window.__AV_ASSET_BASE__ — and both directions are checked: a name declared in tools/runtime-globals.mjs with no reader in src/js/ fails, and a window.__AV_…__ written in the documentation, a kit README or the authored markup that is not declared fails too. Comments are stripped from the runtime first, because this repository explains its defects beside the code that had them and a header comment would otherwise vouch for the very name it describes. It exists because __AV_ASSET_BASE__ shipped across ten customer-facing documents while the vendor loader anchored ../vendor/… to document.currentScript.src unconditionally and never looked at it. Runs inside lint. |
npm run check:scss-api | A $av-… variable named anywhere in the documentation must be declared in src/scss/. It exists because the build-pipeline page printed a src/scss/_config.scss holding twenty-seven of them, and there is not one !default declaration anywhere under src/scss/ — the whole configuration surface was invented, and eighty-eight mentions of it had spread across thirteen pages, each showing a @use 'adminvora' with (…) block that cannot compile. One of them costed itself: "~31 KB gzipped instead of 112 KB", against a stylesheet that is 41.7 KiB gzipped with no configuration at all. Prose is checked as well as fenced blocks, because a name is a claim about an API in both — which means a page cannot name one of these even to deny it, and the three pages that needed to say a flag does not exist say it without printing the flag. Comments are stripped from the SCSS first, and a use of a variable does not vouch for it. Runs inside lint. |
npm run check:demo-dates | Every data-av-relative-time hook in the authored markup sits on a <time>, carries a datetime the browser can parse, and names no instant after the one the demo data depicts. The element rule matters because the module scans [data-av-relative-time] on any element and then reads getAttribute('datetime') — on a <span> that is null, so the hook is claimed, nothing is rewritten, and the server-rendered fallback stays on screen; check:hooks cannot see it, because the attribute does have a reader. Catches a past-tense column rendering a future time — a Last active cell reading "in 4 days" beside "Now" and "7 hr ago". Nothing else can see it: the attribute is well-formed, the hook is read, and the visual baseline records whatever the page last produced. It also asserts that tests/visual.mjs still freezes the clock at the same instant, because both constants describe one decision. Runs inside lint. |
The site is configured in docs/.vitepress/config.mjs. Two things there are worth knowing before you edit it:
The sidebar is derived from the directory tree, not hand-listed. Order comes from the numeric filename prefixes — the only reason they exist — and each entry's label comes from that file's first H1, so a page and its sidebar entry cannot disagree. Add a Markdown file and it appears. Paired with the orphan check in docs:links, every page is reachable from both the sidebar and the prose.
Inline code containing {{ is rendered v-pre. VitePress compiles every page as a Vue template, which reads {{ … }} as an interpolation and tries to parse the contents as JavaScript. These docs are full of brace pairs that are not JavaScript — the HTML assembler's {{> partial }}, Handlebars, Blade, Django tags — and `{{> illustrations}}` on the iconography page failed the build outright. Fenced blocks already come out v-pre; the markdown.config hook adds it to inline code too.
Do not "fix" this by moving Vue's delimiters globally. The same plugin compiles VitePress's own theme components, so the sidebar then renders a literal
{{ site.title }}and the page outline a column of{{ title }}. Escape the content, never the compiler.
Release
| Command | Purpose |
|---|---|
npm run pack:starters | Scaffolds and zips all eight framework starter kits → dist-starters/. |
npm run pack | Assembles the thing a buyer downloads into dist-package/: adminvora-<v>-dist.zip (the bundle), adminvora-<v>-full.zip (bundle, demo pages and built docs), the starters zip, plus SHA256SUMS.txt in sha256sum -c format and a manifest.json. Needs dist/, html-dist/ and docs-dist/ — it names which one is missing and the command that makes it. Every figure in the manifest is measured off the finished archive rather than off the list that built it, because two values written in the same breath always agree. Archive timestamps are pinned, so packing an unchanged tree twice gives identical digests; without that a published checksum distinguishes nothing. |
npm run pack:release | The same, but re-runs the bundle claim gates (check:inventory, check:components, check:licenses) and refuses on an unresolved LICENSE.md placeholder before packing anything. Packing is the last point at which a wrong count can be caught and the first at which it reaches a customer. |
Generators
| Command | Purpose |
|---|---|
npm run create | Scaffolds a starter kit: npm run create -- my-app --kit=laravel. |
npm run starters:list | The eight kits, their ids, and what each is for. |
There is no page or component generator. A new page is created by hand under html/_src/, registered in the sidebar partial, and added to PAGES in tests/lib/server.mjs — that last step makes it visible to the test suites.
Serving the docs from a subfolder
VitePress writes root-absolute asset URLs — /assets/style.css. That is right when the site is the server root and wrong the moment it is not. Open docs-dist/ at, say, 127.0.0.1:5500/docs-dist/ and every stylesheet, script and font 404s.
The failure is worth recognising on sight, because it does not look like a path problem: the page renders completely, with correct headings, links and reading order, and no styling whatsoever. It reads as a broken stylesheet, and the stylesheet is fine.
bash
npm run docs:preview # the zero-thought answer: serves at the right root
npm run docs:build -- --base=docs-dist # or rebuild so a subfolder deploy works--base takes a bare segment with no slashes, and that is deliberate rather than terse. The underlying DOCS_BASE needs a slash on both ends, and typing one in Git Bash does not survive the trip: MSYS rewrites any argument that looks like a POSIX path, so --base=/docs-dist/ reaches Node as C:/Program Files/Git/docs-dist/ and the build happily produces a site pointing at URLs inside your Git installation. Passing the bare segment leaves nothing for the shell to rewrite, and tools/build-docs.mjs adds the slashes where getting them wrong is not possible. A value that has been mangled anyway is rejected with an explanation rather than built.
Environment variables
The build reads none. window.__AV_ASSET_BASE__ is a runtime global, not an environment variable: the starter kits behind a hashing bundler set it so the runtime resolves vendor/ correctly.
Read next: Architecture Overview.