retro-displayz

A retro inspired HUD-aesthetic web component library built with Lit. Components are framework-agnostic custom elements — use them in React, Vue, plain HTML, or any other stack.

Live Showcase

Components

| Element | Description | |---|---| | <hud-input> | Text input with scan-line focus animation | | <hud-button> | Button with ghost / primary / danger variants | | <hud-toggle> | Switch with sliding thumb, ON/OFF label | | <hud-checkbox> | Checkbox with animated checkmark, indeterminate support | | <hud-range> | Range slider with custom track and fill | | <hud-select> | Custom listbox with keyboard navigation | | <hud-combobox> | Typeahead combobox with highlighted match text | | <hud-audio> | Audio player with Web Audio frequency visualizer | | <hud-status> | Pulsing status dot — idle / loading / ready / error | | <hud-progress> | Linear progress bar, determinate and indeterminate scan | | <hud-textarea> | Multiline input with optional character counter | | <hud-number> | Numeric input with [−] [+] step controls | | <hud-toast> | Fixed notification — info / success / warning / error, auto-dismiss | | <hud-gauge> | Radial SVG meter with animated fill arc |

All form components are form-associated custom elements — they participate in native <form> submit and FormData without any wrapper.

Running Locally

npm install
npm run dev

Requires Node 18+.

Design Tokens

Every visual property is driven by CSS custom properties defined in src/styles/tokens.css. These pierce Shadow DOM natively, so overriding them at :root (or on any ancestor element) themes all components at once:

:root {
  --cyan:   #00e5ff;
  --bg:     #06090f;
  --font-mono: 'Your Font', monospace;
}

Accessibility Caveats

Several known issues remain. Contributions welcome.

Color contrast: The HUD palette deliberately uses muted, dark tones. Most informational text now passes WCAG 2.1 AA (≥ 4.5:1), but some decorative states — dimmed --text-faint elements in non-interactive contexts — may fall below recommended minimums on non-standard display profiles.

Missing aria-activedescendant in hud-select: hud-combobox has aria-activedescendant wired to option IDs, but hud-select does not yet — keyboard navigation in the listbox is not announced by screen readers. This is the most important remaining gap.

No accessible name enforcement: hud-toggle and hud-checkbox with no label attribute will render without an accessible name. The components do not currently warn or throw when this happens.

hud-audio seek bar: The seek bar has aria-valuemin/max/now but no human-readable aria-valuetext (e.g., "1:23 of 3:45"). Screen readers announce a raw percentage.

prefers-reduced-motion: CSS transitions and animations are suppressed via @media (prefers-reduced-motion: reduce), but the Web Audio requestAnimationFrame visualization loop in hud-audio is not yet gated on this preference.

Roadmap

Package release

The goal is to publish these as a proper npm package so they can be consumed by any project:

# Planned — not yet released
npm install retro-displayz

<script type="module">
  import 'retro-displayz'   <!-- registers all elements -->
</script>
<hud-input label="Callsign"></hud-input>

Before release the following needs to happen:

• [ ] Separate the library build (vite --mode lib) from the showcase build so dist/ contains only the component bundle
• [ ] Publish dist/index.js + dist/index.d.ts to npm — package.json needs "exports", "types", and "files" fields
• [ ] Document the token override API and theming guide
• [ ] Add unit tests (Lit recommends @web/test-runner + @open-wc/testing)
• [ ] Set up a changelog (changeset or conventional-commits)
• [ ] Fix remaining accessibility gaps listed above before calling it stable

Additional components

• [x] hud-textarea — multiline input with character counter
• [x] hud-number — numeric input with [−] [+] step controls
• [x] hud-progress — linear progress bar (determinate + indeterminate scan)
• [x] hud-status — pulsing status dot with idle / loading / ready / error states
• [x] hud-toast — notification that enters from the edge, auto-dismisses
• [x] hud-gauge — radial meter that animates to a value
• [ ] hud-datepicker — date input with keyboard-navigable calendar grid (deferred)
• [ ] hud-video — custom video player with timecode display (deferred)

Infrastructure

• [x] Storybook integration — npm run storybook · stories + autodocs + a11y audit for all 14 components
• [ ] GitHub Pages deploy for Storybook (build-storybook output)
• [ ] hud-select aria-activedescendant (mirrors the fix already applied to hud-combobox)
• [ ] Accessible name enforcement — warn in dev mode when required label is missing

License

MIT