@qeetrix/ui

v2.0.0

Published

a month ago

Qeetrix UI — the Qeet Group React component library (shadcn + Base UI, Tailwind v4).

Downloads

106

0High
0Medium
0Low

qeetgroup

msboffl

🎨 Qeetrix

The Qeet Group design system — one package, every surface

Premium · Accessible · Token-driven · Built on Base UI + Tailwind v4

🚀 Install · 🏗 Architecture · 🧩 Components · 🎨 Tokens · 📖 Storybook · 🚢 Release

Status — 1.0.3, standalone. Tokens + brand ship inside @qeetrix/ui. Already a live dependency of Qeet ID (console · login · website) and qeet-docs.

✨ Why Qeetrix

| | | |:--|:--| | 📦 One design-system package | @qeetrix/ui ships components + design tokens + brand; React 19 and Tailwind 4 remain explicit peers | | ♿ Accessible by construction | Built on Base UI (WAI-ARIA APG behavior) + axe-tested stories; visible focus, reduced-motion, AA contrast | | 🎨 Token-driven theming | W3C DTCG JSON → Style Dictionary → CSS + JSON; OKLCH colour, light/dark via the .dark class | | 💎 Premium by default | Layered elevation, refined focus rings, tasteful hover-lift micro-interactions, self-hosted Cal Sans | | 🌗 First-class dark mode | Every component themed through semantic tokens — no hard-coded greys | | 🏢 Enterprise breadth | Data tables, command palette, rich-text editor, charts, sidebar shells, date/time pickers, and more | | 🧱 Consistent foundation | Shared cva + cn() conventions, data-slot hooks, tree-shakeable named exports | | 🔒 Quality-gated | Typecheck, Biome, Vitest + axe, real-browser tests, coverage, WCAG contrast, architecture, API, manifest, bundle and performance gates — all on every PR |

🏗 Architecture

A standalone Bun package. Tokens are the source of truth; everything downstream is generated or composed from them. Components live in src/components/<category>/, but the published import paths stay flat — dist carries a generated façade, so a component can move category without breaking a single consumer.

flowchart TB
    subgraph pkg["@qeetrix/ui"]
        direction LR
        tokens["Design tokens<br/>W3C DTCG JSON · OKLCH<br/>src/tokens/"]
        sd["Style Dictionary<br/>scripts/build/tokens.mjs<br/>→ semantic + raw --qx-* CSS + JSON"]
        comps["145 UI modules · 10 categories<br/>custom + Base UI<br/>src/components/&lt;category&gt;/"]
        brand["Brand<br/>QeetLogo + 10 icons<br/>src/brand/"]
        tokens --> sd --> comps
        brand --> comps
    end

    consumers["Qeet ID — console · login · website<br/>qeet-docs · future Qeet products"]
    workshop["qeetrix-story — Storybook 10 workshop (sibling repo)"]

    comps --> consumers
    comps --> workshop

Build pipeline: clean → tokens (Style Dictionary) → manifest → tsc → tsc-alias → subpath-shims → postbuild (CSS entry, fonts, tokens, manifest).

Source layout

src/
├── tokens/            DTCG token source — primitive · semantic · component · theme overlays
├── components/        10 category folders, each with index.ts + __tests__/
│   ├── actions/ inputs/ selection/ pickers/ navigation/
│   └── feedback/ surfaces/ data-display/ layout/ utility/
├── contracts/         component contract: types + closed vocabularies + the layer table
├── manifests/         the manifest's type, and the declarations it is generated from
├── foundations/       typed token values — GENERATED from src/tokens/
├── providers/         theme · density · direction
├── blocks/ brand/ hooks/ lib/ fonts/
├── styles/            index.css (entry) + generated token CSS/JSON
└── __tests__/         global harness: setup, a11y smoke, client boundaries, API lock, governance
scripts/
├── build/             tokens · manifest · subpath-shims · postbuild · logos
├── check/             architecture · component-contract · exports · a11y-coverage · token-usage · contrast · package
└── lib/               shared analysis: layer graph, contract validator, TS literal reader
docs/
├── architecture/      overview · component-layers · dependency-rules
├── standards/         api-guidelines · component-manifest
└── governance/        component-status · deprecations · versioning

Layers flow one way — tokens → foundations → runtime/primitives → components → blocks — and dependencies are deny by default. The allow-list lives in src/contracts/layers.ts; bun run check:architecture enforces it against the real module graph. See docs/architecture/.

Import paths

Every published path is enumerated in the exports map — there are no wildcards over hooks/, lib/, providers/ or blocks/, so a new module in one of those folders is internal until someone adds it to the map. bun run check:package proves each path below resolves in the packed tarball, and that everything under Not published does not.

Not published — these resolve to nothing, deliberately: @qeetrix/ui/components/<category>/<slug> (the category a component lives in is an implementation detail; use the flat path), @qeetrix/ui/components/index (use the barrel), @qeetrix/ui/hooks/use-controllable-state and anything under primitives/, contracts/, manifests/, runtime/ or foundations/.

🚀 Install & use

bun add @qeetrix/ui react react-dom tailwindcss
# peers: React/React DOM >=19, Tailwind CSS >=4

In your Tailwind v4 global stylesheet:

@import "@qeetrix/ui/styles.css";              /* tokens + fonts + base layer */
@source "../node_modules/@qeetrix/ui/dist/**/*.js";   /* let Tailwind see component classes */

Then wrap the app and compose:

import { ThemeProvider, Button, Card, CardContent } from "@qeetrix/ui";
import { QeetLogo } from "@qeetrix/ui/brand";

export function App() {
  return (
    <ThemeProvider defaultTheme="system">
      <Card>
        <CardContent className="flex items-center gap-3">
          <QeetLogo size={28} />
          <Button>Authenticate with Qeet</Button>
        </CardContent>
      </Card>
    </ThemeProvider>
  );
}

Light/dark is driven by the .dark class (managed by ThemeProvider). Its keyboard shortcut is disabled by default; enableKeyboardShortcut opts into Ctrl/Meta+Shift+D. Need raw values? @qeetrix/ui/tokens.css (the --qx-* ramp) and @qeetrix/ui/tokens.json.

Import surfaces: see the table in Architecture. The pre-1.0 @qeetrix/ui/components/ui/<slug> path still resolves.

🧩 What's inside

145 React UI modules across ten categories; every one has a Vitest/axe test in its category's __tests__/, and stories cover the public catalog.

Overlays — Dialog · Sheet · Drawer · Popover · DropdownMenu · ContextMenu · Menubar · HoverCard · Tooltip · CommandPalette · NavigationMenu
Inputs & controls — Button · Input · Textarea · Select · Combobox · MultiSelect · Autocomplete · Checkbox · Radio · Switch · Toggle · Slider · AngleSlider · OTPInput · NumberField · Field / Form · Chip · SegmentedControl · ColorPicker · Date / Time / Timezone pickers
Data & navigation — Table · DataTable · Tabs · Breadcrumb · Pagination · Sidebar · Tree · Timeline · Accordion · Collapsible · Listbox · TableOfContents · Carousel · Charts
Enterprise operations — AccessReview · AuditLog / AuditEvent · SecurityItem · accessible ChartDataTable fallbacks · responsive ScheduleCalendar agenda
Feedback & surfaces — Card · Alert · Banner · Notification · Toast · Stat · Badge · StatusPill · Skeleton · Progress · Meter · EmptyState · Feed · Spoiler · Marquee
Content & typography — Typography / Prose · Blockquote · Highlight · Kbd · CodeBlock · JSONTree · RichTextEditor · NumberFormatter · RollingNumber
Brand — QeetLogo (theme-adaptive) + 10 custom Qeet icons, at @qeetrix/ui/brand
Blocks — auth, dashboard shell, settings layout, onboarding wizard, pricing table

🎨 Design tokens

The single source of truth lives in src/tokens/ as W3C DTCG JSON, in four layers — primitive (values) → semantic (meaning) → component (per-component mapping, including the shadcn bridge) → component styles. Style Dictionary compiles them to:

@qeetrix/ui/styles.css — the full entry (:root / .dark, @theme mappings, fonts, base layer)
@qeetrix/ui/qeetrix.css — the semantic + component layers, as --qx-* vars
@qeetrix/ui/tokens.css — everything including the primitive ramps · @qeetrix/ui/tokens.json — resolved per theme
src/foundations/token-values.ts — the same values, typed, re-exported from @qeetrix/ui

The primitive layer is not published to the stylesheet components render against, so a component physically cannot resolve a palette value — the ownership rule is a fact, not a convention. Full detail: docs/standards/tokens.md.

Colour is authored in OKLCH; elevation uses a layered shadow ladder (rest · hover · popover · modal). Every semantic text/surface pair is held to WCAG-AA contrast by a build gate (part of bun run verify).

Re-branding is one alias hop: re-point the nine color.brand.* aliases and every semantic token, component token and component follows. Retuning corners is one variable (--radius).

🛠 Develop

Toolchain: Node ≥ 20 · Bun ≥ 1.3.

bun install
bun run dev              # regenerate tokens, then tsc --watch
bun run build            # tokens → manifest → tsc → aliases → subpath shims → assets
bun run test             # Vitest + vitest-axe
bun run verify           # typecheck · lint · test · architecture · API lock · a11y · tokens · contrast
bun run verify:package   # build, pack, and compile real consumers against the tarball
bun run check:generated  # the tracked generated artifacts match their generators
bun run check:release    # the publication preflight (release gate, not a build gate)
bun run format           # biome check --write

verify:package fails closed. The Vite + Tailwind consumer passes are hermetic; the Next.js RSC pass needs qeetrix-docs installed next to this repo, and skipping it has to be asked for with QEETRIX_SKIP_NEXT_CONSUMER=1 — a run that could not verify server components says so loudly instead of exiting green.

verify is the gate to run before pushing. Its eight structural checks are what keep the architecture honest:

| Check | Enforces | |:--|:--| | check:architecture | category map ↔ filesystem, complete barrels, no barrel imports, kebab-case, client directives, layer boundaries | | check:contract | every component satisfies the component contract — valid status, capabilities, states, ARIA pattern, deprecation record | | check:exports | the published surface of all 21 entry points matches src/__tests__/public-api.json down to each export's kind and each declared prop's optionality, type, generics and base types, and is intentional — no unreachable component, no leaking @barrel-exclude, no duplicate export | | check:a11y | every component has an axe test (currently 145/145) | | check:tokens | the token graph — layer direction, references, cycles, types, theme parity, deprecations | | check:token-usage | no raw colours, z-indexes, shadows or bare lengths in component source | | check:contrast | WCAG-AA on every semantic text/surface pair, both themes | | check:performance | the scale baseline in src/__tests__/performance/baseline.json — budgets may only shrink |

Adding a component? Create src/components/<category>/<slug>.tsx (cva + cn(), data-slot, Base UI for anything interactive), list the slug in scripts/config/category-map.json, export it from the category index.ts, add __tests__/<slug>.test.tsx, declare its status + ARIA pattern in src/manifests/component-registry.ts, then run bun run verify — it will tell you exactly what is missing. Re-snapshot the API with bun run check:exports -- --update and record a changeset. See CONTRIBUTING.md and docs/standards/component-api.md.

🚢 Release

Versioning + publishing run on Changesets and are documented in docs/governance/release.md, behind a gate:

bun run changeset          # record a change + bump level
bun run version-packages   # apply bumps + changelog (usually CI)
bun run check:release      # the publication preflight — posture, lockfile, pinned toolchain
bun run release            # check:release → verify → verify:package → publish

bun run release cannot publish something the quality gate rejects, and .github/workflows/release.yml is the only place it is meant to run: merging to main opens the Version Packages PR, and merging that publishes — after check:release, verify and verify:package all pass in the protected npm-publish environment.

Publication is currently blocked, on purpose. bun run check:release fails while license: "UNLICENSED" sits next to public publication settings, and while bun.lock is uncommitted. Both are decisions, not defects — see docs/governance/release.md for what a human still has to do (licence posture, registry, npm-publish environment reviewers, branch protection).

Supported development environments: macOS and Linux. The scripts use Node's filesystem and path APIs rather than a POSIX shell, but only Linux is exercised in CI, so Windows is unverified rather than supported.

📚 Documentation · 🤝 Contributing · 📄 License

Part of the Qeet Group workspace. Licensed UNLICENSED (private to Qeet Group) pending the public-release decision — which is why bun run check:release refuses to publish. See docs/governance/release.md.