newtone_ui_react-web
Newtone's component library for React on the web.
The authoritative description of this repo is
~/gallina/newtone/ui_react-web/_blueprint/index.md, and the components here discharge~/gallina/newtone/_blueprint/contracts/. If this README and those disagree, they win.
What is here
Twenty-six Thirty-four components and a colour port (recounted with ls src/*/index.ts on 2026-09-25, when the six chart parts arrived in 0.6.0; the twenty-six had gone stale before them). ls src/*/index.ts is the complete public API that
JavaScript can reach; package.json's exports map is the complete one including stylesheets.
This table is the spine and not the list — the blueprint above carries every component.
Surface | Owns the context its contents read: theme, elevation, mode |
Button | Discharges contracts/button.md. Three variants, five states, three size rungs |
Text | Discharges contracts/typography.md. font, weight, case, figures, ligatures |
Navbar | Discharges contracts/navbar.md. Parts and knobs; arrangements belong to the site |
Desktop | Discharges contracts/desktop.md. An OS frame: windows, launcher, panel, sheet (no menu bar or dock: the host has them); the consumer keeps the layout |
Identity | A scoped seed set: re-derives colour for one subtree |
color.ts | A port of contracts/color-derivation.md — the runtime half of identity |
Control sizes
Every control here is one of five heights — 36, 40, 44, 48, 56 — on one of two type pairs,
14/20 or 16/24. A size prop picks a rung and the rung carries its height, its type pair, its
glyph and its padding together; there is no second axis. contracts/button.md, Sizes.
sm | md | lg | xl | |
|---|---|---|---|---|
Control | 36 | 40 | 44 | 48 |
Button, Navbar | 40 | 44 | 48 | — |
Action, QuickAction | 48 | — | 56 | — |
A Control sits a rung below a Button at the first three positions, and xl is the exception.
It exists for controls standing on a photograph — Gallery's arrows, VideoLightbox's close — where
there is no page whose primary action they could compete with.
The idea in one example
import { Surface, Button } from '@newtone-dev/ui-react-web'
import '@newtone-dev/ui-tokens/newtone.css'
import '@newtone-dev/ui-react-web/button.css'
<Surface theme="emphasis">
<Button>Primary</Button>
</Surface>
That Button becomes a light fill with a brand label, and nothing was passed to it.
Components carry no facets. No theme, mode or elevation prop on Button, ever. Its
tokens point at roles, and a role resolves against the Surface it is sitting on. A theme
prop would put the 24-way context product back onto every component, which is precisely
what the role layer exists to prevent.
Scoped identity
<Identity seeds={{ system: { accent: { h: 35, c: 0.78 } } }}>
{/* this subtree wears another brand over the site's own neutrals */}
</Identity>
seeds is shaped like the tokens repo's seed.json — group, then palette, then a hue and
a saturation. A seed is not a colour and has no lightness, because lightness is a
property of the job a colour is doing, and the job is not known until a role asks for it.
c is a ratio from 0 to 1 of the most colourful thing reachable at that lightness and hue,
so c: 1 is the gamut boundary rather than an error, and the same number means the same
request of a yellow as of a blue.
Only the core colour layer is identity-dependent, so this writes 51 custom properties per palette named and nothing else. Everything below is references and follows on its own. Palettes not named inherit from the enclosing scope, and nesting is free because that inheritance is CSS's own.
The derivation is computed, not tabulated: fifty-one steps spaced evenly in CIE L*, with
chroma taken from the Display P3 ceiling. src/color.ts and the tokens repo's
compute/ are two implementations of one contract and must produce the same bytes.
The build
npm run build — tsc to dist/, then copy-styles.mjs, which walks src and copies all 29
stylesheets across verbatim because tsc emits no CSS. dist/ is gitignored and built on publish
by prepublishOnly; there is no bundler.
This section said There is no build until 2026-09-21, and had been wrong since the build
landed. tsconfig.json sets "module": "NodeNext", which is why every relative import here carries
an explicit extension — a bundler resolved from './button' and Node ESM does not.
Consuming
Published to npm as @newtone-dev/ui-react-web. It declares react as a peer (^18 || ^19)
and does not depend on @newtone-dev/ui-tokens: every component reads --newtone-* custom
properties by name, and supplying them is the consuming site's job.
npm install @newtone-dev/ui-react-web @newtone-dev/ui-tokens
import { Surface, Button } from '@newtone-dev/ui-react-web'
import '@newtone-dev/ui-react-web/button.css'
Stylesheets are imported one at a time, per component, and every path a consumer may import is a
key in the exports map. sideEffects names **/*.css so a bundler keeps them.
This section said Nothing is published to npm until 2026-09-21, three weeks after
publishConfig.access and prepublishOnly were added.