@arbingerinstitute/ui

Arbinger's shared component library and theme system. One semantic token contract, many themes, zero dark: classes.

Why this exists

The previous library (@arbingerinstitute/ui-legacy) uses 191 distinct color utilities named after positions on a palette ramp — bg-neutral-700, text-primary-1000 — plus 1,658 hand-written dark: variants across the repo. Those names carry no meaning to translate, so a second theme has to be authored one class at a time, and a third is impractical.

This package inverts that. Components reference 43 semantic tokens. A theme is a flat list of those 34 values in a plain CSS file. Adding Gruvbox costs one 57-line file and no component changes.

Quick start

pnpm add @arbingerinstitute/ui

If the app does not use Tailwind, that is the whole integration:

import "@arbingerinstitute/ui/styles.css"
import { Button } from "@arbingerinstitute/ui/Button"

styles.css is precompiled and carries every utility the components use plus all four themes. If the app does run Tailwind v4, import theme.css and the themes you want instead, and add @source "../node_modules/@arbingerinstitute/ui/dist"; — Tailwind does not scan node_modules, and without that line the components render unstyled.

See AGENTS.md for the full component list, the token vocabulary, self-hosted fonts, and the flash-of-wrong-theme script. That file is written for coding agents, and it is also the fastest reference for people.

How theming works

theme.css declares the contract in a Tailwind v4 @theme static block, so bg-surface compiles to background-color: var(--color-surface). Each theme file overrides those variables under html[data-theme="name"], and the data-theme attribute is the only switch.

Two details that are easy to get wrong:

• Theme files must stay unlayered. Tailwind emits @theme defaults inside @layer theme, and unlayered rules beat layered ones regardless of specificity. Wrapping a theme in @layer makes the override silently lose.
• Never use @theme inline for a themeable token. It inlines the literal value instead of emitting a var(), which kills runtime switching. shadcn's v4 template uses inline, so this is easy to copy by accident.

Because a theme is plain CSS with no build step, a designer or a customer can author one without touching TypeScript.

Accessibility

pnpm check:contrast validates every theme against the contract and against 17 WCAG AA pairs — body text, secondary text, placeholders, links, button labels, control borders, focus rings, and all four status tones in both solid and tinted form.

It is a build gate, not a linter, because a theme is data and data gets contributed. It has already caught genuine problems in the existing brand palette — failing body text, unusable placeholder greys, and low-contrast control borders, all now fixed.

It also carries one accepted exception. White button labels on the brand cyan are 2.78:1, below the 4.5:1 AA needs for text. That is a deliberate brand requirement, and it matches what the Outward app already ships, so it is recorded in ACKNOWLEDGED_EXCEPTIONS rather than silenced: the reason prints on every run, and the check still fails if the ratio ever drops below the accepted 2.78:1.

Adding an entry to that list is a deliberate act requiring a reason. It is not a way to make a new theme pass.

Development

pnpm playground        # every component, live theme switcher, port 5180
pnpm test              # 50 unit tests
pnpm check:contrast    # token contract + WCAG gate
pnpm typecheck
pnpm lint
pnpm build             # tsup ESM + .d.ts, assets, compiled styles.css
pnpm fonts             # re-fetch Montserrat from Google and regenerate fonts.css

The playground is a falsification tool: if a component hardcodes a color, switching to Gruvbox makes it obvious in one click.

Releasing

Bump the version in package.json, then tag ui-v<version>:

git tag ui-v0.0.1 && git push origin ui-v0.0.1

The tag prefix is deliberate — the repo already uses bare semver tags for the portal and API deploys, so an unprefixed tag would collide. It also extends to the other packages later (feature-flags-v1.2.0) without them sharing a namespace.

UI-Publish checks the tag against the manifest, runs typecheck, lint, the contrast gate and the tests, then builds, packs and publishes. workflow_dispatch offers a dry run that packs without publishing. Requires an UI_NPM_TOKEN secret — a granular npm token scoped to the @arbingerinstitute org. The workflow checks it is present before doing any work.

The token needs Bypass 2FA enabled, which npm leaves unchecked by default. Without it the publish runs the whole build and then dies on npm error code EOTP, asking for an authenticator code no CI run can supply. Do not try to automate the code itself — the TOTP seed would have to live in CI beside the token, which is the second factor, and npm is phasing TOTP out regardless.

Two clocks on this. npm caps write-capable granular tokens at 90 days, so the secret needs re-cutting every quarter. And direct publishing from a bypass-2FA token is deprecated as of January 2027, after which such a token can only stage a publish for a human to approve. The exit from both is npm trusted publishing — OIDC, no stored token — which needs id-token: write adding back to the workflow.

Provenance is deliberately off. npm will only verify a provenance bundle whose source repository is public, and rejects one from a private repo with E422 Unsupported GitHub Actions source repository visibility: "private". It stays off until this repo is public, so the published tarball carries no provenance attestation and no npm "Built and signed" badge.

Licensing

MIT — see LICENSE. Copyright (c) 2026 The Arbinger Institute.

The licence covers this package only. The surrounding monorepo is not MIT, and publishing an MIT package from it does not relicense anything else in the repo.

Third-party notices live in THIRD_PARTY_LICENSES.md and ship in the published tarball. Two things there are worth knowing:

• Montserrat is redistributed. The woff2 binaries are inside the package, so the SIL Open Font License travels with them at dist/fonts/OFL.txt. Both the build and CI fail if it goes missing.
• Radix is a dependency, not vendored. Every Radix reference in dist/ is a bare import specifier, so no third-party source is inlined and each Radix package delivers its own MIT notice on install. The component structure comes from shadcn/ui, which is credited as the design origin.

Status

0.0.1 — early. The token names are the public API and are not yet frozen; expect churn before 0.1.0.

Verified against real consumers: a Vite app with no Tailwind at all (precompiled styles.css), a Vite app running Tailwind v4, and a webpack + babel-loader app with the conventional exclude: /node_modules/. Types resolve and prop unions are enforced in all three.