@alfadocs/ui-kit

The AlfaDocs design system — React components, tokens, and translations.

Released. Breaking changes land in majors and are called out in CHANGELOG.md.

Install

npm install @alfadocs/ui-kit

Requires React 18+ and Node ≥ 22.6.

Source maps (optional)

The default @alfadocs/ui-kit tarball ships without .map files to keep installs small (4.6 MB tarball / 17.3 MB unpacked, against 9.5 MB / 36.8 MB for the debug build). 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.
// Pin the exact version you already have installed, not a range: maps from a
// different release point at lines that have moved.
"@alfadocs/ui-kit": "npm:@alfadocs/[email protected]"

Or as a separate dev-only dep if your error reporter accepts maps from a sibling package.

Never commit the alias — it rewrites the lockfile, so npm ci would pull the debug build into production images. See Storybook → "30. Debugging — Source Maps and the Debug Package" for the full guide.

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.org

Usage

Tokens

Import the design tokens once at your app root so the CSS custom properties are available everywhere:

import '@alfadocs/ui-kit/tokens';

This full stylesheet includes all four third-party bridges. For an app that uses only part of the kit, choose core and add the bridges its components need:

import '@alfadocs/ui-kit/styles/core.css';
import '@alfadocs/ui-kit/styles/ag-grid.css'; // DataTable

Anything else that renders one of these components needs the same bridge.

Choose either tokens or core plus the required bridges. Core keeps all tokens, themes, base rules, component utilities and kit font declarations. Date pickers and booking components need no bridge. Vendor JavaScript and optional peer dependencies are still installed or supplied as before. Load core first so it establishes the CSS layer order. If copying built stylesheets, keep them beside the fonts/ directory, as with tokens.css.

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: true flag — 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.