@njoythehive/ui

The HIVE design system: components, tokens, accessibility composables and the application shell contract.

Ships raw source — .vue and .ts, compiled by the consuming application's Vite instance. There is no build step and there deliberately is not one: the components import icons as ~icons/lucide/*, which are virtual modules created by unplugin-icons in the consumer's build. Pre-bundling would resolve them at the wrong time, and the repository's .npmrc sets ignore-scripts=true, so no prepare hook would fire anyway.

Consuming it

npm install @njoythehive/ui @iconify-json/lucide unplugin-icons

The package ships raw source — .vue and .ts, compiled by your Vite. There is no build step and deliberately never one: the components import icons as ~icons/lucide/*, which are virtual modules created by unplugin-icons in your build.

So a host has to wire four things, all of them peer dependencies, which is the machine-readable form of this list:

1. the @ui alias, in Vite and in tsconfig paths — every import inside the package uses it;
2. unplugin-icons, with a hive collection pointed at the package's own custom SVGs, and @iconify-json/lucide installed in the application;
3. the stylesheet and Tailwind v4, with source(none) and an explicit @source reaching into node_modules;
4. vue-router — HAppFooter, HBreadcrumb, HMenuItem, HNavItem and HSubNav render <RouterLink>.

docs/installation.md is the full contract, with copy-paste configs, the frame package, the four ways this fails silently, and a troubleshooting table. Read it before wiring a new application — three of the four failures produce either no error or an error naming the wrong thing.

Verifying the wiring

Build, then grep the output CSS for a class that exists only in package source:

grep -c "auto-cols-fr" dist/assets/*.css   # HAppShell.vue only — a zero means @source is not reaching the package

Make it a CI step. It is the only cheap proof the stylesheet wiring is still correct, and the failure it catches is silent.

Working on the package

npm install
npm run dev        # the showcase, at http://localhost:5173/_design/

The showcase is in this repository deliberately. It is the package's usage documentation and the only place its browser behaviour can be tested: jsdom computes no layout, so HDataGrid's virtualiser renders nothing, HScrollArea's overflow shadow measures zero and axe's color-contrast rule silently passes. Splitting it out would mean this package could no longer prove its own claims before publishing.

| | | |---|---| | npm run lint · npm run typecheck · npm test | the jsdom suite, beside the components | | npm run e2e | keyboard, contrast and smoke, in a real browser | | npm run e2e:visual | the showcase baselines. macOS only — see tests/e2e/README.md | | npm run build | builds the showcase for deployment. The package itself is never built | | npm run icons:sync | regenerate typed icon names after dropping an SVG into src/icons/custom | | npm run showcase:api | regenerate the props/events/slots tables from the component sources |

PORT=5180 npm run e2e moves the dev server, for running suites side by side.

Run lint, typecheck, test and e2e before publishing. Anything touching layout, focus or motion also wants npm run e2e:visual — those baselines are the only thing that can see it.

Publishing

private: true is deliberate: it is what makes npm publish refuse. Removing it without setting publishConfig.registry would let an internal design system go to the public npm registry on a typo.

To publish, decide the registry first, then set both together. Note the scope has to belong to you on whichever registry you choose — @hive on npmjs, or an org of the same name on GitHub Packages.

files in package.json is the allowlist: src, docs and this README, with the .test.ts files excluded. Check it with npm pack --dry-run before the first publish — 159 files, ~200 kB.

Repository layout

src/          the package. Raw .vue and .ts, no build step
docs/         the package's own documentation, travelling with it
showcase/     /_design — the usage documentation and the browser test surface
tests/e2e/    keyboard, contrast, visual, smoke
scripts/      the two generators: icon names, showcase API tables

Import style

• @njoythehive/ui — the barrel: types, enums, composables, the shell contract. What application code imports.
• @ui/components/core/HButton.vue — components, imported by path. There is no component barrel on purpose: one over sixty single-file components pulls every one of them into the dev module graph on first import.

What is inside

| Path | | |---|---| | src/components/{core,data,domain,form,nav,overlay}/ | The components | | src/composables/ | Focus trap, dismissal, roving tabindex, field and choice contracts, anchoring, scroll lock | | src/shell/ | The application shell contract — types and provide/inject only. No data, no fetching | | src/css/ | Tokens, semantic aliases, base layer, utilities | | src/icons/ | HIcon, the generated name unions, and drop-in custom SVGs | | src/types.ts, src/enums/, src/utils.ts, src/styles/control.ts | The shared vocabulary | | docs/ | The package's own documentation, travelling with it: installation.md, rules.md, components.md with a file per group under components/, conventions.md, and the three subsystems |

The consuming application's rules — module boundaries, repositories, where a control sits on a screen — are its own, in docs/rules.md there, alongside the programme's plan of record in docs/README.md.