@alfadocs/ui-kit-debug

v0.13.0

Published

3 hours ago

AlfaDocs shared design system — tokens, components, patterns, and translations for platform, booking, and alfascribe. (debug build — identical runtime to @alfadocs/ui-kit, ships source maps for symbolication).

0High
0Medium
0Low

lockymic-alfa

@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-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 (~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.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';

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.

Published

Vulnerabilities

Links

Maintainers

Keywords

Readme