@rubriclab/rubrot-ui

Rubric's design system and frontend platform — dark, dense, Linear-grade tokens and primitives shared by the fleet (rubrot, metal, vault, radar). Ships as TS source; consumers transpile it.

Adopting in an app

1. bun add @rubriclab/rubrot-ui (workspace apps: "@rubriclab/rubrot-ui": "workspace:*").

2. next.config.ts: transpilePackages: ["@rubriclab/rubrot-ui"].

3. app/globals.css:

   @import "tailwindcss";
   @import "@rubriclab/rubrot-ui/theme.css";
   @source "../node_modules/@rubriclab/rubrot-ui/src";
   /* optional brand re-tint: */
   @theme {
     --color-brand: #5e6ad2;
     --color-brand-fg: #ffffff;
   }

4. PWA (optional, all pieces independent):

   • app/manifest.ts → export default () => defineManifest({ name: "Vault" })
   • app/sw.js/route.ts → export const GET = createServiceWorkerRoute({ version: "shell-v1", offlinePath: "/offline.html" }) (from @rubriclab/rubrot-ui/pwa/server)
   • app/api/pwa/version/route.ts → export const dynamic = "force-dynamic"; export const GET = createPwaVersionRoute({ killEnvVar: "VAULT_PWA_KILL" })
   • layout: <PwaProvider /> (+ <InstallPrompt appName="Vault" /> if wanted)

5. SSE routes: sseResponse + envelope from @rubriclab/rubrot-ui/live/server; the client end is useEventStream + StreamStatusChip.

6. Harness v2 UI (optional): install @rubriclab/rubrot-harness, import the components from @rubriclab/rubrot-ui/harness, and import their protocol types from @rubriclab/rubrot-harness/protocol.

Rules the package holds itself to: semantic tokens only (its own ui-tokens test rejects raw Tailwind palette classes), files ≤250 lines, one meaning per color, focus-visible rings on every interactive element, motion via the ui-* keyframes with a global reduced-motion kill switch.

Components

• Atoms — avatar badge (+BadgeTone) button card empty-state notice banner (bordered callout) skeleton (+LogSkeleton) skeletons (route-shell kit) spinner (+FeedLoader) status-dot ping-dot live-pulse vault-badge (+lifecycle status) toggle
• Forms — field (Field/FieldStack/Input/Select/Textarea) image-input inline-rename select-list tag-input env-draft-editor (masked env drafts + paste-a-.env preflight) use-draft-state (sessionStorage dialog drafts; pair with Radix onInteractOutside prevented while dirty)
• Actions — use-action (useAction/requestJson) action-error (actionErrorText)
• Overlays — dialog action-menu confirm-dialog edit-dialog copy-once (CredentialsOnceDialog/CopyRow) command-palette (+ pure command-palette-data + use-command-menu wrapper hook) set-in-vault-dialog (SetInVaultDialog/SetInVaultButton) step-up-reveal
• Copy — copy-button copy-link-button
• Rows & layout — entity-row resource-row section-card table meta-pill filter-tabs page-header auth-frame team-roster panel (+PanelFooterButton) section-label (the one uppercase eyebrow) segmented-control (the pill segment picker) figure (inline 13px stat) code-chip (mono one-time code + CopyButton)
• Settings — mail-settings-form (one ResourceRow mail card: set-in-vault → connect → reconnect, test/disconnect in the … menu) settings-modal (SettingsModal/SettingsSection: the wide sticky-header scaffold — settings live in a modal, not a page) setting-row (SettingRow: Linear-style inline edit — click the value, save on blur/Enter through injected onSave, busy/error in place; clamped textarea for long text)
• Content — markdown disclosure jot-list (dense collapsed-by-default expandable rows: glyph · clamped title · timestamp · trailing slot) log-view (filter/problem jumps/wrap/copy/stick-to-tail) run-tree (strict-contract v1 run journal)
• Charts — time-series-chart (multi-series time x-axis, null gaps, stacked mode, shared-crosshair tooltip, --color-chart-1..6 tokens) breakdown-bar (100% share bar + legend) range-tabs (24h/7d/30d window) trend-chart sparkline spark-bars funnel stat-tile (+delta/spark/subline) (shared chart-math + internal chart-parts)
• Live — live/use-event-stream live/stream-status-chip live/snapshot-cache live/agent-live (createAgentLive/envelopeData: one shared EventSource in context) live/activity-face (the ticking/exploring/idle/offline vocabulary) live/agent-presence (ambient header chip) live/agent-rail (the Home command rail + drill-down) live activity components; server: live/server (sseResponse/envelope)
• Harness (v2) — the @rubriclab/rubrot-ui/harness subpath exports HarnessRuntimeStatus, HarnessRuntimeControls, HarnessFreshness, HarnessAccounts, HarnessUsage, HarnessRateLimits, and HarnessSkills. Controls emit canonical revisioned mutations; the Skills surface binds directly to the canonical client and preserves authoritative desired/effective state through reconnects without an application mirror.
• Timeline — the @rubriclab/rubrot-ui/timeline subpath exports the bounded Timeline feed, TimelineRunDeepView, compact SourceChips, safe SourceLink, buildRunDeepTree, and their strict data/prop types and Zod contracts. Apps pass the canonical projected page/deep models directly; there is no renderer adapter.
• Keyboard — keyboard/kbd keyboard/keyboard-nav (g-then-key + shortcuts overlay)
• PWA — pwa/register (PwaProvider) pwa/install-prompt pwa/manifest (defineManifest); server: pwa/server (createServiceWorkerRoute/createPwaVersionRoute)
• Utils — utils (cn/formatCompact/copyText) dates dotenv (the one KEY=value parser) humanize scrub file-kind

New in 0.3.0

Dataviz + the settings-modal primitives, built for the Wave-1 surface rebuilds (control room, cockpit, settings modal):

• TimeSeriesChart — 2–6 series on a real time axis (day/hour ticks from the span), null-gap honesty, optional stacking, client-only shared crosshair + tooltip (SSRs clean without it), TrendChart-idiom delta badge. Series colors are the new --color-chart-1..6 theme tokens — a CVD-validated categorical order (worst adjacent pair ΔE 65.6, all six ≥ 3:1 on --color-card); identity only, never state.
• RangeTabs — controlled 24h/7d/30d window selector (FilterTabs look, buttons not hrefs); one row scopes every chart below it.
• StatTile v2 — back-compatible delta (tone = direction × goodness) and inline spark sparkline.
• BreakdownBar — 100% share bar + inline legend for per-provider / per-billing-method splits; color follows the entity via explicit slots.
• SettingsModal / SettingsSection / SettingRow — the D6/D7 settings surface: wide dialog, sticky compact header, hairline sections, and the inline-edit row (input/select/textarea variants, async save on blur/Enter via injected onSave, clamped overflow textarea).
• JotList — the compact log-row shape on Disclosure.

Promotions in 0.2.0

Fleet-proven components, generalized on the way in:

• SetInVaultDialog / SetInVaultButton (vault canonical + radar's launcher deltas) — the vault-API coupling became an injected onSubmit(values); info rows unify vault's infoRows and radar's hint on CopyRow; the button degrades to a fallbackHref deep link when in-app writes aren't provisioned.
• MailSettingsForm (vault + radar unified on the ResourceRow shape) — app wiring injected: connectHref, setInVault action slot, onTest/onDisconnect returning the note to show; vault's sending-as override kept via status.sendingAs.
• TeamRoster (vault + radar) — read-only divide-y roster; per-member state via tone, everything app-specific in the actions slot.
• useDraftState + EnvDraftEditor + dotenv (metal) — sessionStorage draft semantics preserved verbatim; the zod coupling became the structural DraftContract (any zod schema still passes as-is).
• Agent live rail (radar) — createAgentLive<T>() keeps the wire shape app-side behind parse; AgentRail/AgentPresence render injected facts/counts/faces.
• StepUpReveal (vault) — the WebAuthn ceremony became the injected verify() resolving { value } | { noPasskey }; the component owns only the step-up UX.
• useCommandMenu (rubrot + metal wrappers) — ⌘K toggle, g-chords, per-open refresh, openCommandMenu() event, and the platform hint.

Export contract

Button, Field (with Input/Textarea), Dialog, Notice, Spinner, Badge, Card, EmptyState are stable names other agents/apps code against. Server-only factories are deliberately NOT in the root export: import them from @rubriclab/rubrot-ui/live/server and @rubriclab/rubrot-ui/pwa/server.

Tests

bun test packages/ui — token guard, palette filtering, action error mapping, chart math (incl. time ticks/stacking/gaps), a TimeSeriesChart SSR-without-a-DOM fixture, SettingRow save/error behavior, JotList and RangeTabs toggling, SettingsModal scaffold (behavior tests run on happy-dom, registered per-file via test/dom.tsx), service-worker routing/boundary/headers, manifest defaults, scrub + dates, dotenv parsing, draft restore (parseDraft), and the command-menu editable-target guard.