Skip to content
JadRizkPublic

About

A HUD design system for React, with WCAG AA enforced at build.

Topics

Resources

Code of conduct

Contributing

Security policy

Stars

2 stars

Watchers

0 watching

Forks

Latest commit

 

History

116 Commits

Folders and files

Repository files navigation

Nexus Cyberdeck: the HUD that passes the audit.

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.

Install

npm install @nexus-cyberdeck/react @nexus-cyberdeck/tokens
import "@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 pack output in the meantime.

Packages

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.

Why this one

  • 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. The hud theme 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.

Browser support

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.

Documentation

  • 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.

Repository layout

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)

Developing

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.

Token architecture

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 build

Editing 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.

The one restricted colour

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.

Themes

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.

Accessibility

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:a11y

axe 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 useFocusTrap implementation used by both Drawer and CommandPalette
  • CommandPalette is a real combobox: input retains focus and owns aria-activedescendant, results are a listbox, 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"> with aria-valuetext
  • Global :focus-visible ring 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-motion collapses every animation, the blink included, and prefers-contrast: more removes the CRT overlay — both asserted against a real renderer
  • The contrast bargain is asserted in both directions: hud-aa passes axe's colour-contrast rule and hud is required to fail it

CRT layer

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.

Visual regression

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 change

Docker 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.

Releasing

Versions and changelogs are managed with Changesets. Any change a consumer could notice needs one:

npx changeset      # pick packages, pick the bump, describe the change

A 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.

What counts as breaking

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.0 was 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.

What is deliberately not here

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.

Known gaps

  • 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.

License

MIT © Jad Rizk

About

A HUD design system for React, with WCAG AA enforced at build.

Topics

Resources

Code of conduct

Contributing

Security policy

Stars

2 stars

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages