ui

Burtson UI

React components for Burtson Labs products.

Used in Bandit Stealth, Sentinel, our cluster tools and client apps. Burtson Labs' own primitive layer (src/primitives: focus, dismissal, positioning, presence, menus, selects, form controls) handles behaviour; Tailwind v4 handles styling, and the icons are Burtson Icons. No runtime provider. Install the package, or copy a component's source and change it.

Docs for AI agents: llms.txt · llms-full.txt · Use with AI agents

Install

npm install @burtson-labs/ui @burtson-labs/icons

With Tailwind CSS v4, add the theme and let Tailwind see the component classes:

@import 'tailwindcss';
@import '@burtson-labs/ui/theme.css';
@source '../node_modules/@burtson-labs/ui/dist';

Without Tailwind (an MUI app, for example), import the precompiled styles once:

import '@burtson-labs/ui/styles.css';

Then:

import { Button } from '@burtson-labs/ui';

export const Save = () => <Button>Save</Button>;

Or copy the source

Every component is also a registry item in the shadcn registry format. The CLI copies the file into components/ui, installs its dependencies and adds the Burtson theme:

npx shadcn@latest add https://ui.burtson.ai/r/button.json

Or add the @burtson namespace to components.json and install by name:

{ "registries": { "@burtson": "https://ui.burtson.ai/r/{name}.json" } }

npx shadcn@latest add @burtson/button

Use with AI agents

Claude Code, Cursor, Codex, Copilot and other coding agents can read the docs as plain text and install components through the registry:

• llms.txt lists every component; llms-full.txt has them all in one file; each page is also Markdown at https://ui.burtson.ai/docs/components/<name>.md.
• npx shadcn@latest mcp init --client claude (or cursor, vscode, codex) sets up the shadcn MCP server, which can search and install @burtson/* items once the namespace is in components.json.
• npx skills add burtson-labs/ui installs the burtson-ui Agent Skill.

The Use with AI agents page has a block of rules to paste into CLAUDE.md or AGENTS.md and example prompts. Contributors' agents: see AGENTS.md.

Components

Accordion · Agent Run · Alert · Alert Dialog · App Shell · Attachment · Audio Player · Avatar · Avatar Upload · Badge · Breadcrumb · Button · Card · Chat History · Chat Layout · Checkbox · Checkbox Card · Collapsible · Combobox · Command · Composer · Connection Status · Context Menu · Conversation · Copy Button · Data Table · Dialog · Dropdown Menu · Editor Tabs · Empty State · Error Summary · Field · Form Actions · Icon Button · Input · Kbd · Label · Markdown · Menubar · Message · Message Actions · Mobile Nav · Native Select · Navigation Menu · Number Input · Onboarding Checklist · Page Header · Pagination · Popover · Progress · Radio Group · Reasoning · Resizable · Scroll Area · Secret Input · Select · Separator · Sheet · Skeleton · Slider · Source · Spinner · Stat Card · Status · Steps · Switch · Table · Tabs · Textarea · Toast · Toaster · Tool Call · Toolbar · Tooltip · Tour · Tree View · Voice Recorder

Live previews, when-to-use notes, accessibility notes and code for each one are at ui.burtson.ai. Building a chat app? The chat recipe puts history, attachments, streaming, voice notes and full screen together, with the complete source. Building a form? Field wires label, help and error onto any control, FieldGrid lines fields up and FormActions places the buttons, on phones too.

Every control is at least 44px on touch screens, shows one focus style per kind of control (focusRingClasses, fieldFocusClasses) and meets 4.5:1 for text and 3:1 for boundaries in both palettes and any accent; a Playwright smoke in CI measures it.

Agent decisions, loading and appearance

import {
  AskUser, AgentPlan, ContextUsage, CircularProgress, LoadingDots,
  ThemeProvider, ThemeToggle,
} from '@burtson-labs/ui';

<ThemeProvider defaultTheme="system" storageKey="app-theme">
  <ThemeToggle />
  <AskUser
    questions={[{ id: 'goal', prompt: 'What should I focus on?' }]}
    onSubmit={async (answers) => { await sendAnswers(answers); }}
  />
</ThemeProvider>

<CircularProgress label="Connecting" />; // unknown duration
<CircularProgress value={64} label="Uploading" showValue />;
<LoadingDots label="Thinking" showLabel />;
<ContextUsage used={42000} limit={200000} />;

Load the theme init script in <head> so a saved dark theme applies before first paint (no light flash). Under a strict CSP serve the file, configured with data attributes:

<script src="/theme-init.js" data-storage-key="app-theme"></script>

Copy it from @burtson-labs/ui/theme-init.js, or render themeInitScript({ storageKey: 'app-theme' }) inline and add await themeInitScriptHash({ storageKey: 'app-theme' }) to script-src.

The theme editor previews presets, custom accents, corner radius and control density and exports both palettes. Agent callbacks belong to your runtime. See the coverage audit for the existing components and remaining workflow gaps.

Theming

src/tokens.ts is the single source of colour, radius and type. It generates theme.css (the CSS variables, with shadcn names plus brand, brand-soft, success and warning), feeds the registry's theme item, and drives the MUI adapter. Light is the default; add class="dark" or data-theme="dark" to <html> for dark.

MUI apps

Most Burtson Labs apps run MUI today. They can share the palette now and adopt components one screen at a time:

import { ThemeProvider } from '@mui/material/styles';
import { createBurtsonTheme } from '@burtson-labs/ui/mui';

<ThemeProvider theme={createBurtsonTheme('dark')}>{app}</ThemeProvider>;

// A product accent and admin density; contrast is kept for any accent.
createBurtsonTheme({ mode: 'dark', accent: '#2563eb', density: 'compact' });

@burtson-labs/ui/tokens also exports accentTokens(accent, mode) for the CSS side, the motion timing (duration, easing) that theme.css exposes as --duration-* and --ease-* and every transition-* utility runs on, the elevation levels (shadow.lg for floating surfaces, shadow.xl for modal ones) and the layer z-index scale (raised 10, chrome 40, overlay 50, toast 100).

Develop

npm install
npm run dev        # docs site with live components, http://localhost:5173
npm run check      # typecheck, lint, format, tests, package build, site build
npm run smoke      # Playwright: touch targets, focus, overflow, keyboard (needs npm run site)
npx playwright test --config playwright.navigation.config.ts # navigation, including mobile Safari

Adding a component: write src/components/<name>.tsx (forwardRef, data-slot on every part, focusRingClasses or fieldFocusClasses for focus, 44px on touch), export it from src/index.ts, add a demo in site/src/demos/<name>.tsx, an entry in site/src/docs.ts, its notes in site/src/usage.ts and a cell in site/src/matrix.tsx. The registry picks it up on the next build.

Linting and formatting follow Burtson Labs frontend standards. Every push is audited by Sentinel.

Primitives and API references

The behaviour primitives are Burtson Labs' own layer under src/primitives, written from the WAI-ARIA Authoring Practices and the web specifications (design notes in its README; copy-source use on the Primitives page). The kit has no Radix, cmdk or other component-library code in it and no runtime dependency on them. API_REFERENCE.md lists the generated component references, and THIRD_PARTY_NOTICES.md the licenses of what remains adapted (shadcn/ui's class lists and conventions).

License

MIT © Burtson Labs. Inspired by and partly adapted from shadcn/ui (MIT); see THIRD_PARTY_NOTICES.md.