A HUD design system for React: acid green on near-black, hairline borders, zero corner radius, corner ticks, monospace everything, and a WCAG AA mode that is enforced at build time rather than promised in a README. It ships with a force-directed WebGL graph canvas that speaks the same language.
20 components, two hooks, a search ranker, 86 tokens, two themes. Dark only and desktop first, built for consoles, dashboards and visualisations rather than marketing pages. React 18.3 or 19.
npm install @nexus-cyberdeck/react @nexus-cyberdeck/tokensimport "@nexus-cyberdeck/tokens/tokens.css";
import "@nexus-cyberdeck/react/styles.css";
import { NexusProvider, Panel, SectionHeading, Stat, Button } from "@nexus-cyberdeck/react";
export default function App() {
return (
<NexusProvider theme="hud-aa">
<Panel corners={["tl", "br"]} raised style={{ width: 280 }}>
<SectionHeading>/// subject</SectionHeading>
<Stat label="Class" value="NODE" tone="info" />
<Button active>Isolate</Button>
</Panel>
</NexusProvider>
);
}That is the whole install. The getting-started guide takes it from here to a command palette and a graph in about ten minutes, and every snippet in it was built from the packed tarballs before it was written down.
The packages are not on npm yet. See the guide for installing from
npm packoutput in the meantime.
| Package | What it is |
|---|---|
@nexus-cyberdeck/tokens |
CSS custom properties for both themes, typed accessors, contrast ratios computed at build time. Zero dependencies. |
@nexus-cyberdeck/react |
The 20 components, useFocusTrap, useHotkey, rankItems. Depends only on tokens. |
@nexus-cyberdeck/graph |
Force-directed WebGL canvas on Three.js: SDF glyph nodes, links that carry kind in form and direction in their ends, CRT post-process, and keyboard and screen-reader navigation. Versioned separately; no dependency on the other two. |
Not using React? @nexus-cyberdeck/tokens is plain CSS. Set data-nx-theme
on any element and the custom properties cascade.
- The accessible mode is the default, and it is checked by machines. Each
theme declares the contrast floors it holds itself to in
tokens.json, and the token build refuses to emit if a colour moves past one. axe-core runs over every route, component and overlay state in CI. Thehudtheme is required to fail the contrast rule, so the documented trade-off cannot quietly become an undocumented one. - Category is never colour alone. Six glyph silhouettes carry meaning (WCAG 1.4.1), the criterion most dark-neon systems fail.
- The blink is capped at 0.94 Hz. The prototype flickered at 9 Hz, above the 3 Hz seizure threshold in WCAG 2.3.1. That is a Level A failure, not a taste.
- A real token architecture. W3C DTCG source of truth, generated CSS, lint rules that stop a component from touching a primitive, and a component-token layer you retheme with one custom property on any ancestor.
- The graph is included. Most systems stop at the panel. This one ships the canvas the panels were designed around.
Evergreen browsers — the current and previous versions of Chrome, Edge,
Firefox and Safari. The floor is Safari 15.4+, because the focus ring is
built on :focus-visible, which Safari did not ship until 15.4; on anything
older the ring never appears and keyboard users lose the only focus indicator
the system draws.
@nexus-cyberdeck/graph additionally requires WebGL2, and that is a hard
requirement rather than a preference: its Three.js renderer asks for a
webgl2 context and nothing else, and there is no 2D or DOM fallback. Where
WebGL2 is unavailable or the context is lost, the canvas calls onFatal and
renders nothing further — handle that prop and show your own fallback. A lost
context stays lost as far as the canvas is concerned: three's renderer asks the
browser to restore it (it calls preventDefault() on webglcontextlost), but
the canvas deliberately does not resume when that happens, so recovering means
remounting it.
- Getting started: zero to a themed console, verified against a real install.
- Component reference: every component, the colour props, the accessibility guarantees.
- Tokens reference: every custom property, the typed accessors, the DTCG-shaped source file.
- Graph reference: data model, props, controller.
- STYLING.md: the rule behind the component-token layer and the specificity trap it avoids.
- The showcase (
npm run dev) has a docs section (getting started, seven Foundations pages generated from the tokens, a page per component and a page per hook), plus the Graph and Glitch Lab. Component pages render live examples, most with a rationale note and a code sample and some with an accessibility note. - BRAND.md: the identity behind the mark, palette and voice.
- CONTRIBUTING.md: how to contribute, and how releases are authorised.
nexus/
├── packages/
│ ├── tokens/ @nexus-cyberdeck/tokens CSS custom properties + typed handles
│ │ ├── build-tokens.mjs the generator
│ │ ├── lib/wcag.mjs contrast maths, dependency-free
│ │ └── src/
│ │ ├── tokens.json SOURCE OF TRUTH — the only file to edit
│ │ ├── tokens.css generated · both themes
│ │ ├── contrast.gen.ts generated · computed ratios
│ │ ├── base.css hand-authored base + focus rules
│ │ ├── roles.ts semantic role names
│ │ ├── crt.css CSS-only CRT layer
│ │ └── index.ts typed accessors
│ ├── react/ @nexus-cyberdeck/react 20 components, no runtime deps
│ │ ├── build-styles.mjs assembles the shipped stylesheet
│ │ └── src/
│ │ ├── components/<Name>/ one folder per component:
│ │ │ <Name>.tsx · <Name>.css · <Name>.test.tsx
│ │ ├── hooks/ useFocusTrap, useHotkey (+ tests)
│ │ ├── search/ rankItems (+ tests)
│ │ ├── colour.ts the tone/colour resolver
│ │ └── styles.css generated · concatenated components
│ └── graph/ @nexus-cyberdeck/graph force-directed WebGL canvas
├── apps/showcase/ Home · Docs (start, Foundations, components, hooks) · Graph · Glitch Lab
├── brand/ BRAND.md, PALETTE.md and the generated mark and social assets
├── browser/ visual regression + axe suite (Playwright, pinned container)
├── docs/ getting-started guide
├── reference/ preview.jsx — the whole system in one generated file
├── scripts/ build-preview, brand-*, check-docs, check-changeset, ds-figures, browser-tests, …
└── .changeset/ pending release notes (see Releasing)
Node 22.12 or newer. The repo develops against React 19; CI also runs the typecheck and unit tests against React 18.
npm install
npm run build # tokens → react → graph with tsup (ESM + CJS + .d.ts), then the preview
npm run dev # showcase on :5173
npm run typecheck # tsc, strict
npm run lint # eslint + stylelint
npm run test # unit tests, all workspaces
npm run test:browser # visual regression + a11y (needs Docker)One folder per component, holding everything about it: implementation, its
own CSS where it needs any, and its tests. styles.css is generated by
npm run build:styles; edit the component's own stylesheet. Components import
each other by path rather than through the barrel, so an import cycle is not
possible, and adding a component means adding a folder. There is no central
list to remember to update.
The figures the showcase advertises (version, token count, component count)
are read from the code at build time by scripts/ds-figures.mjs, and
scripts/check-docs.mjs fails CI if prose anywhere quotes a stale copy.
src/tokens.json is the source of truth, in W3C DTCG format. tokens.css and
contrast.gen.ts are generated from it:
npm run build:tokens # regenerates both; runs as part of npm run buildEditing either generated file by hand is caught in CI. The source file is
DTCG-structured ($value/$type/$description); values are written as CSS
strings (hex colours, rem/ms dimensions, cubic-bezier()) rather than the
newer structured DTCG value shapes, so treat it as DTCG-flavoured rather than
a strict DTCG document a tool is guaranteed to import unchanged.
Three layers. Components may reference only the semantic layer, enforced by ESLint and stylelint rather than by convention.
primitive --nx-acid, --nx-grey-300 raw values, never used directly
semantic --nx-fg-accent, --nx-border-strong roles, what components use
component --nx-btn-border, --nx-panel-padding per-component, overridable from any ancestor
Both themes define every semantic name, so switching themes never touches component code.
Magenta is reserved for alarm states: unresolved items and conflicts, nothing
else. That restraint is why it reads as a warning rather than decoration.
--nx-alarm has exactly one semantic alias, --nx-fg-critical. There is no
general accent alias, so it cannot quietly become a button colour.
hud-aa (default) |
hud |
|
|---|---|---|
| muted ramp | lifted, AA-compliant | the prototype's original |
| type scale | ×1.15 | ×1.0 |
| disabled text | 4.82:1 | 2.14:1 ✗ |
| UI boundaries | 3.19:1 | 1.57:1 ✗ |
The signature colours are identical in both. Acid 14.98:1, data 12.19:1, lime 15.20:1, sodium 8.32:1, violet 6.27:1, alarm 5.44:1, phosphor 16.84:1. All already clear AA, which is why the accessible theme needed no redesign. Only the muted ramp had to move, and it was solved rather than eyeballed: hue 100°, saturation 13%, binary-searched per step against exact contrast targets.
Every ratio quoted is measured against the panel surface, --nx-bg-surface.
The floors are enforced on every opaque background a component can render
on — including --nx-bg-raised, which is lighter than the panel and so is
where the ramp binds. That is why the two figures above sit above their floors
rather than on them: 4.82:1 and 3.19:1 on the panel are 4.54:1 and 3.00:1 on
the raised surface, and the raised number is the one that had to clear.
Every ratio quoted above is computed at build time from the resolved token
values, including the comments in tokens.css itself. Each theme declares the
floors it holds itself to in tokens.json, and the build fails if a colour
moves past one, naming the surface it failed on:
hud-aa/grey-300 is 4.25:1 on --nx-bg-raised (#11150F), below the 4.5:1 floor
for disabled text — WCAG 1.4.3.
That check is itself tested: lib/build-tokens.test.mjs feeds the generator a
deliberately broken palette and asserts it refuses to emit.
Every claim below is asserted by a machine. browser/a11y.spec.ts runs
axe-core over the real rendered page, once per route, once per component and
once per overlay state, and browser/a11y-claims.spec.ts makes direct
assertions for the things axe cannot see.
npm run test:a11yaxe is treated as a floor, not a ceiling. It found a malformed listbox in
CommandPalette's empty state and a scrollable region with no keyboard access;
it did not notice that the showcase traps focus in a modal drawer at page
load. Automated coverage does not replace using the thing with a keyboard.
Verified behaviours:
- Focus trap, focus restoration, Escape: one shared
useFocusTrapimplementation used by both Drawer and CommandPalette - CommandPalette is a real combobox: input retains focus and owns
aria-activedescendant, results are alistbox, a live region announces the result count - ToggleRow is a real checkbox, visually hidden but focusable and announced
- TabStrip uses roving tabindex with arrow/Home/End
- Slider stays a native
<input type="range">witharia-valuetext - Global
:focus-visiblering that cannot be removed per component - Glyphs carry category by shape, satisfying 1.4.1
- Blink capped at 0.94 Hz, below the 3 Hz threshold in WCAG 2.3.1
- Slider tracks use
--nx-border-strong(3:1) not the decorative hairline, because a track is a UI component boundary under 1.4.11 prefers-reduced-motioncollapses every animation, the blink included, andprefers-contrast: moreremoves the CRT overlay — both asserted against a real renderer- The contrast bargain is asserted in both directions:
hud-aapasses axe's colour-contrast rule andhudis required to fail it
The graph's CRT is a four-pass GPU pipeline: render to texture, a thresholded horizontal blur, a vertical blur, then a composite with barrel distortion, chromatic aberration, aperture grille, rolling refresh bar, grain and glitch slicing. You cannot run that behind every panel in an application.
crt.css gets most of the read for one composited pseudo-element and no
JavaScript. Reserve the shader version for a hero canvas.
<div class="nx-crt nx-crt--roll nx-crt--grain">…</div>
<span class="nx-crt-split">CHROMATIC FRINGING</span>Two switches turn the layer off outright: data-nx-crt="off", an author
decision, and prefers-contrast: more, because someone asking for more
contrast should not be fighting a scanline overlay. Under
prefers-reduced-motion the rolling refresh bar stops and is removed; the
static scanlines stay, since they are texture rather than motion.
The visual suite covers the things jsdom cannot see: Panel's corner ticks, focus rings, hover states, both themes, the CRT layer, and the overlays.
npm run test:visual # run the suite
npm run test:browser:update # re-record after an intended visual changeDocker is required, and that is deliberate. Chromium renders text
differently on macOS and Linux, so a baseline captured on a laptop fails on CI
for reasons unrelated to the change, which is how visual suites end up
permanently red and then permanently ignored. There is one supported renderer:
the official Playwright container, pinned to the same version as the
@playwright/test dependency. CI runs the job in that image; the script above
runs the same image locally. Baselines are therefore Linux-only and byte-
comparable everywhere.
The comparison threshold is zero differing pixels. If the suite ever goes flaky the fix is to stabilise the input (wait for a font, disable an animation, pin a viewport), never to widen the tolerance. An earlier draft of this config allowed a 0.2% pixel ratio, which sounds conservative and permits around 360 changed pixels on a panel screenshot; Panel's four corner ticks are roughly 120 pixels in total, so deleting the entire corner-tick system passed.
Versions and changelogs are managed with Changesets. Any change a consumer could notice needs one:
npx changeset # pick packages, pick the bump, describe the changeA pull request that touches packages/*/src must add its own changeset, and
CI fails it otherwise; a changeset already pending on main from earlier work
does not count. The entry you write becomes the changelog verbatim, so write
it for someone upgrading.
A breaking change is any change that could require a consuming application to update. Major bump, always:
- Removal or rename of an exported name — component, hook, type, constant or function.
- Addition of a required prop, or removal of any prop, on an exported component.
- Change to an existing prop's type, default or behaviour.
- Removal or rename of an
nx-*class on a rendered element. The DOM is part of the contract here, because the whole restyling story is consumers writing CSS against those classes:react@3.0.0was a major with no API change at all, purely because the markup moved from inline styles to classes. - Removal or rename of a
--nx-*custom property, or a change to what an existing one means.
Not breaking, and not a major bump: adding an optional prop, adding an
export, adding an nx-* class or a --nx-* property, and any internal change
that leaves all of the above intact.
Those two lists are the whole rule and they apply to every exported component
equally. A component with a closed prop interface — one that declares its own
Props type instead of extending an HTML element's — is not exempt from them.
A closed interface says which props the component accepts; it says nothing
about how stable those props are, and changing one of them is as breaking
there as anywhere else. (Adding an optional prop to a closed interface is
still fine, by the second list, same as everywhere else.)
@nexus-cyberdeck/tokens and @nexus-cyberdeck/react are versioned in
lockstep, and react depends on an exact tokens version rather than a
range. The two communicate through CSS custom property names at runtime: a
component asking for a token a newer build no longer defines does not fail to
compile, it renders the wrong colour. Pinning is what makes that mismatch
unreachable. @nexus-cyberdeck/graph versions independently, because it is a
product built with the system rather than part of it.
The packages are still "private": true, and that flag is the deliberate hold
on the first publish. With it set, changeset version (run as
version:packages when the release workflow opens the Version Packages pull
request) still bumps the version and writes the changelog, and
changeset publish creates the git tag but skips the registry
(privatePackages: { version: true, tag: true } in .changeset/config.json),
while a by-hand npm publish is refused. The release workflow is already
wired, and it publishes through npm trusted publishing (OIDC) — see
How publishing is authorised
in CONTRIBUTING. There is no NPM_TOKEN secret and none should be added: a
token on the publish step would make npm use it instead and silently bypass
provenance. Starting to publish needs the nexus-cyberdeck organisation to
exist on npm. Then private comes off a package in the same pull request as
its manual first publish, tokens before react (which pins an exact tokens
version), and trusted publishing takes over for every release after that
first manual one.
A light theme, responsive breakpoints, text inputs, a generic dialog. The first two are positioning: this is a dark, desktop-first HUD language and it would be a worse one if it tried to be a general kit. The last two are gaps, listed below.
- No keyboard path to a canvas surface (WCAG 2.1.1). This belongs in the consuming visualisation, not the component layer; provide a list or a palette beside the graph.
- No responsive layout. The showcase and the Drawer assume a desktop viewport. Nothing overflows on a phone, but the drawer covers it.
- No text input, select or generic dialog. The palette has an input internally; a standalone one is the first post-launch component.
- No Storybook. The showcase covers the same ground with rationale notes and code samples; a decision on Storybook is pending rather than made.
MIT © Jad Rizk
