newtone_ui_react-web

Newtone's component library for React on the web.

The authoritative description of this repo is ~/source/blueprints/newtone/repos/newtone_ui_react-web.md, and the components here discharge ~/source/blueprints/newtone/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 | | 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 | | --- | --- | --- | --- | | Control | 36 | 40 | 44 | | Button, Navbar | 40 | 44 | 48 | | Action, QuickAction | 48 | — | 56 |

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.