Enterprise Healthcare Web Component Library

A production-ready Web Component library built with Lit 3.x and TypeScript for healthcare organizations that demand accessibility compliance, design token theming, and Drupal CMS integration.

Documentation · Storybook · NPM Package · Contributing

---

Quick Start

npm install @helixui/library

Then use components in your HTML:

<script type="module">
  import '@helixui/library';
</script>

<hx-button variant="primary">Get Started</hx-button>

<hx-card variant="featured" elevation="raised">
  <span slot="heading">Patient Portal</span>
  <p>Accessible, themeable components for healthcare UIs.</p>
  <hx-button slot="footer" variant="primary">Learn More</hx-button>
</hx-card>

Or import individual components for optimal tree-shaking:

import '@helixui/library/components/hx-button';
import '@helixui/library/components/hx-card';

---

Why HELiX?

• Healthcare accessibility built in — Self-certified to WCAG 2.2 AAA on the 44 P0 components (per packages/hx-library/aaa-verdicts.json: 376 Supports / 109 Not Applicable / 0 Partial / 0 Fail), with WCAG 2.2 AA as the baseline for the rest of the library. Exceeds the current HHS Section 504 digital accessibility requirement (WCAG 2.1 AA); the HHS extension pushed the original May 2026 compliance deadline into 2027–2028 for federally funded healthcare providers — see the HHS Section 504 final rule for the current dates. Every component is keyboard-navigable, screen reader compatible, and tested with axe-core.

• Framework-agnostic Web Components — Built on Lit 3.x and the Web Components standard. Works in React, Angular, Vue, Drupal, or plain HTML. No framework-specific adapter is required; optional @helixui/react wrappers are available for ergonomic React integration.

• Design token theming — Three-tier token architecture (primitive → semantic → component) with CSS custom properties. Theme entire applications by overriding --hx-* tokens — light mode, dark mode, and high contrast modes included.

• Enterprise-grade quality — TypeScript strict mode, 81 component directories registering 102 custom elements (see packages/hx-library/custom-elements.json for the authoritative list), 3-tier code review, automated accessibility testing, and most components <5KB gzipped (hx-theme is larger due to design token imports). Built for organizations where software failures impact patient care.

---

Components

HELiX ships 81 component directories that register 102 custom elements (the authoritative list lives in packages/hx-library/custom-elements.json). A curated selection of the most commonly consumed elements:

Category	Components
Actions	hx-button, hx-button-group, hx-copy-button, hx-action-bar
Forms	hx-text-input, hx-checkbox, hx-radio-group, hx-select, hx-combobox, hx-date-picker, hx-file-upload, hx-form
Data Display	hx-card, hx-data-table, hx-list, hx-tree-view, hx-badge, hx-avatar, hx-tag
Feedback	hx-alert, hx-toast, hx-progress-bar, hx-spinner, hx-skeleton
Navigation	hx-breadcrumb, hx-tabs, hx-pagination, hx-side-nav, hx-menu
Layout	hx-grid, hx-container, hx-divider, hx-top-nav, hx-stack
Overlays	hx-dialog, hx-drawer, hx-tooltip, hx-popover, hx-dropdown

Browse all components in Storybook →

---

Documentation

Full documentation is available at helix.bookedsolid.tech:

• Getting Started — Installation, setup, and first component
• Component API Reference — Auto-generated from Custom Elements Manifest
• Design Tokens — Token architecture, theming guide, and token reference
• Drupal Integration — Twig templates, Drupal behaviors, and CDN delivery
• Accessibility — WCAG compliance guide and testing procedures

---

Drupal Integration

HELiX is designed for seamless Drupal CMS integration:

{# node--article--teaser.html.twig
   hx-card variants: default | featured | compact. Use hx-href (component
   attribute) + hx-label for the interactive whole-card pattern; the card
   then dispatches hx-click rather than performing default browser navigation. #}
<hx-card
  variant="featured"
  elevation="raised"
  hx-href="{{ url }}"
  hx-label="Read {{ node.label }}"
>
  <img slot="image" src="{{ image_url }}" alt="{{ image_alt }}" />
  <span slot="heading">{{ node.label }}</span>
  {{ node.body.summary }}
</hx-card>

See the Drupal Integration Guide for complete setup instructions, Twig patterns, and JavaScript behaviors.

---

Development

Prerequisites

• Node.js 22 LTS or Node.js 24 (Node 20 reaches upstream EOL on 2026-04-30)
• pnpm 9+ (via Corepack: corepack enable)
• Git

Setup

git clone https://github.com/bookedsolidtech/helix.git
cd helix
pnpm install
pnpm run dev        # Start library + Storybook + docs

Commands

pnpm run dev            # All apps + library (Turborepo)
pnpm run dev:storybook  # Storybook on port 3151
pnpm run dev:docs       # Documentation site on port 3150
pnpm run build          # Build everything
pnpm run test           # Run all tests (Vitest browser mode)
pnpm run type-check     # TypeScript strict check
pnpm run verify         # Lint + format:check + type-check + build (quick gate)
pnpm run preflight      # Required before push — runs the full 12-gate preflight
                        # (lint, format, type-check, build, smart tests, CEM drift,
                        # changeset check, full test matrix, Docker CI parity,
                        # AAA verdict integrity, docs version drift, docs claims
                        # fact-check; see scripts/preflight.sh)

---

Tech Stack

Layer	Technology
Components	Lit 3.x, Shadow DOM, CSS Parts, ElementInternals
Language	TypeScript (strict mode)
Build	Vite library mode, per-component entry points
Testing	Vitest browser mode + Playwright
API Docs	Custom Elements Manifest (CEM)
Stories	Storybook 10.x
Docs	Astro Starlight
Monorepo	Turborepo + pnpm workspaces

---

Contributing

See CONTRIBUTING.md for guidelines. All contributions must:

• Pass TypeScript strict mode (pnpm run type-check)
• Include tests with 80%+ coverage
• Meet WCAG 2.2 AAA on P0 surfaces / AA baseline elsewhere (verified via pnpm aaa:audit)
• Include Storybook stories for all variants

---

License

MIT

---

Documentation · Storybook · NPM · Issues

Built with care for healthcare.