https://github.com/bookedsolidtech/helix
HELiX — 72-component enterprise web component library built with Lit 3.x and TypeScript. WCAG 2.1 AA compliant, W3C design tokens, Storybook 10, Drupal-ready. Includes Custom Elements Manifest for AI-assisted development via MCP.
https://github.com/bookedsolidtech/helix
accessibility ai-tools component-library css-custom-properties custom-elements custom-elements-manifest design-system design-tokens drupal enterprise healthcare lit mcp monorepo shadow-dom storybook turborepo typescript wcag web-components
Last synced: 27 days ago
JSON representation
HELiX — 72-component enterprise web component library built with Lit 3.x and TypeScript. WCAG 2.1 AA compliant, W3C design tokens, Storybook 10, Drupal-ready. Includes Custom Elements Manifest for AI-assisted development via MCP.
- Host: GitHub
- URL: https://github.com/bookedsolidtech/helix
- Owner: bookedsolidtech
- License: mit
- Created: 2026-02-15T19:01:44.000Z (4 months ago)
- Default Branch: main
- Last Pushed: 2026-04-19T07:03:40.000Z (about 2 months ago)
- Last Synced: 2026-04-19T07:12:53.289Z (about 2 months ago)
- Topics: accessibility, ai-tools, component-library, css-custom-properties, custom-elements, custom-elements-manifest, design-system, design-tokens, drupal, enterprise, healthcare, lit, mcp, monorepo, shadow-dom, storybook, turborepo, typescript, wcag, web-components
- Language: TypeScript
- Homepage:
- Size: 25.6 MB
- Stars: 1
- Watchers: 0
- Forks: 0
- Open Issues: 2
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- Contributing: CONTRIBUTING.md
- License: LICENSE
- Audit: AUDIT-DEVELOPER-EXPERIENCE.md
- Codeowners: .github/CODEOWNERS
- Notice: NOTICE
Awesome Lists containing this project
README
### 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.
[](https://www.npmjs.com/package/@helixui/library)
[](https://github.com/bookedsolidtech/helix/actions)
[](LICENSE)
[](packages/hx-library)
[](tsconfig.base.json)
[](https://www.w3.org/TR/WCAG21/)
[](https://helix.bookedsolid.tech)
[](https://helix-storybook.bookedsolid.tech)
[Documentation](https://helix.bookedsolid.tech) · [Storybook](https://helix.bookedsolid.tech/storybook/) · [NPM Package](https://www.npmjs.com/package/@helixui/library) · [Contributing](CONTRIBUTING.md)
---
## Quick Start
```bash
npm install @helixui/library
```
Then use components in your HTML:
```html
import '@helixui/library';
Get Started
Patient Portal
Accessible, themeable components for healthcare UIs.
Learn More
```
Or import individual components for optimal tree-shaking:
```js
import '@helixui/library/components/hx-button';
import '@helixui/library/components/hx-card';
```
---
## Why HELiX?
- **Healthcare accessibility built in** — Targeting WCAG 2.1 AA compliance ahead of the [HHS Section 504 mandate (May 2026)](https://www.hhs.gov/civil-rights/for-providers/compliance-enforcement/digital-accessibility/). Every component is keyboard-navigable, screen reader compatible, and tested with axe-core. Accessibility audits are ongoing as we work toward full AA conformance across all 73 components.
- **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 lock-in, no adapter libraries.
- **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, 73 components, 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 **73 production components** spanning the full spectrum of UI needs:
| 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-sidebar`, `hx-menu` |
| **Layout** | `hx-grid`, `hx-container`, `hx-divider`, `hx-header`, `hx-stack` |
| **Overlays** | `hx-dialog`, `hx-drawer`, `hx-tooltip`, `hx-popover`, `hx-dropdown` |
[Browse all components in Storybook →](https://helix.bookedsolid.tech/storybook/)
---
## Documentation
Full documentation is available at **[helix.bookedsolid.tech](https://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:
```twig
{# node--article--teaser.html.twig #}
{{ node.label }}
{{ node.body.summary }}
```
See the [Drupal Integration Guide](https://helix.bookedsolid.tech/guides/drupal/) 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](https://nodejs.org/api/corepack.html): `corepack enable`)
- Git
### Setup
```bash
git clone https://github.com/bookedsolidtech/helix.git
cd helix
pnpm install
pnpm run dev # Start library + Storybook + docs
```
### Commands
```bash
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 + type-check (required before push)
```
---
## Tech Stack
| Layer | Technology |
| ---------- | ------------------------------------------------------------------- |
| Components | [Lit 3.x](https://lit.dev), 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](https://storybook.js.org) |
| Docs | [Astro Starlight](https://starlight.astro.build) |
| Monorepo | [Turborepo](https://turbo.build) + pnpm workspaces |
---
## Contributing
See [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines. All contributions must:
- Pass TypeScript strict mode (`pnpm run type-check`)
- Include tests with 80%+ coverage
- Meet WCAG 2.1 AA accessibility standards
- Include Storybook stories for all variants
---
## License
[MIT](LICENSE)
---
**[Documentation](https://helix.bookedsolid.tech)** · **[Storybook](https://helix.bookedsolid.tech/storybook/)** · **[NPM](https://www.npmjs.com/package/@helixui/library)** · **[Issues](https://github.com/bookedsolidtech/helix/issues)**
Built with care for healthcare.