@kiberon-labs/ui
v1.2.1
Published
The Kiberon Labs design system: 46 shadcn-style React components (Radix + Tailwind) themed with the Kiberon design tokens. Dark mode is the brand-canonical appearance.
Readme
Kiberon Labs UI
The Kiberon Labs design system: 46 shadcn-style React components (Radix + Tailwind) themed with the Kiberon design tokens. Dark mode is the brand-canonical appearance.
Storybook: https://storybook.kiberonlabs.com/
The brand and design language — voice, color, the crystal palette, type, spacing, and iconography — are documented in GUIDELINES.md and browsable in Storybook under Foundations.
Installation
This package is published to the Kiberon Labs GitHub Packages registry (not the public npm registry). Point the @kiberon-labs scope at it and authenticate with a GitHub token that has read:packages for the Kiberon-Labs org. Add to your project's .npmrc:
@kiberon-labs:registry=https://npm.pkg.github.com
//npm.pkg.github.com/:_authToken=${GITHUB_TOKEN}Then install (with GITHUB_TOKEN set in your environment):
pnpm add @kiberon-labs/ui lucide-reactThe package is framework- and Tailwind-agnostic: components ship plain CSS. Import the stylesheet once (app root / root layout):
import "@kiberon-labs/ui/css/index.css";The design system is dark-only: add the dark class to <html> (or any ancestor).
The theme is set in Geist; load it in your app (e.g. @fontsource/geist).
Customizing styles
Two stable surfaces, no build tooling required:
- Design tokens — override the CSS custom properties globally or per-scope. They ship in four layers:
css/theme.css(semantic color/shadow/radius —--primary,--radius,--shadow-floating-small, …),css/brand.css(crystal palette--kl-*+ signature gradients),css/typography.css(--font-sans,--text-*, tracking), andcss/spacing.css(--space-*,--radius-*). - Component classes — every component uses stable prefixed classes (
kl-button,kl-dialog__content,kl-badge--success); target them in your own CSS, or passclassName(merged last) on any component.
To ship only the styles you use, import css/theme.css + css/brand.css + css/typography.css + css/spacing.css + css/base.css + individual files from css/components/ instead of css/index.css.
Usage
Everything is exported from the package root:
import { Button, Dialog, DialogContent, useToast, cn } from "@kiberon-labs/ui";Brand assets
The Kiberon Labs logo, crystal mark, favicon, and palette ship in-repo under
assets/ and are published with the package. Import them by path:
import logo from "@kiberon-labs/ui/assets/logo-dark-full.png";They are also browsable in Storybook under Foundations → Brand.
Agent skill
The package ships an agent skill that teaches AI coding agents (Claude Code, etc.) how to install, theme, and compose the components — including the full per-component API reference.
To install it in a consuming project:
# from a project that has @kiberon-labs/ui installed
cp -r node_modules/@kiberon-labs/ui/skills/kiberon-ui .claude/skills/kiberon-uior copy skills/kiberon-ui/ from this repo into ~/.claude/skills/ for global availability.
Development
pnpm install
pnpm storybook # component workbench at :6006
pnpm test # vitest
pnpm build # tsc + css assets -> dist/
pnpm build:storybook # static storybookVisual regression tests
Every Storybook story is screenshot-tested in dark mode — the design system's only theme (Playwright + Chromium; one-time setup: npx playwright install chromium):
pnpm test:visual # build storybook + compare against baselines
pnpm test:visual:update # rebaseline after an INTENTIONAL visual changeBaselines live in tests/visual/__screenshots__/<platform>/ and are committed. When a change alters rendering, the test fails and Playwright writes *-expected.png / *-actual.png / *-diff.png into test-results/; open the HTML report (npx playwright show-report) to view the before/after/diff side by side. Review the diff — if the change is intended, rebaseline and commit the updated PNGs with the code change so the visual delta is part of the PR.
Notes: external network requests are blocked during capture (image-bearing stories render their fallback states) and the calendar runs on a fixed clock, so runs are deterministic. Baselines are platform-specific (win32, linux, …) — running the suite on a new platform generates that platform's baselines on first test:visual:update.
Releases are managed with changesets (pnpm changeset), published from CI on master.
Notes
This is an ESM-only package.
