@2lab.ai/ui

Agent UI components from the 2lab soma-work dashboard, as Web Components with zero runtime dependencies.

Demo & docs: https://2lab.ai/ui**

Surfaces — the page-level pieces around the agent (0.6.0):

Page parts — the pages around the app: settings, memory, sign-in (0.9.0):

Primitives — the building blocks the dashboard shares, in the same tone and motion:

Foundations: @2lab.ai/ui/icons (a 16-grid, 1.5-stroke currentColor SVG set — icon('gear') returns an SVG string) and @2lab.ai/ui/ui-kit.css (light-DOM classes on the same tokens: .ui-btn with one ink primary, .ui-icon-btn, .ui-fab — round, or .is-extended with a word that .is-folded folds away —, .ui-chip (.is-sm; .is-toned with an inline --ui-tone for a per-thing colour such as an environment tag — a tag, not a toggle: pressed and hover states stay the plain chip's), .ui-select-chip (a native <select> read as a label-sized chip, alone or in a <label> with a leading word), .ui-spinner (the working ring; a still ring with a dot under reduced motion), .ui-status, .ui-kbd, .ui-dl, .ui-skeleton, .ui-empty, .ui-status-line, .ui-avatar, .ui-owner-badge (the board's name pill; .is-self orbits — syncOwnerBadgeOrbit(el) keeps it in step with the board's), .ui-sr-only, .ui-expand, .ui-section-head with a .ui-count badge, and for page parts .ui-input, .ui-switch, .ui-card, .ui-notice, .ui-row — the row that is the page, aria-current="page", keeps the hover fill). Korean prose (lang="ko") breaks between words, never inside them, in every element and every kit class (word-break: keep-all).

Designs — whole looks for a site built with these parts (0.38.0): data-design="<id>" on <html> (with tokens.css) recolours every element and kit class, locked to the design's color scheme, and designs/<id>/DESIGN.md in this repository holds its tone & manner (layout, type, composition, an acceptance list). Start at designs/README.md; live at https://2lab.ai/ui/docs/designs.

Server — @2lab.ai/ui/server, the one entry with no element in it: authCardHtml(data) renders the auth card as a declarative shadow root the element later hydrates in place, authCardCss is its sheet as data, with tokensCss, kitCss, icon() and the escapers. Nothing in it touches the DOM at load, so it runs on Node as ESM (import) or CommonJS (require, the .cjs build); its types resolve under NodeNext and node10 (typesVersions).

// a route handler, ESM or CommonJS — the page works before (and without) the script
const { authCardHtml, tokensCss } = require('@2lab.ai/ui/server');
res.send(`<style>${tokensCss}</style>${authCardHtml(data, { page: true })}<script type="module" src="/lib/auth-card.js"></script>`);

Sound — opt-in interface cues (0.11.0): every element plays a short cue for what the person just did (a detent when a tab changes, air when a dialog opens, a soft chord when a run is done). Off until the person turns it on. @2lab.ai/ui/sound is the policy (setSound, bindSound, quiet regions, opt-in typing) and loads no audio; @2lab.ai/ui/sound-cuelume is the player — Cuelume's fourteen cues synthesized live with Web Audio, no audio files, bundled so the package keeps zero runtime dependencies. See https://2lab.ai/ui/docs/sound.

import { bindSound, setSound } from '@2lab.ai/ui/sound';
bindSound();                                   // your own <button data-ui-sound> … sound too
// in the click that turns sound on (keep the choice beside the theme switch):
const { cuelumeSound, unlockSound } = await import('@2lab.ai/ui/sound-cuelume');
setSound({ player: cuelumeSound, enabled: true });
unlockSound();

Install

npm i @2lab.ai/ui

import '@2lab.ai/ui';                 // registers every element
import '@2lab.ai/ui/context-window';  // or just one
import '@2lab.ai/ui/tokens.css';      // optional page tokens (data-theme="dark" switches)
import '@2lab.ai/ui/ui-kit.css';      // optional light-DOM classes (buttons, chips, status …)
import { icon } from '@2lab.ai/ui/icons';
import { authCardHtml } from '@2lab.ai/ui/server';  // on a server: no DOM, no element; require() works too

No build step: <script type="module" src="https://2lab.ai/ui/lib/index.js"></script>.

Use

<ui-context-window lang="en"></ui-context-window>
<script type="module">
  const el = document.querySelector('ui-context-window');
  el.data = { window: 1_000_000, autoCompactAt: 750_000, parts: { cacheRead: 272300, output: 10 }, canCompact: true };
  el.addEventListener('ui-compact', async () => {
    el.data = { ...el.data, compactState: 'sending' };   // assign a new object — in-place mutation does not re-render
    await fetch('/compact', { method: 'POST' });
    el.data = { ...el.data, compactState: 'sent' };
  });
</script>

Data in (el.data = {...} — always assign a new object), events out (ui-*, bubbling + composed). Elements never fetch. English by default, Korean with lang="ko". Light/dark follow the OS, theme="light|dark" pins one, --ui-* custom properties theme a page, and data-design="modern-mono" applies a whole design (see designs/README.md).

Develop

npm i
npm run dev          # demo site with live reload
npm run verify       # biome · tsc · vitest · lib + site build · packed-tarball consumer check (NodeNext + node10 types, every element registers, require('@2lab.ai/ui/server'))

See AGENTS.md for the component contract.

Credits

Interaction patterns were studied from affectUI and re-implemented for the soma-work dashboard's own data. No affectUI code or assets are included.

Interface sounds: Cuelume (MIT, Daniel Belyi) is bundled into dist/sound-cuelume.js; the sound policy is ported from Morphin UI (MIT, Ivan Oliinyk).

Six elements are ported from bencho.dev's free blocks (MIT, Lorenzo Cabra — https://bencho.dev/licence): Slide to Confirm, Agent Island (Dynamic island), Step Track (Step player), Action Node, Image Compare and ASCII Wake. Bencho Pro blocks may not be passed on inside a component library, so none is included.

Their notices ship in dist/THIRD_PARTY_NOTICES.md.