nava-ui · v0.8.0
A small, dark-first UI kit in plain CSS.
The design tokens and components of allan-nava.github.io, extracted so that other projects can look like they belong together. No build step, no framework, two themes.
Get started
One stylesheet, and optionally one script for the theme toggle and the card spotlight.
<link rel="stylesheet" href="https://cdn.jsdelivr.net/gh/Allan-Nava/nava-ui@v0.10.0/dist/nava-ui.css">
<script defer src="https://cdn.jsdelivr.net/gh/Allan-Nava/nava-ui@v0.10.0/dist/nava-ui.js"></script>
Then write HTML with the nv- classes shown below. Every example on this page is live, and the source under it is read from the example itself, so the two cannot drift apart.
| File | What it contains | Use it when |
|---|---|---|
dist/nava-ui.css | tokens, base and components | nava-ui styles the whole page |
dist/nava-ui.components.css | tokens and components | the page already has its own typography |
css/tokens.css | the custom properties only | you write your own components on these values |
dist/nava-ui.motion.css | scroll reveal, section rule, view transitions | optional, after the kit: motion |
dist/nava-ui.js | theme toggle, card spotlight, toasts, dialogs, tabs, copy code | optional: the CSS works without it |
Tokens
Components read custom properties and nothing else. Switch the theme with the button in the nav: the swatches change, the names do not.
Colour
--nv-bg
page background--nv-surface
cards, inputs, buttons--nv-surface-hover
hovered surface--nv-fg
body text--nv-fg-strong
titles, emphasis--nv-fg-muted
secondary text--nv-accent
links, primary actions--nv-accent-hover
hovered accent--nv-accent-soft
tag and code background--nv-accent-text
text on accent-soft--nv-on-accent
text on accent--nv-border-strong
borders (and--nv-border)
Type
Display --nv-text-4xl
Heading one --nv-text-3xl
Heading two --nv-text-2xl
Heading three --nv-text-xl
Lead paragraph --nv-text-lg
Body text --nv-text-base
Small text --nv-text-sm
Label --nv-text-xs
The font is Inter Variable, self-hosted (48 KB, Latin subset) with a system fallback. Sizes from base up are fluid: they grow with the viewport between two bounds.
Spacing and radius
Use sm for inline code and focus rings, md for images and code blocks, lg for cards and panels, pill for everything you can click that is not a card.
Components
Buttons
One primary action per view. A link that looks like a button is an <a>; something that acts on the page is a <button>.
- Use it for
- An action on this page; a link drawn as a button when it is the page's main way forward.
- Not for
- Navigation inside running text: that is a link. More than one primary button in a view.
- Your part
<button type="button">for an action,<a href>for going somewhere. An icon-only button needs anaria-label. A disabled button hides why: say it next to it.
Chips
Three roles: nv-tag labels content, nv-chip links to a topic, nv-chip--filter is a toggle (a <button> with aria-pressed).
- Use it for
nv-taglabels content,nv-chiplinks to a topic,nv-chip--filtertoggles a filter.- Not for
- A state (use a badge) or an action that changes data (use a button).
- Your part
- Filter chips are buttons with
aria-pressedkept in step, grouped byrole="group"with anaria-label; announce the result count in arole="status"line.
Badges
A short status label, neutral by default, in three tones. The words carry the state, so a badge is never a coloured dot alone; nv-badge--dot adds a dot before them.
checkfleet v1.4 runs every 10 minutes.
- Use it for
- A short state next to a name: Live, Beta, Down.
- Not for
- Anything to click, or more than two words.
- Your part
- The word carries the state and the colour only repeats it. A badge that is only a dot needs its word in
nv-sr-only.
Marked pills and legend
For a list where every item has a kind. The kind is told three ways: the shape of the mark (dot, ring, diamond), the pill's fill and border, and words, visible in the legend and read by screen readers in each pill. This is how the site lists where each skill was used.
- At work
- Earlier role
- Own projects
- Go, at work
- Nomad, at work
- Kotlin, earlier role
- Kubernetes, own projects
- Use it for
- A list where every item has a kind that must read without colour.
- Not for
- A list with one kind: plain chips are enough.
- Your part
- A legend near the list, and the kind in words for screen readers (
nv-sr-only): the marks arearia-hidden.
Cards
A horizontal card: thumbnail, title, two-line excerpt, meta. nv-list--two gives two columns from 860px. Without an image use the generated placeholder, nv-ph nv-ph-0 to nv-ph-5. Add data-nv-spotlight to the list for the glow that follows the pointer.
-
GO
Go-DDD-Scaffold
A starting point for Go services laid out by domain, with wiring generated at build time.
-
KC
keycloak-apple-identity-provider
Sign in with Apple as a Keycloak identity provider. A long single-word title wraps instead of overflowing.
-
SQ
Square thumbnail
For vertical sources, where a 16:9 box would show a thin slice.
-
No thumbnail
The card stays compact when there is nothing to show.
- Use it for
- Lists of things to open: posts, projects, videos.
- Not for
- A single feature (a panel or a tile), or content with several actions: the whole card is one link.
- Your part
- One link per card, whose text is the title. A thumbnail that only decorates has
alt=""; one that informs has real alt text.
Bento grid
Tiles of different sizes in one grid: one column on phones, two from 561px, six from 860px. A tile takes two of the six columns by default; nv-tile--w3, --w4 and --w6 make it wider, nv-tile--h2 two rows tall. nv-tile--feature marks the one tile that leads. Placement is dense, so a tall tile leaves no holes. This is the "What I work with" section of the site.
-
Infrastructure11 skills
- Nomad, at work
- Consul, at work
- Traefik, at work
- HAProxy, at work
- Docker, at work
- Ansible, at work
- Terraform, at work
- AWS, at work
- TeamCity, at work
- Linux, at work
- Kubernetes, own projects
-
Languages8 skills
- Go, at work
- Java, at work
- Kotlin, earlier role
- Swift, earlier role
- Python, earlier role
- PHP, earlier role
- TypeScript, own projects
- React, earlier role
-
Data and identity6 skills
- Keycloak, at work
- NATS JetStream, at work
- MariaDB, at work
- PostgreSQL, at work
- KeyDB, at work
- Canal, at work
-
Reliability4 skills
- Prometheus, at work
- checkfleet, at work
- k6, at work
- Incident response, at work
-
Live video3 skills
- OTT, at work
- HLS and DASH, own projects
- Low-latency HLS, own projects
-
AI-assisted2 skills
- Claude Code, at work
- Agent tooling, own projects
- Use it for
- An overview of groups of different weight.
- Not for
- Long lists of equal items (cards) or values to compare (a table).
- Your part
- Write the markup in reading order: dense placement may move a tile on screen, never in the order a screen reader follows. One feature tile per grid.
Lede
The opening of a page: a kicker, a very large title with one or two highlighted words, a short paragraph.
Software engineer · Milan
I build live video platforms that stay up.
Backend in Go, infrastructure on three data centres, and the parts in between.
- Use it for
- The opening of a page, once.
- Not for
- Section headings.
- Your part
- Its title is the page's
<h1>; the kicker is a paragraph, not a heading.
Banner
A page opening over a landscape: kicker, title, a line of words and a line of facts, over a faint grid, an accent glow and layered ridges. The ridges are an inline <svg class="nv-banner__ridges"> with preserveAspectRatio="none": paths nv-banner__far, __mid and __near, and a nv-banner__line with pathLength="1". Without prefers-reduced-motion the line draws itself, the glow breathes and the ridges drift at three speeds on scroll. This is the opening of the site's videos page, from the YouTube channel banner.
- Use it for
- The opening of a showcase or media page.
- Not for
- Every page, or a page whose content must start above the fold.
- Your part
- The title is the page's
<h1>and the ridges SVG staysaria-hidden. Its motion already stops under reduced motion: add none of your own that does not.
Profile
Who a page is about: a round photo, the name as the page's <h1>, one line of role and place, and a row of buttons. Side by side, stacked and centred on phones. This is the opening of the site's about page.
- Use it for
- The opening of a page about a person.
- Not for
- Author lines under a post, or lists of people.
- Your part
- The name is the page's
<h1>. The photo'saltis empty when the name is next to it, and itswidthandheightare set so the page does not jump while it loads.
Timeline
Roles or events in order, the latest first: an <ol class="nv-timeline"> whose items have the dates in nv-timeline__when and the rest in nv-timeline__body — a title, an nv-timeline__org line with an optional logo, a line of text. A rail with a dot per item runs between dates and body; the item still going on takes nv-timeline__item--current. On phones the dates go above the body.
-
– now
DevOps Engineer
HiWay Media · Milan
Infrastructure for live video and OTT platforms, from the capacity test before the match to the post-mortem after it.
-
–
Full Stack Developer
HiWay Media · Milan
The platform's apps for Android, Android TV, Fire TV, iOS and tvOS.
-
–
Software Web Developer, then Full Stack Developer
IES Italia
- Use it for
- Work history, the steps of a project, a changelog told as a story.
- Not for
- Lists without dates, or dozens of entries: use a table.
- Your part
- Keep it an
<ol>, with dates in<time datetime>. The title is a heading one level below the section's. A logo next to the organisation's name has an emptyalt.
Award
A recognition, set apart from the text around it: a mark, the kind and year, what was won, from whom and for what, and an optional link to the story. An accent hairline and a faint accent wash make it a highlight in both themes.
- Use it for
- One or two recognitions worth a reader's attention.
- Not for
- A list of certificates, or anything that is not an outside recognition.
- Your part
- The mark stays
aria-hidden; give the<aside>anaria-label. Name who gave it and when: an award without its source reads as a claim.
Section head
Latest projects
All projects →The content of the section goes here.
- Use it for
- A titled section with a link to its full list.
- Not for
- Inside a card or a tile.
- Your part
- The heading level follows the page's outline; the link says where it goes ("All projects", never "More").
Stats
A <dl>: the label comes first in the markup, the number is drawn on top.
- Projects
- 64
- Posts
- 212
- Years
- 11
- Use it for
- Three or four numbers that give the scale at a glance.
- Not for
- Numbers to compare in detail (a table) or that change live.
- Your part
- The label (
<dt>) says what is counted, and the page says when.
Bars
A horizontal bar list. The width is an inline style; the number is always written next to the bar, so the bar is never the only carrier of the value.
- Use it for
- Comparing a handful of counts.
- Not for
- Exact values to read (a table), or more than about fifteen rows.
- Your part
- The number is in the text (
nv-bar__value); the bar's width is decoration. A label that leads somewhere is a link.
Form field
Press / to focus, Esc to clear.
- Use it for
- A single search or filter box.
- Not for
- A form with several fields: use
nv-fieldand the controls below. - Your part
- A visible label, or an
aria-labelfor a search in a toolbar;type="search".
Form controls
For a form with several fields: nv-field ties a label, a control and a hint together, and nv-input--box gives the input the same corners as the other controls. Checkbox, radio and switch are classes on the native <input>, wrapped in a nv-choice label so the text is part of the target. A switch is a checkbox with role="switch": use it for a setting that applies at once, a checkbox for something sent with the form.
- Use it for
- Forms. A switch for a setting that applies at once, a checkbox for something sent with the form, radios for a few visible options, a select for many.
- Not for
- A switch inside a form that waits for Submit.
- Your part
- Every control has a label (
nv-fieldornv-choice); a group has afieldsetand alegend; a hint is linked witharia-describedby.
Validation
An invalid control has aria-invalid="true", and its message is linked with aria-describedby: the CSS styles the attribute, so what a screen reader announces and what the eye sees cannot disagree. A valid control has the class is-valid. Neither is told by colour alone: the edge gets thicker and the message has a mark and says what to do.
- Use it for
- After the person leaves a field or submits the form.
- Not for
- While they are still typing.
- Your part
aria-invalid="true"and the message inaria-describedby; the message says how to fix it. On submit, move the focus to the first error.
Alerts
A message in the page, in four tones. The tone is never told by colour alone: each has its own mark and a title that says what happened. Add role="alert" only to a message that appears after an action and needs attention now. A button with data-nv-dismiss removes the alert it is in.
A new version is available
Version 0.3.0 adds form controls. The default tone is info.
Project created
The certificate expires in 7 days
Renew it before 19 November to keep the site reachable.
The deploy failed
The health check did not answer in 30 seconds. The previous version is still running.
- Use it for
- Something on this page to read now: a problem, a result.
- Not for
- A confirmation that can be missed (a toast), or promotion.
- Your part
role="alert"only for an urgent message added after load. Dismissing one must not remove the only copy of an error.
Toasts
A short message over the page that goes away by itself. Call navaUI.toast(message, { tone, title, timeout }): the script creates the live region, so screen readers announce the message, and stops the timer while the pointer or the focus is on the toast. A toast is for something the person can afford to miss; anything they must act on belongs in an alert.
Saved
This one is written in the page, to show the markup the script produces.
- Use it for
- A confirmation the person can afford to miss: "Saved".
- Not for
- Errors that need action, or a link that must be followed.
- Your part
- Short text;
timeout: 0for anything longer to read; never a burst of several at once.
Dialog
The native <dialog>, opened with showModal() or a button with data-nv-dialog="<id>": the browser traps the focus, closes it on Escape, makes the page behind inert and gives the focus back to the button that opened it. The close button sits in a <form method="dialog">, so it works without the script; closedby="any" also closes it on a click outside. Below, the same dialog drawn in the page, and a button that opens it for real.
- Use it for
- A decision that blocks the task: confirming a deletion, a short form.
- Not for
- Content that could be a page, long forms, information that can sit inline.
- Your part
aria-labelledbyits title, a close button inside<form method="dialog">, and a destructive action named for what it does ("Delete playlist", never "OK").
Tabs
The ARIA tab pattern in the look of the nav links: role="tablist" with an aria-label, buttons with role="tab", aria-selected and aria-controls, panels with role="tabpanel". With nava-ui.js a click selects a tab, the arrow keys move and select, Home and End go to the ends, and Tab goes on to the panel. Without the script only the first panel can be reached.
Three data centres, 42 allocations, last deploy 12 minutes ago through the canary node.
The last 200 lines of the deploy, newest first.
Canary size, health-check timeout and the rollback rule.
- Use it for
- Switching between a few views of the same thing, with short labels.
- Not for
- Steps of a process, navigation between pages (links), or content to compare side by side.
- Your part
- The ARIA markup with its ids, and
nava-ui.js(or the ReactTabs): without a script only the first panel can be reached.
Data table
A table in a box that scrolls both ways. The box takes tabindex="0", role="region" and an aria-label, so a keyboard can scroll it; with a max-height the header sticks to its top. nv-table__num right-aligns a column in tabular figures. A row is selected when the checkbox in its first cell is checked (or with is-selected): the state lives in the checkbox and the colour follows it.
| Selected | Region | City | Allocations | Uptime | p95 |
|---|---|---|---|---|---|
| eu-south-1 | Milan | 42 | 99.98% | 184 ms | |
| eu-west-1 | Dublin | 36 | 99.95% | 211 ms | |
| eu-central-1 | Frankfurt | 28 | 99.99% | 167 ms | |
| us-east-1 | Virginia | 19 | 99.91% | 243 ms |
- Use it for
- Rows to compare or to act on.
- Not for
- Layout, or a list of one column.
- Your part
scopeon every header cell, anaria-labelon the scrolling box withtabindex="0"androle="region", and a row checkbox named after its row.
Empty state
What a region shows when it has nothing to show: an optional icon, a title, one line of text and at most one action. Say what is missing and what to do about it, not that something went wrong.
- Use it for
- A region with nothing in it yet, or no match for a filter.
- Not for
- Errors (an alert) and loading (a skeleton).
- Your part
- Say what is missing and what to do about it, with one action; the heading level fits the page.
Skeleton
Placeholders while content loads, in the shape of what is coming: nv-skeleton sized inline, --line for a line of text, --circle for an avatar. The region carries aria-busy="true" and a "Loading…" for screen readers; the skeletons are aria-hidden. The shimmer stops under prefers-reduced-motion.
- Use it for
- Content whose shape is known and that takes more than a moment to arrive.
- Not for
- A short wait (show nothing) or content of unknown shape.
- Your part
aria-busy="true"on the region and a "Loading…" text for screen readers; remove both when the content is in.
Button spinner
A button that is working keeps its label, gets aria-busy="true" and an nv-spinner before the text. It stays readable, unlike a disabled button, and ignores clicks until it is done. The spinner takes the colour of the text and stands still under prefers-reduced-motion.
- Use it for
- An action that takes a moment after the click.
- Not for
- A page load.
- Your part
aria-busy="true", the label kept; when it is done, say the result (a toast or an alert).
Pagination
On the first or last page keep the arrow in the markup with aria-disabled="true": it is hidden but still takes its space, so the page number stays centred.
- Use it for
- A long list split into pages.
- Not for
- A handful of items, or a feed that loads as it scrolls.
- Your part
- A
<nav>with anaria-label, anaria-labelon each arrow, and the current page written out.
Panel
- Use it for
- One call to action at the end of a page.
- Not for
- More than one per page.
- Your part
- A heading at the right level and one clear action.
Nav
A floating glass island, sticky at the top; the nav of this page is the same component. Mark the current page with aria-current="page". On phones the name is hidden and the links scroll sideways: there is no menu to open.
- Use it for
- The site's main navigation, with a few links.
- Not for
- More than about six links: on a phone they scroll sideways.
- Your part
aria-current="page"on the current link, a skip link before the nav, and a brand link that keeps a name (the kit hides the name visually only).
Footer
- Use it for
- The end of every page: who, the main links, the licence.
- Not for
- A second navigation with everything in it.
- Your part
- Column titles are real headings; links say where they go.
Prose
With base.css loaded, plain elements are styled too: headings, links, quotes, inline code, code blocks, tables, rules.
A quote has an accent rule on the left and a faint background.
Inline code sits on the accent tint; strong text is brighter than body text; links are underlined.
| Token | Value |
|---|---|
| --nv-radius-lg | 14px |
| --nv-dur | 200ms |
- Use it for
- Long-form text: posts and documentation.
- Not for
- Interface text.
- Your part
- Headings in order, alt text on images, and
tabindex="0"on a code block that scrolls sideways.
Code block with a copy button
With nava-ui.js, a <pre data-nv-copy>, or every <pre> inside an element with data-nv-copy, gets a Copy button in its top corner. It shows when the pointer is on the block or the keyboard reaches it, and always on touch screens; it says Copied for a moment, and a hidden status says it to screen readers. The script adds it only where the browser can copy, so there is never a button that does nothing. Every code block on this page has one. For a block added later, call navaUI.copyButton(pre).
npm install @allan_nava/nava-ui
- Use it for
- Code a reader will paste somewhere else: a command, a snippet, a configuration.
- Not for
- Inline code, or output to read rather than run.
- Your part
tabindex="0"on a block that scrolls sideways; only the code inside the<pre>, no prompt sign, since the button copies all of it.
Page templates
Three complete pages built only with the kit, for a made-up product. Each one is screenshotted in both themes and at both widths, and checked for accessibility as a whole page.
- Landing: lede, stats, a bento grid, cards, a panel and the footer.
- Listing with filters: search, filter chips, a card grid, the empty state and pagination; the filter is a few lines of the page's own script.
- Application screen: an alert, tabs, a data table with badges, a settings form, a dialog and toasts.
Motion
The kit moves only on hover and press. The site's movement is a separate stylesheet, loaded after the kit, with no script:
<link rel="stylesheet" href="https://cdn.jsdelivr.net/gh/Allan-Nava/nava-ui@v0.10.0/dist/nava-ui.motion.css">
- Scroll reveal:
nv-card,nv-tileand anything withnv-revealfade and rise into place as they enter the viewport. The hover lift of the cards keeps working. - Section rule: the line under an
nv-section-headdraws itself from the left. - View transitions: between pages of the same site that all load the file, the page cross-fades, the
nv-navstays put and the current link slides to its new place.
With prefers-reduced-motion: reduce the file does nothing, and where the browser does not know scroll-driven animations the elements are simply in place. This page does not load it, so its examples hold still; the page templates do: scroll the landing, then move between the three pages with the nav.
- Use it for
- Pages read top to bottom, and a site whose pages share a nav.
- Not for
- An application screen people work in all day, or a long list where every row would animate.
- Your part
- Load it on every page of the site, or the view transitions do not run; nothing in it is ever the only way to see content.
Theming
Dark is the default. Light applies when the system asks for it, and an explicit choice on <html data-theme="light"> or data-theme="dark" wins over both. To remember the choice without a flash on load, put this in <head>, before the stylesheet:
<script>
(function () {
try {
var t = localStorage.getItem('nv-theme');
if (t === 'light' || t === 'dark') document.documentElement.setAttribute('data-theme', t);
} catch (e) {}
})();
</script>
To make the kit yours, override tokens in your own CSS: the kit sits in cascade layers (nv.tokens, nv.base, nv.components), so any rule of yours outside a layer wins, before or after the stylesheet. Changing the accent takes six values per theme, because the accent is used both as text and as a background:
:root {
--nv-accent: #4c8dff;
--nv-accent-hover: #74a7ff;
--nv-accent-soft: rgba(76, 141, 255, 0.12);
--nv-accent-border: rgba(76, 141, 255, 0.35);
--nv-accent-text: #a9c8ff; /* text on accent-soft */
--nv-on-accent: #04101f; /* text on accent */
}
Check the contrast of each pair you change, in both themes. The full list of tokens and the rules for adding a component are in the README.