Skip to content
nava-ui

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.

FileWhat it containsUse it when
dist/nava-ui.csstokens, base and componentsnava-ui styles the whole page
dist/nava-ui.components.csstokens and componentsthe page already has its own typography
css/tokens.cssthe custom properties onlyyou write your own components on these values
dist/nava-ui.motion.cssscroll reveal, section rule, view transitionsoptional, after the kit: motion
dist/nava-ui.jstheme toggle, card spotlight, toasts, dialogs, tabs, copy codeoptional: 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

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

1 · 4px
2 · 8px
3 · 12px
4 · 16px
5 · 24px
6 · 32px
7 · 48px
8 · 64px
9 · 96px
sm · 4px
md · 8px
lg · 14px
pill

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>.

Primary Secondary
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 an aria-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-tag labels content, nv-chip links to a topic, nv-chip--filter toggles 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-pressed kept in step, grouped by role="group" with an aria-label; announce the result count in a role="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.

Draft Live Degraded Down

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 are aria-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.

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.

Videos @allan_nava

Mountains, crags & the road

Hiking Climbing Snowboard Travel

149 videos 127 on the map

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 stays aria-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.

Allan Nava

Software & DevOps engineer · Milan

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's alt is empty when the name is next to it, and its width and height are 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.

  1. – 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.

  2. –

    Full Stack Developer

    HiWay Media · Milan

    The platform's apps for Android, Android TV, Fire TV, iOS and tvOS.

  3. –

    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 empty alt.

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> an aria-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-field and the controls below.
Your part
A visible label, or an aria-label for 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.

Lower case, no spaces.

Checks to run
Visibility
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-field or nv-choice); a group has a fieldset and a legend; a hint is linked with aria-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.

Add the part after the dot, for example .com.

This address is free.

Choose a plan to continue.

Accept the terms to create the project.

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 in aria-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: 0 for 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.

Delete this playlist?

The 12 videos stay on the channel; only the list goes. This cannot be undone.

Delete this playlist?

The 12 videos stay on the channel; only the list goes. This cannot be undone.

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-labelledby its 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.

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 React Tabs): 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.

Regions
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
scope on every header cell, an aria-label on the scrolling box with tabindex="0" and role="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.

No videos in this list yet

Videos you save while browsing show up here, newest first.

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.

Loading…
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 an aria-label, an aria-label on each arrow, and the current page written out.

Panel

Want to work together?

A centred block to close a page with one clear action.

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.

TokenValue
--nv-radius-lg14px
--nv-dur200ms
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.

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">

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.