{"id":49894930,"url":"https://github.com/codejupiter/helix-ui","last_synced_at":"2026-05-15T23:01:48.088Z","repository":{"id":357947421,"uuid":"1227126592","full_name":"codejupiter/helix-ui","owner":"codejupiter","description":"Accessible React component primitives built from scratch with keyboard navigation, theming, and interaction tests.","archived":false,"fork":false,"pushed_at":"2026-05-14T23:34:39.000Z","size":106,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-05-15T01:32:58.489Z","etag":null,"topics":["accessibility","component-library","design-system","react","testing","typescript"],"latest_commit_sha":null,"homepage":null,"language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/codejupiter.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-05-02T08:38:59.000Z","updated_at":"2026-05-14T23:34:43.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/codejupiter/helix-ui","commit_stats":null,"previous_names":["codejupiter/helix-ui"],"tags_count":null,"template":false,"template_full_name":null,"purl":"pkg:github/codejupiter/helix-ui","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/codejupiter%2Fhelix-ui","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/codejupiter%2Fhelix-ui/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/codejupiter%2Fhelix-ui/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/codejupiter%2Fhelix-ui/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/codejupiter","download_url":"https://codeload.github.com/codejupiter/helix-ui/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/codejupiter%2Fhelix-ui/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":33082699,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-15T20:25:35.270Z","status":"ssl_error","status_checked_at":"2026-05-15T20:25:34.732Z","response_time":103,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.5:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["accessibility","component-library","design-system","react","testing","typescript"],"created_at":"2026-05-15T23:01:07.871Z","updated_at":"2026-05-15T23:01:48.082Z","avatar_url":"https://github.com/codejupiter.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Helix UI\n\nCustom-built, accessible React component primitives.\n\nA personal project exploring what it takes to build a serious component library from scratch — without leaning on Radix, Headless UI, or other headless frameworks. Every primitive is hand-rolled with care for accessibility, keyboard navigation, and bundle size.\n\n```bash\nnpm install @codejupiter/helix-ui\n```\n\n```tsx\nimport '@codejupiter/helix-ui/styles.css';\nimport { Button, Dialog, ToastProvider } from '@codejupiter/helix-ui';\n\nfunction Example() {\n  return (\n    \u003cToastProvider\u003e\n      \u003cDialog\u003e\n        \u003cDialog.Trigger\u003e\u003cButton\u003eConfirm\u003c/Button\u003e\u003c/Dialog.Trigger\u003e\n        \u003cDialog.Content\u003e\n          \u003cDialog.Title\u003eAre you sure?\u003c/Dialog.Title\u003e\n          \u003cDialog.Description\u003eThis cannot be undone.\u003c/Dialog.Description\u003e\n          \u003cDialog.Close\u003e\u003cButton variant=\"ghost\"\u003eCancel\u003c/Button\u003e\u003c/Dialog.Close\u003e\n          \u003cButton variant=\"danger\"\u003eDelete\u003c/Button\u003e\n        \u003c/Dialog.Content\u003e\n      \u003c/Dialog\u003e\n    \u003c/ToastProvider\u003e\n  );\n}\n```\n\n## Status\n\n**All 16 planned primitives shipped.** 112 tests passing.\n\n## Documentation\n\n- [API reference](packages/helix-ui/docs/API.md) — install, exports, compound components, theming, package shape, and bundle budgets.\n- [Accessibility contract](packages/helix-ui/docs/ACCESSIBILITY.md) — primitive behavior, consumer responsibilities, testing strategy, and release checklist.\n- [Release checklist](packages/helix-ui/docs/RELEASE_CHECKLIST.md) — validation gates, package contents, npm publishing, and next release candidates.\n- [Helix UI v0.1.0 release notes](packages/helix-ui/docs/releases/helix-ui-v0.1.0.md) — release summary, engineering highlights, evidence, and known limits.\n- [Changelog](packages/helix-ui/CHANGELOG.md) — package release history.\n- [Security policy](SECURITY.md) — supported version, reporting path, and security posture.\n\n| Primitive    | Notes                                                         |\n| ------------ | ------------------------------------------------------------- |\n| Button       | 4 variants, 3 sizes, loading state, icon slots                |\n| Input        | Invalid state via `aria-invalid`                              |\n| Checkbox     | Visually-hidden native input + styled overlay                 |\n| Switch       | `role=\"switch\"` for assistive tech                            |\n| RadioGroup   | Context-driven group + items, mutual exclusivity              |\n| Slider       | Keyboard (arrows, Home/End, PageUp/Down) + pointer drag       |\n| Select       | Custom combobox + listbox with full keyboard navigation       |\n| Avatar       | Image with deterministic initials fallback                    |\n| Progress     | Determinate + indeterminate states                            |\n| Tooltip      | Hover/focus triggered with delay                              |\n| Popover      | Click-triggered with outside-click and Escape dismissal       |\n| Dialog       | Focus trap, scroll lock, return focus, full ARIA              |\n| Toast        | Stacking notifications with auto-dismiss                      |\n| Tabs         | ARIA tabs pattern with roving tabindex                        |\n| Accordion    | Single + multi-expand modes                                   |\n| DropdownMenu | Keyboard-navigable menu with arrow keys                       |\n\n## Design principles\n\n- **Custom-built, no headless dependencies.** Every interactive primitive is implemented from scratch — no Radix, no Headless UI. Accessibility isn't outsourced; it's owned.\n- **Native semantics first.** Where the browser has the right element (`\u003cbutton\u003e`, `\u003cinput type=\"checkbox\"\u003e`), we use it. The styled-overlay pattern keeps screen readers, keyboard users, and form submission happy.\n- **Tokens over hardcoded values.** All visual properties reference CSS custom properties under the `--helix-*` namespace. Theming is a single-file change.\n- **Tree-shakeable.** Each component is a separate file with no side effects beyond CSS. Import what you use.\n- **Tested.** 112 tests across 16 components — unit + interaction via Vitest + Testing Library.\n\n## Bundle size\n\nReal measurements from the latest build:\n\n| Output      | Raw     | Gzipped |\n| ----------- | ------- | ------- |\n| ESM bundle  | 38 KB   | 8.6 KB  |\n| CSS         | 26 KB   | 4.2 KB  |\n\nZero runtime dependencies. React 18+ peer dependency only.\n\n## Theming\n\nTwo themes ship by default:\n\n```tsx\n\u003cdiv data-helix-theme=\"dark\"\u003e  {/* default */}\n  \u003cButton\u003eDark\u003c/Button\u003e\n\u003c/div\u003e\n\n\u003cdiv data-helix-theme=\"light\"\u003e\n  \u003cButton\u003eLight\u003c/Button\u003e\n\u003c/div\u003e\n```\n\nOverride any token by setting CSS custom properties:\n\n```css\n:root {\n  --helix-accent: #f97316;\n  --helix-radius-md: 0.125rem;\n}\n```\n\n## Accessibility\n\nEvery primitive is built against WCAG 2.1 AA standards.\n\n- All interactive elements are keyboard-accessible\n- Focus states use visible 3px outline rings (not just color)\n- Labels are properly associated via `htmlFor` / `id`\n- ARIA attributes are applied where native semantics aren't sufficient\n- `prefers-reduced-motion` is honored (transitions become instant)\n- Dialog implements full focus trap + scroll lock + return focus\n- Composite controls implement keyboard navigation patterns from the WAI-ARIA Authoring Practices\n\n## Architecture highlights\n\nA few engineering details worth noting:\n\n- **Compound components for complex primitives.** Dialog, Tabs, Accordion, Select, and DropdownMenu use `Object.assign` exports (e.g. `Tabs.List`, `Tabs.Trigger`, `Tabs.Content`) to keep their APIs cohesive while remaining tree-shakeable.\n- **Context-driven shared state.** RadioGroup, Tabs, Accordion, Select, and Dialog use React Context to share state between root and children without prop drilling. Each context throws a helpful error if used outside its parent.\n- **Custom focus trap implementation.** `useFocusTrap` walks the focusable-element selector list, manages Tab / Shift+Tab cycling, and restores focus on cleanup. Used by Dialog.\n- **Roving tabindex for composite controls.** Tabs uses the proper ARIA roving tabindex pattern: only the active tab is in the tab order; arrow keys move focus and activate.\n- **`aria-activedescendant` for Select.** Select uses the listbox-with-active-descendant pattern so keyboard navigation doesn't move DOM focus while still announcing the highlighted option to screen readers.\n\n## Development\n\n```bash\n# Install\ncd packages/helix-ui\nnpm install\n\n# Run tests in watch mode\nnpm run test:watch\n\n# Build the library\nnpm run build\n\n# Typecheck\nnpm run typecheck\n\n# Verify bundle budgets and package contents\nnpm run size\nnpm run pack:check\n```\n\n## Quality gates\n\nGitHub Actions runs production audit, lint, typecheck, the full Vitest component suite, package build, bundle-size budgets, and `npm pack --dry-run`. This keeps the library honest as a publishable package, not just a local component demo.\n\nBefore publishing or creating a GitHub release, run the [release checklist](packages/helix-ui/docs/RELEASE_CHECKLIST.md).\n\n## License\n\nMIT — Zoriah Cocio\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcodejupiter%2Fhelix-ui","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fcodejupiter%2Fhelix-ui","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcodejupiter%2Fhelix-ui/lists"}