Mozilla Nova-styled web components written in TypeScript with Lit. The design tokens are compiled from Firefox's Nova design system, and the icons and illustrations from FirefoxUX/acorn-icons, so the components match Firefox and can be kept up to date with it.
[!NOTE]
This project is still in development and may experience changes. This project is also built by and for the AMO team primarily and not the Acorn team.
What's inside
<moz-provider> provides ambient theme, locale, and high-contrast state to its descendants.
The Nova design tokens, as CSS custom properties and a typed map.
A set of Nova-styled components:
Actions: <moz-button> (default / primary / destructive / ghost / muted, plus icon-only; menu-id points it at a panel list), <moz-chip>, <moz-panel-list> with <moz-panel-item> and <moz-panel-row> (an anchored action menu, with an optional header, subheadings, separators and submenus).
Forms: <moz-input-text> (text / email / url / tel), <moz-input-search> (debounced search field), <moz-checkbox> (with <moz-checkbox-all> for select-all and <moz-checkbox-visual> for display-only), <moz-select> (the platform popup, or a <moz-panel-list> one via popup="panel"), <moz-radio-group> with <moz-radio>, <moz-toggle> (a switch), <moz-label>, <moz-fieldset> — form-associated, with built-in labelling, description, and validation.
Status & feedback: <moz-message-bar>, <moz-badge>, <moz-status-badge> (a status-colored pill), <moz-status-dot> (a status dot), <moz-five-star> (a read-only or selectable star rating).
Primitives: <moz-icon> renders a named icon from the Nova set; <moz-illustration> renders a named illustration (kit pieces and pictograms), following the ambient theme for its light/dark variants.
These are standard custom elements, so they work in plain HTML and in any framework (React, Vue, Svelte, and so on). Typed React wrappers are included for a more idiomatic React API.
Installation
Published to npm as @mozilla/lit-web-components — a public scoped package, so no registry configuration or token is needed:
npm install @mozilla/lit-web-components
lit and @lit/context are dependencies and install automatically. react and react-dom are optional peer dependencies, needed only if you use the @mozilla/lit-web-components/react entry.
Quick start
Load the token layer once at your app root, then import and use the components.
// Once, at the app entry: the foundation (tokens + document defaults).import '@mozilla/lit-web-components/foundation.css';// Import the components you use (they self-register):import '@mozilla/lit-web-components/components/moz-button';import '@mozilla/lit-web-components/components/moz-icon';
foundation.css is everything you need, but you can also import style sheets individually if you need finer control over load order.
Importing from the package root (import '@mozilla/lit-web-components') registers every component. Importing a per-component subpath pulls in only what you use.
Theming and ambient state
Most theming is pure CSS: the tokens use light-dark(), so light and dark follow color-scheme. Wrap a subtree in <moz-provider> to control that, plus locale and high contrast, from the app:
<moz-provider theme="auto" locale="en-US" contrast="auto"> <!-- your app --></moz-provider>
theme: light | dark | auto (sets color-scheme).
contrast: auto | high. high turns on the higher-contrast token set for everything inside. High contrast also responds to the OS automatically through @media (prefers-contrast) and @media (forced-colors).
locale: BCP-47 locale, broadcast for future internationalization.
Per-component appearance is set through the token scales rather than arbitrary values (see each component below).
React
The React entry provides typed wrappers so props and events follow React conventions:
import { MozButton, MozProvider } from '@mozilla/lit-web-components/react';import '@mozilla/lit-web-components/foundation.css';export function App() { return ( <MozProvider theme="auto"> <MozButton variant="primary" onClick={save}>Save</MozButton> </MozProvider> );}
Design tokens
The tokens ship as CSS custom properties in tokens.css (foundation, on :root), and also as a typed map:
import { tokens, type TokenName } from '@mozilla/lit-web-components/tokens';// tokens['--color-accent-primary'] === 'light-dark(var(--color-violet-50), var(--color-violet-30))'
Component-specific tokens (--button-*, and so on) are scoped to each component's shadow root, so they don't leak into the global surface by default.
all-tokens.css
If, for example, you have an exisiting app in a previous design system, and want to attempt a blanket update without consuming these components. all-tokens.css re-exports the full set of tokens — foundation plus every component's tokens — on :root:
It's larger than tokens.css and everything sits in the @layer acorn.tokens cascade layer, so your own unlayered CSS overrides it without a specificity fight. Set color-scheme on :root (or use <moz-provider>) so the light-dark() values resolve.
Package exports
Entry
Contents
@mozilla/lit-web-components
All components + tokens/option maps + types
@mozilla/lit-web-components/components/<name>
A single component (e.g. moz-button)
@mozilla/lit-web-components/foundation.css
Tokens + base defaults (one import)
@mozilla/lit-web-components/tokens.css
Foundation tokens as CSS custom properties
@mozilla/lit-web-components/all-tokens.css
Every token (foundation + all component tokens) on :root (opt-in; larger than tokens.css)