@hsb3/keel-ui

The shared React 19 component library — components in three tiers (ui / compose / layout), plus the CSS token layer they render against. Published ESM + .d.ts — no raw TypeScript entry, no build step required in the consumer.

What you get

Components you do not have to assemble. The ui tier is Radix primitives with the token layer applied; compose is the tier that saves real time — DataTable, Chat, CommandPalette, DataExplorer, Form, the tool-render family — each already wired rather than left as a pile of parts. Counts per tier live in the generated facts, so this file never restates them.

A theme layer that does not touch your markup. Components consume semantic tokens and are forbidden — by a validator, not a convention — from keying on the active theme. One data-theme attribute on <html> re-renders the whole surface across all four shipped themes. Pictured is the anchor pair — carbon and carbon-dark, one palette in light and dark; the other two are parked, not promoted (docs/site/themes.md has the full set).

| carbon | carbon-dark | |---|---| | | |

A gallery that renders every component's real knob matrix, not one happy-path default — apps/demo in this repo, which is also where the images on this page were captured from a running build. A pink border marks demo scaffolding; anything without one is this package rendering itself.

What it is not (yet)

• Not a public library. The scope is private, there is no hosted per-component reference site, and the gallery is a repo app rather than a published docs surface.
• Some status colours fail WCAG contrast on their own surfaces — a known palette decision the contrast gate has priced, not an oversight (KEEL-62).
• Visual regression is gated in one environment only. Every exhibit is byte-compared in CI, but the baselines live in the pinned Playwright container and can only be regenerated there (apps/demo/README.md); a run on your own machine reports drift that is the machine, not the change.
• carbon and carbon-dark are the anchor pair — one palette (IBM Carbon), light and dark modes, carbon-dark transcribed from the published @carbon/themes package rather than designed. newspaper and terminal are parked: shipped, scored, baselined, but not where further theme work goes. html.dark is a compatibility alias for [data-theme="carbon-dark"] and now carries the whole theme (docs/site/themes.md).
• The charting and editor components carry optional peers you must install yourself — see below. That is deliberate, and the reason they are absent from the root barrel.

Install

bun add @hsb3/keel-ui      # registry: npm.pkg.github.com

react and react-dom (^19) are peer dependencies. Everything else — Radix primitives, open-props, tailwind-merge — ships as a real dependency; you do not add them.

Charts and the editor are the exceptions, in two ways.

First, echarts / echarts-for-react (charts) and @codemirror/* + diff (the editor) are optional peer dependencies, so an app with no chart and no editor installs neither set. If you use ui/chart or compose/tool-chart, add both yourself:

bun add echarts echarts-for-react

and for compose/editor:

bun add @codemirror/state @codemirror/view @codemirror/language @codemirror/commands \
        @codemirror/search @codemirror/lang-markdown diff

Second, those components are subpath-only — they are deliberately not exported from the package root:

import { Chart } from "@hsb3/keel-ui/ui/chart";                    // ✅
import { ToolChart } from "@hsb3/keel-ui/compose/tool-chart";       // ✅
import { MarkdownEditor } from "@hsb3/keel-ui/compose/editor";      // ✅
import { Chart } from "@hsb3/keel-ui";                              // ❌ not exported

That is what makes the optional peer actually optional. A bundler resolves the chart's dynamic echarts-for-react import eagerly, so if the root barrel re-exported these components, every app importing anything from the package root would be required to have echarts installed — a chart-free app would fail its production build outright. Keeping them off the barrel also keeps echarts' types out of the root .d.ts. Two gates enforce it (check:components, check:pack), so it cannot regress.

Styles

Import the token layer once, at the top of your global stylesheet:

@import "tailwindcss";
@import "@hsb3/keel-ui/styles.css";   /* foundation → tokens → semantic → utilities */
@source "../node_modules/@hsb3/keel-ui/dist";

The @source line is not optional, and it fails silently

Tailwind v4 only emits utility classes it finds in scanned source. keel-ui's components are pre-built JS in node_modules, which Tailwind does not scan by default, so the @source directive is what makes their classes exist at all.

It must be a relative path to the dist directory. The bare package-specifier form —

@source "@hsb3/keel-ui";        /* WRONG — generates zero utilities and still exits 0 */

— produces an empty utility set, no warning, no non-zero exit. The failure only shows up as unstyled components in the browser. Use the relative form:

@source "../node_modules/@hsb3/keel-ui/dist";

Adjust the ../ depth to your stylesheet's location (from app/globals.css in a Next app, ../node_modules/... is correct). If your components render with layout and colors from the token layer but no spacing/flex/text utilities, this line is why.

Brand overrides go after the keel-ui import: both land on :root, so source order decides.

Importing components

import { Button, DataTable } from "@hsb3/keel-ui";          // root barrel
import { Card } from "@hsb3/keel-ui/ui/card";               // per-component subpath
import { Shell } from "@hsb3/keel-ui/layout/shell";

Every component in components.manifest.json is reachable from the root barrel; the tiered subpaths (./ui/*, ./compose/*, ./layout/*) exist for narrower imports. For how many there are of each tier, see the generated facts.

Gates

The package's contract is two committed manifests, both machine-checked (these run in CI, and a change that breaks either fails the build):

| command | what it proves | |---|---| | bun run --filter @hsb3/keel-ui check:tokens | every custom property in tokens.manifest.json is defined in the built CSS — a token rename is legal only by editing the manifest in the same PR. The manifest's fallback-only tier is held to the inverse rule: no base or anchor scope declares it, and every call site carries a fallback | | bun run --filter @hsb3/keel-ui check:tokens:selftest | the tokens gate's own proof-of-failure harness: the fallback-only tier's pass condition is an ABSENCE, so the fixtures are what prove the rules can still fail | | bun run --filter @hsb3/keel-ui check:components | components.manifest.json agrees with the build in both directions: every entry resolves and re-exports from the root barrel, and every built component has an entry. The three subpath-only modules (ui/chart, compose/tool-chart, compose/editor) invert the first half — they must be ABSENT from the barrel | | bun run --filter @hsb3/keel-ui check:pack | packs the tarball and consumes it from a throwaway dir — built ESM + types only, subpaths resolve, no forbidden SDK in the dependency set, no optional-peer library (charting, @codemirror/*, diff) among the shipped dependencies, and none reachable from the root barrel's import closure (dist/index.js and dist/index.d.ts) while ui/chart, compose/tool-chart + compose/editor still import by subpath | | bun run --filter @hsb3/keel-ui test | mount coverage for every component |

Editing the theme layer

src/styles/theme/ is foundation → tokens → semantic → utilities, imported in that order by index.css. foundation.css pulls the Open Props non-color primitives (sizes, shadows, easings, borders); its @imports sit at the top of the file because CSS requires @import to precede every style rule. Components never reference --carbon-* or raw Open Props props directly — they consume the short tokens (--bg, --fg-dim, --accent) or the semantic tokens.

Roadmap

Tracked on the KEEL board, not here. Queued for this package: consolidating the chat families into one shape with form factors (KEEL-64), the --color-primary token the border-primary utility already assumes (KEEL-75), a check:design rule for utilities referencing undefined tokens (KEEL-92), and the contrast work named above (KEEL-62).