@alfadocs/ui-kit
v0.12.0
Published
AlfaDocs shared design system — tokens, components, patterns, and translations for platform, booking, and alfascribe.
Readme
@alfadocs/ui-kit
The AlfaDocs design system — React components, tokens, and translations.
Pre-release. APIs may change between minor versions before 1.0.
Install
npm install @alfadocs/ui-kitRequires React 18+ and Node ≥ 22.6.
Source maps (optional)
The default @alfadocs/ui-kit tarball ships without .map files to keep
installs small (~680 KB tarball). Browsers only request source maps on
demand when devtools is open, so end-users don't pay this cost regardless.
If you need symbolicated stack traces (Sentry / Rollbar uploads, in-browser
debugging of kit internals), install the -debug sibling instead. Both
packages are runtime-identical and version-locked:
// package.json — alias-install so imports still resolve as @alfadocs/ui-kit
"@alfadocs/ui-kit": "npm:@alfadocs/ui-kit-debug@^0.1.8"Or as a separate dev-only dep if your error reporter accepts maps from a sibling package.
Troubleshooting
npm install fails with ETARGET No matching version found for @alfadocs/ui-kit@<x.y.z> — even though the version exists on npmjs.org
This almost always means your ~/.npmrc (or a project-level .npmrc) has a
stale @alfadocs:registry= line pointing somewhere other than
https://registry.npmjs.org/. @alfadocs/ui-kit is published exclusively
to public npmjs.org from 0.1.0 onwards; the @alfadocs scope on GitHub
Packages only contains legacy 0.0.x builds and is not maintained.
Earlier 0.1.x bumps inside the same checkout can mask this — npm reuses
the resolved tarball URL from package-lock.json and never re-consults the
scope mapping. The first fresh resolve (a new minor, a clean checkout, a
rm -rf node_modules) is when the dead end surfaces.
Fix. Open ~/.npmrc and remove any @alfadocs:registry=… line — or
set it to the npm default, which is redundant but harmless:
@alfadocs:registry=https://registry.npmjs.org/Then re-run npm install.
One-shot workaround (if you can't edit your .npmrc right now):
npm install --@alfadocs:registry=https://registry.npmjs.orgUsage
Tokens
Import the design tokens once at your app root so the CSS custom properties are available everywhere:
import '@alfadocs/ui-kit/tokens';Then apply a theme class on the root element:
<html class="theme-light">
<!-- or theme-dark, optionally combined with theme-accessible -->
</html>Components
Each component is also available as its own subpath import for narrower bundles:
import { Button } from '@alfadocs/ui-kit/button';
import { Card } from '@alfadocs/ui-kit/card';
export function Example() {
return (
<Card>
<Card.Body>
<Button intent="primary">Save</Button>
</Card.Body>
</Card>
);
}Or import everything from the root entry:
import { Button, Card } from '@alfadocs/ui-kit';i18n
The kit ships with react-i18next pre-configured and locale bundles
in dist/locales/:
import i18n from '@alfadocs/ui-kit/i18n';
import en from '@alfadocs/ui-kit/locales/en.json';
i18n.addResourceBundle('en', 'ui', en);Host integration
The kit's dismissable primitives — Dialog, Popover, DropdownMenu,
Tooltip, Select, ContextMenu, NavigationMenu, AlertDialog —
all build on Radix's @radix-ui/react-dismissable-layer, which attaches
a bubble-phase pointerdown listener on document to detect outside
clicks. Consuming applications must not register a capture-phase
document (or body) listener that calls event.stopPropagation() on
pointerdown / mousedown / click — capture-phase consumers run
BEFORE Radix's detector and starve it, leaving overlays stuck open.
// Will break every dismissable primitive in the kit
document.addEventListener('pointerdown', (e) => e.stopPropagation(), true);If a legacy script must intercept pointer events at document level
(jQuery plugins, Bootstrap modals, in-house global menu handlers, etc.):
- Scope the listener to a specific container instead of
document/body. - Drop the
useCapture: trueflag — bubble-phase listeners fire AFTER Radix and don't interfere. - Drop the
stopPropagation()call entirely if it isn't load-bearing.
Each dismissable component's Storybook page carries a WithHostInterference
story that reproduces the failure mode for diagnosis.
Peer dependencies
react, react-dom, react-i18next, i18next. Tailwind CSS is not
required to consume the kit — components ship pre-styled, and the
tokens stylesheet exposes CSS custom properties you can reference from
your own styles.
License
Business Source License 1.1 — production use is permitted; offering the Licensed Work, or a substantial portion of it, as a competing hosted, embedded, or rebranded design-system or component-library product is not. The Licensed Work converts to the Apache License 2.0 on the Change Date specified in the LICENSE.
For commercial licensing arrangements outside the BUSL grant, contact AlfaDocs GmbH.