# Twentyfirst UI: complete docs

> Version 0.6.0. Examples import from `@twentyfirstmedia/halo`; for Pro import the same names from `@twentyfirstmedia/pro`. Patterns (full screens) are linked at the end; their code is in each linked Markdown page.

## Introduction

> Halo is one of the two Twentyfirst UI kits: React components, tokens and complete screens with the same API as Pro.

Twentyfirst UI is two React UI kits with one component API.

- **Halo** is soft, rounded and light-first: big white cards on a warm canvas, five pastel tints that carry meaning and ink as the only accent.
- **Pro** is sharp, dense and dark-first: monochrome cells on a visible hairline grid, square corners, Geist, and colour only for state.

Both kits have exactly the same components, props, markup, classes and tokens. Only tokens and CSS differ, so an app can load both and switch at runtime with `data-kit`, without changing markup or losing state.

### What is in the box

- 236 components on 119 pages: foundations, navigation, forms, data, charts, overlays, AI (chat, agents, approvals), commerce, admin, real estate and media.
- 37 patterns: complete screens built only from kit parts.
- Tokens for colour, type, space, radius, shadow and motion in light and dark, as CSS variables and as a Tailwind v4 preset.
- A CLI that sets up an app and copies components when you want to own them, and an MCP server so coding agents know every component.

### Principles

- **Mobile first.** Every component works from a 320px screen up: shells collapse, tables scroll, dialogs become sheets and inputs never zoom.
- **Accessible.** Keyboard paths, focus rings and ARIA follow the WAI-ARIA practices; axe (WCAG 2.1 AA) runs on every example of both kits, light and dark.
- **Tokens only.** No colour literals in component CSS.
- **Private.** Fonts are self-hosted, nothing phones home and components make no requests of their own.
- **English, formatted with Intl.** Built-in text is plain English and overridable through props or `UIProvider messages`; numbers, money, percentages and dates go through `formatNumber`, `formatMoney`, `formatPercent` and `formatDate`, in en-US or the `UIProvider locale` ([Text and locale](https://ui.twentyfirst.media/halo/text/)).

### Quick start

```sh
npx @twentyfirstmedia/ui init --kit halo
```

```tsx
import "@twentyfirstmedia/halo/styles.css";
import { UIProvider, Button } from "@twentyfirstmedia/halo";

export function App() {
  return (
    <UIProvider>
      <Button variant="primary">Save</Button>
    </UIProvider>
  );
}
```

Next: [Installation](https://ui.twentyfirst.media/halo/installation/), [CLI](https://ui.twentyfirst.media/halo/cli/), [Theming and tokens](https://ui.twentyfirst.media/halo/theming/), [AI agents and MCP](https://ui.twentyfirst.media/halo/ai/) and [all components](https://ui.twentyfirst.media/halo/components/).


## Installation

> Install one kit from npm, import its styles once and wrap the app in UIProvider. React 18.3 or 19; works with Next.js, Vite and any React setup.

### 1. The kit

The packages are on npm under the MIT license. Install a kit with the CLI (it also sets up styles, the provider and the Next.js layout) or by hand:

```sh
npx @twentyfirstmedia/ui init --kit halo
# or
pnpm add @twentyfirstmedia/halo
```

### 2. Styles and provider

Import `styles.css` once. It brings the self-hosted fonts, the tokens (light, dark, density) and every component style; no `data-kit` attribute is needed.

```tsx
import "@twentyfirstmedia/halo/styles.css";
import { UIProvider, Button } from "@twentyfirstmedia/halo";

export function App() {
  return (
    <UIProvider theme="system">
      <Button variant="primary">Save</Button>
    </UIProvider>
  );
}
```

### Tailwind v4

The kit ships a preset that maps every token to Tailwind and clears the default palette, so utilities can only use kit values.

```css
@import "tailwindcss";
@import "@twentyfirstmedia/halo/tailwind.css";
```

### Both kits in one app

Import `@twentyfirstmedia/ui-core/themes.css` instead (both kits, scoped under `[data-kit="…"]`) and switch with `<UIProvider kit="pro">` or the attribute on `<html>`. Markup, props and state stay as they are.

```tsx
import "@twentyfirstmedia/ui-core/themes.css";
import { UIProvider } from "@twentyfirstmedia/halo";

<UIProvider kit={userPrefersPro ? "pro" : "halo"}>{children}</UIProvider>;
```

### Fonts for share images

Tools that cannot read woff2 or variable fonts, such as `next/og` (Satori) or PDF generators, get static WOFF files under `fonts/og/`: Halo ships Plus Jakarta Sans (400–800) and IBM Plex Mono (500, 600), Pro ships Geist (400–700) and Geist Mono (500, 600), latin subset.

```tsx
// app/opengraph-image.tsx
import { readFile } from "node:fs/promises";
import { createRequire } from "node:module";

const require = createRequire(import.meta.url);
const font = await readFile(
  require.resolve("@twentyfirstmedia/halo/fonts/og/plus-jakarta-sans-latin-700-normal.woff"),
);
// new ImageResponse(<div>…</div>, { fonts: [{ name: "Plus Jakarta Sans", data: font, weight: 700 }] })
```

### Coding agents

Give Claude Code, Cursor or VS Code the kit's docs with the MCP server, see [AI agents and MCP](https://ui.twentyfirst.media/halo/ai/):

```sh
npx @twentyfirstmedia/ui mcp init
```


## CLI

> npx @twentyfirstmedia/ui sets up a kit, copies components into your app when you want to change them and runs the MCP server for coding agents.

### init

Installs the kit, imports its styles (and the Tailwind preset when the app uses Tailwind), creates `components/ui-root.tsx` with the `UIProvider`, wraps the Next.js layout and sets `data-kit` on `<html>`. Running it again changes nothing.

```sh
npx @twentyfirstmedia/ui init --kit halo
npx @twentyfirstmedia/ui init --kit halo --both   # load both kits and switch at runtime
```

### add

Copies a component, with the private helpers it needs, into `components/ui`. Everything public stays an import from `@twentyfirstmedia/ui-core`, so the copy keeps working in both kits.

```sh
npx @twentyfirstmedia/ui add ApprovalCard DataTable
```

### list and diff

`list` shows every component by group and marks the ones you copied. `diff` compares your copy with the current package source, so updates are easy to merge by hand.

```sh
npx @twentyfirstmedia/ui list
npx @twentyfirstmedia/ui diff ApprovalCard
```

### mcp

`mcp` runs the MCP server on stdio; `mcp init` writes the config for Claude Code, Cursor and VS Code and adds the kit rules to `AGENTS.md`. See [AI agents and MCP](https://ui.twentyfirst.media/halo/ai/).

```sh
npx @twentyfirstmedia/ui mcp init --kit halo
npx @twentyfirstmedia/ui mcp init --client cursor --no-rules
```


## Theming and tokens

> Theme both kits like shadcn/ui: the same variables (primary, secondary, muted, accent, destructive, border, ring, radius, charts, sidebar) restyle every component, light and dark.

Both kits use shadcn/ui's theme variables. A theme is any CSS that sets them, so a theme from ui.shadcn.com/themes, tweakcn or your own design system works as it is, and every component follows it: buttons, fields, menus, tables, charts, the Sidebar, in Halo and in Pro, light and dark.

```css
@import "@twentyfirstmedia/halo/styles.css";

:root {
  --primary: oklch(0.546 0.245 262.881);
  --primary-foreground: oklch(0.985 0 0);
  --ring: oklch(0.546 0.245 262.881);
  --radius: 0.75rem;
}
.dark,
[data-theme="dark"] {
  --primary: oklch(0.707 0.165 254.624);
  --primary-foreground: oklch(0.145 0 0);
}
```

The kits define their variables with zero specificity, so your theme wins in any order. Dark mode follows `data-theme="dark"` or the `.dark` class on `<html>` (next-themes works as it is), and `data-theme="system"` follows the operating system.

### The variables

| Variable | Used for |
| --- | --- |
| `--background`, `--foreground` | Page background and default text |
| `--card`, `--card-foreground` | Cards, panels, fields, the workspace sheet |
| `--popover`, `--popover-foreground` | Menus, popovers, select lists, command palette, hover cards, dialogs |
| `--primary`, `--primary-foreground` | Primary buttons, checked boxes and radios, switches, selected chips and days, progress, current marks |
| `--secondary`, `--secondary-foreground` | Soft buttons and icon buttons |
| `--muted`, `--muted-foreground` | Quiet fills (tracks, search fields, code) and secondary text |
| `--accent`, `--accent-foreground` | The highlight under the pointer or keyboard: menu items, rows, options, nav items |
| `--destructive`, `--destructive-foreground` | Danger buttons, error text and icons |
| `--border`, `--input`, `--ring` | Hairlines, field and checkbox borders, focus rings |
| `--radius` | The base corner radius; every corner derives from it |
| `--chart-1` … `--chart-5` | Chart series (lines, dots, legends) |
| `--sidebar`, `--sidebar-foreground`, `--sidebar-primary`, `--sidebar-primary-foreground`, `--sidebar-accent`, `--sidebar-accent-foreground`, `--sidebar-border`, `--sidebar-ring` | The Sidebar |

The kits' own names (`--canvas`, `--surface`, `--ink`, `--line`, Pro's `--bg-000` … `--fg-400` scale) point at these, and the in-between shades are mixed from them, so you only set the variables above. Outside the theme on purpose: the five tints and status colours (they carry meaning), Halo's dark app frame, paper (e-mail and invoice previews) and media overlays. Halo draws chart bars in soft fills of the series colours (`--chart-sky` … `--chart-blush`); the theme builder and `twentyfirst-ui theme` set them for you when the charts change.

### Presets, CLI and builder

Six brand presets keep each kit's neutrals and change the brand colour: blue, violet, emerald, orange, rose and teal.

```css
@import "@twentyfirstmedia/halo/styles.css";
@import "@twentyfirstmedia/halo/themes/violet.css";
/* both kits loaded: @twentyfirstmedia/ui-core/themes/violet.css */
```

The CLI writes a theme into your app and imports it: a preset, a brand colour (light, optionally dark) or a shadcn theme file.

```sh
npx @twentyfirstmedia/ui theme violet
npx @twentyfirstmedia/ui theme "#2563eb,#60a5fa"
npx @twentyfirstmedia/ui theme ./shadcn-theme.css
```

The [theme builder](https://ui.twentyfirst.media/halo/themes/) shows a theme live on real components and gives you the CSS.

### Themes at runtime

For a brand per customer or a colour the user picks, `UIProvider` takes the same variables. One set applies in both modes; `{ light, dark }` picks by the current theme.

```tsx
import { UIProvider, brandTheme } from "@twentyfirstmedia/halo";

<UIProvider tokens={{ primary: tenant.color, ring: tenant.color }}>{children}</UIProvider>;
<UIProvider tokens={brandTheme("#2563eb", "#60a5fa")}>{children}</UIProvider>;
```

`themeCss(theme, { kit })` writes the CSS for a theme (for a server-rendered `<style>`), `parseThemeCss(css)` reads a shadcn theme, and `brandTheme(color)` picks readable text for a brand colour.

### Glass

For UI that floats over a map, a 3D scene, a video or photos, surfaces can be glass: translucent, blurred and colour-lifted over what is behind, with light catching the top edge. Halo's glass is soft and milky, Pro's is dark with a hairline edge.

```tsx
import { FloatingLayout, MapView, Panel, SearchField, UIProvider } from "@twentyfirstmedia/halo";

// a layout for UI over a background: four slots, glass by default
<FloatingLayout
  height={720}
  background={<MapView background={<YourMap />} points={places} height="100%" />}
  top={<SearchField placeholder="Search places" />}
  start={<Panel title="Layers">…</Panel>}
  end={<Panel title="Harbour Museum">…</Panel>}
/>;

// one surface
<Panel surface="glass" title="Layers">…</Panel>;

// everything floating in a subtree: panels, cards, dock, map legend, menus, popovers, dialogs
<UIProvider scope="subtree" surface="glass">…</UIProvider>;
```

- Inside a glass region, top-level Panels, Cards, the Dock and map legends and controls turn into glass, and so do loose controls (search field, chips, icon and secondary buttons, segmented controls). Menus, popovers, dialogs and drawers take a stronger fill because they carry more text. A surface nested in a glass surface stays clear instead of stacking glass on glass; `surface="solid"` opts one out.
- What sits on glass follows it: inputs, tab tracks, badges, hover and selection highlights turn translucent too.
- The fills keep body text at 4.5:1 or more over any backdrop. Reduced transparency and forced colours switch to solid surfaces, more contrast to the stronger fill, and browsers without backdrop blur get the stronger fill too.
- The glass tokens are themable like every other colour: `--glass`, `--glass-strong`, `--glass-control`, `--glass-well`, `--glass-hover`, `--glass-border`, `--glass-highlight`, `--glass-sheen`, `--shadow-glass` and `--glass-filter` (the backdrop filter). By default they derive from `--card` and `--foreground`, so a theme carries over.
- Without React: `class="tf-glass"` on a surface, or `data-surface="glass"` on any container.

See the [map pattern](https://ui.twentyfirst.media/halo/patterns/MapScreen/) for a full screen.

#### Glass dashboards

A whole app can be glass: put `Ambient` behind it and wrap it in `<UIProvider surface="glass">`. The `AppShell` turns into glass too (top bar, rail, sidebar; the sheet clears so the background shows through), and tinted tiles (`StatTile tint="sky"`, tinted Cards) lay their tint over the glass instead of an opaque block.

```tsx
import { Ambient, AppShell, StatTile, UIProvider } from "@twentyfirstmedia/halo";

<UIProvider surface="glass">
  <Ambient fixed />
  <AppShell brand="Bloom">
    <StatTile value="7h 42m" label="Sleep" tint="sky" />
    …
  </AppShell>
</UIProvider>;
```

`Ambient` draws soft colour fields from `--ambient-1…4` (pastels in Halo, a faint aurora in Pro) that drift slowly; `colors` takes your own, `src` a photo or (with `video`) a video under a calming scrim, and children your own layer. The drift stops with motion off and pauses off screen. With `fixed`, keep `body` transparent so the background shows. On glass, the faintest text steps up one shade so secondary text stays readable. See the [wellbeing pattern](https://ui.twentyfirst.media/halo/patterns/WellbeingScreen/).

### Tailwind

The preset maps the variables to shadcn's utility names, so `bg-primary text-primary-foreground`, `bg-muted text-muted-foreground`, `border-border`, `ring-ring` and `bg-sidebar` work, plus the kits' own names (`bg-surface`, `text-ink`).

### Light, dark and density

Theme and density are attributes: `data-theme="light|dark|system"` and `data-density="compact|comfortable"` on `<html>` or any subtree, or the `theme` and `density` props of `UIProvider`. Halo follows the system theme and is comfortable by default; Pro is dark and compact by default.

```tsx
<UIProvider theme="dark" density="compact">…</UIProvider>
```

### Layout and breakpoints

The kits are mobile first: every component works from a 320px wide screen up, and from 1181px on the full desktop layout applies. Phones (up to 760px) get one column: the shell stacks, rail and page nav become scrolling rows, the dock sticks to the bottom, tables scroll inside their box, dialogs open as bottom sheets and popovers stay on screen. Tablets (761–1180px) move asides below the main column. On touch screens text fields use 16px so browsers do not zoom in, and a compact kit (Pro) switches to comfortable hit targets unless `data-density` is set.

For your own grids, `tf-grid` takes its columns from custom properties: `--cols` on desktop, `--cols-md` on tablets (defaults to `--cols`) and `--cols-sm` on phones (defaults to one column).

```tsx
<div
  className="tf-grid"
  style={{ "--cols": "repeat(4, minmax(0, 1fr))", "--cols-sm": "1fr 1fr" } as React.CSSProperties}
>
  <StatTile value="18" label="Projects" />
  …
</div>
```

### Control sizes

Every control sits on one height scale: Halo 32 / 40 / 48px (sm / md / lg), Pro 24 / 28 / 34px. Mix sizes only on purpose; a row of controls uses one size.

### Colour

| Token | Halo | Pro | Use |
| --- | --- | --- | --- |
| `--background` | `#f4f3f0 / #0f0f10` | `#f6f6f7 / #09090b` | Theme: page background behind every panel (shadcn `background`). |
| `--foreground` | `#141414 / #f2f1ed` | `#111114 / #ededf0` | Theme: default text and icons (shadcn `foreground`). |
| `--card` | `#ffffff / #1a1a1c` | `#ffffff / #0e0e11` | Theme: cards, panels, inputs and the workspace sheet (shadcn `card`). |
| `--card-foreground` | `{foreground}` | `{foreground}` | Theme: text on cards. |
| `--popover` | `{card}` | `{card}` | Theme: menus, popovers, select lists, command palette, hover cards, dialogs. |
| `--popover-foreground` | `{foreground}` | `{foreground}` | Theme: text on popovers. |
| `--primary` | `#141414 / #f2f1ed` | `#111114 / #ededf0` | Theme: the brand colour. Primary buttons, checked boxes, switches, selected chips and days, progress, active marks. |
| `--primary-foreground` | `#ffffff / #141414` | `#ffffff / #09090b` | Theme: text and icons on `primary`. |
| `--primary-hover` | `{primary}` | `color-mix(in oklab, {primary} 70%, #000000) / color-mix(in oklab, {primary} 70%, #ffffff)` | Theme: `primary` under the pointer. |
| `--secondary` | `#ecebe7 / #232326` | `#f0f0f2 / #16161a` | Theme: secondary actions. Soft buttons and icon buttons, neutral chips and badges. |
| `--secondary-foreground` | `{foreground}` | `{foreground}` | Theme: text on `secondary`. |
| `--muted` | `#ecebe7 / #232326` | `#f0f0f2 / #16161a` | Theme: quiet fills. Tracks of segmented controls, tabs and progress, search fields, code, placeholders. |
| `--muted-foreground` | `#5f5e5a / #a9a8a3` | `#4f4f58 / #a6a6b0` | Theme: secondary text, captions, metadata. |
| `--accent` | `#ecebe7 / #232326` | `#f0f0f2 / #16161a` | Theme: highlight under the pointer or keyboard. Menu items, list rows, options, ghost buttons, nav items. |
| `--accent-foreground` | `{foreground}` | `{foreground}` | Theme: text on `accent`. |
| `--destructive` | `#8a2b23 / #f2a8a0` | `#b0301f / #ef6f61` | Theme: destructive actions and errors. Danger buttons, error text and icons. |
| `--destructive-foreground` | `{card}` | `{card}` | Theme: text on solid `destructive`. |
| `--border` | `#e5e4df / #2c2c30` | `#dfdfe3 / #26262c` | Theme: hairlines and dividers between surfaces. |
| `--input` | `#a8a7a1 / #5a5a60` | `#8a8a94 / #62626d` | Theme: borders of fields, checkboxes and radios, and strong lines. |
| `--ring` | `#2f6fe0 / #8fb8ff` | `{foreground}` | Theme: keyboard focus rings. |
| `--chart-1` | `{sky-ink}` | `{sky-ink}` | Theme: chart series 1 (sky series). |
| `--chart-2` | `{mint-ink}` | `{mint-ink}` | Theme: chart series 2 (mint series). |
| `--chart-3` | `{butter-ink}` | `{butter-ink}` | Theme: chart series 3 (butter series). |
| `--chart-4` | `{lilac-ink}` | `{lilac-ink}` | Theme: chart series 4 (lilac series). |
| `--chart-5` | `{blush-ink}` | `{blush-ink}` | Theme: chart series 5 (blush series). |
| `--sidebar` | `{card}` | `{card}` | Theme: Sidebar background. |
| `--sidebar-foreground` | `{foreground}` | `{foreground}` | Theme: Sidebar text. |
| `--sidebar-primary` | `{primary}` | `{primary}` | Theme: Sidebar emphasis (current item mark, badges). |
| `--sidebar-primary-foreground` | `{primary-foreground}` | `{primary-foreground}` | Theme: text on `sidebar-primary`. |
| `--sidebar-accent` | `{accent}` | `{accent}` | Theme: Sidebar item under the pointer and the current item. |
| `--sidebar-accent-foreground` | `{accent-foreground}` | `{accent-foreground}` | Theme: text on `sidebar-accent`. |
| `--sidebar-border` | `{border}` | `{border}` | Theme: Sidebar edges and dividers. |
| `--sidebar-ring` | `{ring}` | `{ring}` | Theme: focus rings inside the Sidebar. |
| `--canvas` | `{background}` | `{bg-000}` | Page background behind every panel and card. |
| `--surface` | `{card}` | `{bg-100}` | Cards, panels, inputs and the main workspace sheet. |
| `--surface-sunken` | `{muted}` | `{bg-200}` | Search fields, segmented-tab tracks, quiet chips and icon-button fills on `surface`. |
| `--frame` | `#121212 / #050505` | `{bg-100}` | The dark app frame: top bar, dock and the outer shell around the workspace. |
| `--on-frame` | `#f4f3f0 / #f2f1ed` | `{fg-100}` | Text and icons on `frame`. |
| `--on-frame-muted` | `#a3a29d` | `{fg-300}` | Secondary text and idle nav icons on `frame` (7:1+). |
| `--ink` | `{foreground}` | `{fg-100}` | Headings, numbers and body copy on `surface`, `canvas`, `surface-sunken` and every tint. |
| `--ink-muted` | `{muted-foreground}` | `{fg-200}` | Descriptions, meta lines and labels on `surface` and `canvas` (4.5:1+ in both themes). |
| `--ink-subtle` | `color-mix(in oklab, {muted-foreground} 91%, {background}) / color-mix(in oklab, {muted-foreground} 84%, {background})` | `{fg-300}` | Placeholders, disabled text and the quietest meta; 4.5:1 on surface and surface-sunken in both themes, still clearly lighter than ink-muted. |
| `--line` | `{border}` | `{line-200}` | Hairline dividers and table rules; decorative, never the only boundary of a control. |
| `--line-strong` | `{input}` | `{line-300}` | Dashed placeholder tiles and input borders (3:1 on `surface`). |
| `--sky` | `#cfe3fb / #1e3550` | `{info-bg}` | Info tint: stat tiles, event cards, the 'scheduled' state. Text on it is `ink`. |
| `--sky-ink` | `#1f4f8a / #9cc6f7` | `{info}` | Icons and labels on `sky` or as an icon colour on `surface`. |
| `--mint` | `#d6efc3 / #24401a` | `{ok-bg}` | Success tint: published/live states, positive stat tiles. Text on it is `ink`. |
| `--mint-ink` | `#2f5d16 / #a8db86` | `{ok}` | Icons and labels on `mint`; success marks on `surface`. |
| `--lilac` | `#e9cdf4 / #3d2547` | `{signal-bg}` | Highlight tint: the one featured card in a grid, lesson events. Text on it is `ink`. |
| `--lilac-ink` | `#6a2a82 / #dba6ee` | `{signal}` | Icons and labels on `lilac`. |
| `--butter` | `#fbe7aa / #4a3a10` | `{warn-bg}` | Money and attention tint: revenue tiles, task events, pending states. Text on it is `ink`. |
| `--butter-ink` | `#6b4d00 / #f3d374` | `{warn}` | Icons and labels on `butter`. |
| `--blush` | `#f8d6d2 / #4a2320` | `{danger-bg}` | Danger and support tint: errors, tickets, destructive confirms. Text on it is `ink`. |
| `--blush-ink` | `#8a2b23 / #f2a8a0` | `{danger}` | Icons and labels on `blush`; destructive text on `surface`. |
| `--focus` | `{ring}` | `{ring}` | Focus ring: 2px solid outline, 1px offset, on every interactive element. |
| `--count` | `#d6efc3` | `{signal}` | Count pills on nav items and tabs (unread, open approvals). |
| `--on-count` | `#141414` | `{bg-000}` | Text on `count`. |
| `--on-frame-success` | `#a8db86` | `{ok}` | Success marks on frame: the brand dot, ok lines in logs. |
| `--on-frame-danger` | `#f2a8a0` | `{danger}` | Error lines in logs and other danger marks on frame. |
| `--scrim` | `rgba(10, 10, 10, 0.32)` | `rgba(17,17,20,0.36) / rgba(0,0,0,0.62)` | Backdrop behind dialogs, sheets and the command palette. |
| `--scrim-strong` | `rgba(10, 10, 10, 0.38)` | `{scrim}` | Backdrop behind modals and the command palette. |
| `--glass` | `color-mix(in srgb, {card} 72%, transparent) / color-mix(in srgb, {card} 70%, transparent)` | `color-mix(in srgb, {card} 74%, transparent) / color-mix(in srgb, {card} 72%, transparent)` | Glass surfaces: panels, cards, docks and map overlays floating over content. Opaque enough that body text stays at 4.5:1 or more over any backdrop. |
| `--glass-strong` | `color-mix(in srgb, {card} 86%, transparent)` | `color-mix(in srgb, {card} 88%, transparent)` | Glass for text-heavy floating layers: menus, popovers, dialogs, drawers. |
| `--glass-control` | `color-mix(in srgb, {card} 62%, transparent) / color-mix(in srgb, {foreground} 10%, transparent)` | `color-mix(in srgb, {card} 55%, transparent) / color-mix(in srgb, {foreground} 7%, transparent)` | Inputs, secondary buttons and chips on glass (replaces surface inside a glass surface). |
| `--glass-well` | `color-mix(in srgb, {foreground} 6%, transparent)` | `color-mix(in srgb, {foreground} 5%, transparent)` | Tab tracks, badges, search fields and nested cards on glass (replaces surface-sunken). |
| `--glass-hover` | `color-mix(in srgb, {foreground} 8%, transparent) / color-mix(in srgb, {foreground} 12%, transparent)` | `color-mix(in srgb, {foreground} 7%, transparent) / color-mix(in srgb, {foreground} 9%, transparent)` | Hover and selection highlight on glass (replaces accent). |
| `--glass-border` | `rgba(255, 255, 255, 0.6) / rgba(255, 255, 255, 0.1)` | `color-mix(in srgb, {foreground} 12%, transparent) / color-mix(in srgb, {foreground} 14%, transparent)` | The hairline edge of a glass surface. |
| `--glass-highlight` | `rgba(255, 255, 255, 0.95) / rgba(255, 255, 255, 0.18)` | `rgba(255, 255, 255, 0.7) / rgba(255, 255, 255, 0.07)` | Light catching the top edge of a glass surface. |
| `--glass-sheen` | `rgba(255, 255, 255, 0.5) / rgba(255, 255, 255, 0.05)` | `transparent` | Pro glass is flat: no sheen. |
| `--ambient-base` | `{background}` | `{background}` | Ground of the Ambient background, under the colour fields. |
| `--ambient-1` | `color-mix(in oklab, {sky} 72%, {sky-ink}) / {sky}` | `color-mix(in oklab, {chart-1} 22%, {background}) / color-mix(in oklab, {chart-1} 30%, {background})` | First colour field of the Ambient gradient (a faint aurora in Pro). |
| `--ambient-2` | `color-mix(in oklab, {mint} 72%, {mint-ink}) / {mint}` | `color-mix(in oklab, {chart-4} 18%, {background}) / color-mix(in oklab, {chart-4} 26%, {background})` | Second colour field of the Ambient gradient. |
| `--ambient-3` | `color-mix(in oklab, {lilac} 72%, {lilac-ink}) / {lilac}` | `color-mix(in oklab, {chart-2} 16%, {background}) / color-mix(in oklab, {chart-2} 22%, {background})` | Third colour field of the Ambient gradient. |
| `--ambient-4` | `color-mix(in oklab, {butter} 72%, {butter-ink}) / {butter}` | `color-mix(in oklab, {foreground} 6%, {background}) / color-mix(in oklab, {foreground} 8%, {background})` | Fourth colour field of the Ambient gradient. |
| `--ambient-scrim` | `rgba(255, 255, 255, 0.28) / rgba(10, 10, 10, 0.45)` | `rgba(246, 246, 247, 0.4) / rgba(9, 9, 11, 0.55)` | Softens a photo or video under glass so the page keeps its calm. |
| `--bg-000` | `{canvas}` | `{background}` | Canvas: app background, behind hairline grids, inputs on surfaces. |
| `--bg-100` | `{surface}` | `{card}` | Surface: every grid cell, panel, table, sidebar, dialog. |
| `--bg-200` | `{surface-sunken}` | `{muted}` | Raised: row and button hover, kbd keys, skeletons, code blocks. |
| `--bg-300` | `{line}` | `color-mix(in oklab, {foreground} 3%, {muted}) / color-mix(in oklab, {foreground} 5%, {muted})` | Selected: active nav item, selected row, pressed segment, open menu trigger. |
| `--fg-100` | `{ink}` | `{foreground}` | Primary text and icons on every surface (bg-000 to bg-300). |
| `--fg-200` | `{ink-muted}` | `{muted-foreground}` | Secondary text: descriptions, table cells that are not the row's key, inactive nav items. On bg-000 to bg-300. |
| `--fg-300` | `{ink-muted}` | `color-mix(in oklab, {muted-foreground} 92%, {background}) / color-mix(in oklab, {muted-foreground} 90%, {background})` | Muted text: meta, timestamps, column headers, eyebrows. On bg-000 to bg-300. |
| `--fg-400` | `{ink-subtle}` | `color-mix(in oklab, {muted-foreground} 47%, {background}) / color-mix(in oklab, {muted-foreground} 57%, {background})` | Disabled text and placeholders only. Below 4.5:1 by design; never for information. |
| `--line-100` | `{line}` | `color-mix(in oklab, {border} 59%, {card}) / color-mix(in oklab, {border} 52%, {card})` | Faint hairline: row separators inside tables and lists, background grid. |
| `--line-200` | `{line}` | `{border}` | Hairline: the structural 1px grid between cells, panel and overlay borders, table header rule. Decorative, not a control boundary. |
| `--line-300` | `{line-strong}` | `{input}` | Control border (3:1 on bg-000, bg-100, bg-200): inputs, checkboxes, secondary buttons, crosshair marks. |
| `--chart-grid` | `{line}` | `{line-100}` | Chart gridlines. |
| `--chart-sky` | `{sky} / {sky-ink}` | `{fg-100}` | Chart series tinted sky: a step of the monochrome ramp (charts carry no decorative colour). |
| `--chart-mint` | `{mint} / {mint-ink}` | `color-mix(in oklab, {foreground} 38%, {card}) / color-mix(in oklab, {foreground} 48%, {card})` | Chart series tinted mint: a step of the monochrome ramp (charts carry no decorative colour). |
| `--chart-lilac` | `{lilac} / {lilac-ink}` | `{fg-300}` | Chart series tinted lilac: a step of the monochrome ramp (charts carry no decorative colour). |
| `--chart-butter` | `{butter} / {butter-ink}` | `{fg-200}` | Chart series tinted butter: a step of the monochrome ramp (charts carry no decorative colour). |
| `--chart-blush` | `{blush} / {blush-ink}` | `{line-300}` | Chart series tinted blush: a step of the monochrome ramp (charts carry no decorative colour). |
| `--ramp-1` | `color-mix(in oklab, {chart-1} 12%, {background})` | `color-mix(in oklab, {chart-1} 12%, {background})` | Map and heatmap ramp, step 1 of 5 (lightest): calm sequential colours for values such as price per m² or density, mixed from `chart-1` and the background. |
| `--ramp-2` | `color-mix(in oklab, {chart-1} 28%, {background})` | `color-mix(in oklab, {chart-1} 28%, {background})` | Map and heatmap ramp, step 2 of 5 (middle): calm sequential colours for values such as price per m² or density, mixed from `chart-1` and the background. |
| `--ramp-3` | `color-mix(in oklab, {chart-1} 46%, {background})` | `color-mix(in oklab, {chart-1} 46%, {background})` | Map and heatmap ramp, step 3 of 5 (middle): calm sequential colours for values such as price per m² or density, mixed from `chart-1` and the background. |
| `--ramp-4` | `color-mix(in oklab, {chart-1} 66%, {background})` | `color-mix(in oklab, {chart-1} 66%, {background})` | Map and heatmap ramp, step 4 of 5 (middle): calm sequential colours for values such as price per m² or density, mixed from `chart-1` and the background. |
| `--ramp-5` | `color-mix(in oklab, {chart-1} 88%, {background})` | `color-mix(in oklab, {chart-1} 88%, {background})` | Map and heatmap ramp, step 5 of 5 (strongest): calm sequential colours for values such as price per m² or density, mixed from `chart-1` and the background. |
| `--ok` | `#2f5d16 / #a8db86` | `#177447 / #5cc28f` | Success / done / healthy: text and status shapes (circle). On bg-000 to bg-300. |
| `--ok-bg` | `#d6efc3 / #24401a` | `rgba(23,116,71,0.09) / rgba(92,194,143,0.12)` | Tint behind ok badges, banners and diff additions. |
| `--info` | `#1f4f8a / #9cc6f7` | `#2856b0 / #7aa7f5` | Running / in progress / neutral notices. Shape: pulsing dot. |
| `--info-bg` | `#cfe3fb / #1e3550` | `rgba(40,86,176,0.08) / rgba(122,167,245,0.12)` | Tint behind info badges and banners. |
| `--warn` | `#6b4d00 / #f3d374` | `#765600 / #d9b44a` | Warning: budget at 80 %, expiring domains, degraded checks. Shape: triangle. |
| `--warn-bg` | `#fbe7aa / #4a3a10` | `rgba(118,86,0,0.09) / rgba(217,180,74,0.12)` | Tint behind warning badges and banners. |
| `--danger` | `{destructive}` | `{destructive}` | Error, failed run, destructive actions, budget stop. Shape: square. |
| `--danger-bg` | `#f8d6d2 / #4a2320` | `rgba(176,48,31,0.08) / rgba(239,111,97,0.12)` | Tint behind error badges, banners, diff removals. |
| `--signal` | `#6a2a82 / #dba6ee` | `#9a4807 / #f2994a` | Needs a human: approval waiting, beacons, the approval count. Shape: diamond. The only hue that may draw the eye unprompted. |
| `--signal-bg` | `#e9cdf4 / #3d2547` | `rgba(154,72,7,0.09) / rgba(242,153,74,0.14)` | Tint behind approval cards' header and signal badges. |
| `--idle` | `#5f5e5a / #a9a8a3` | `{fg-300}` | Status idle: ready, inactive (ring). Alias of `ink-muted`. |
| `--diff-add` | `#2f5d16 / #a8db86` | `{ok}` | Added lines in override diffs. |
| `--diff-add-bg` | `#d6efc3 / #24401a` | `{ok-bg}` | Fill of added lines. Alias of `mint`. |
| `--diff-del` | `#8a2b23 / #f2a8a0` | `{danger}` | Removed lines in override diffs. |
| `--diff-del-bg` | `#f8d6d2 / #4a2320` | `{danger-bg}` | Fill of removed lines. Alias of `blush`. |
| `--paper` | `#ffffff` | `#ffffff` | Document previews (invoices, PDFs): paper is white in both themes. |
| `--paper-ink` | `#141414` | `#111114` | Text on paper. |
| `--frame-hover` | `rgba(255, 255, 255, 0.08)` | `{bg-200}` | Hover fill on the dark frame (top bar, dock, code blocks). Same in both themes. |
| `--frame-active` | `rgba(255, 255, 255, 0.12)` | `{bg-300}` | Active or selected fill on the dark frame. Same in both themes. |
| `--frame-strong` | `rgba(255, 255, 255, 0.18)` | `{bg-300}` | Strong fill or divider on the dark frame. Same in both themes. |
| `--on-frame-strong` | `#ffffff` | `{fg-100}` | Highlighted text on the frame (log highlights). Same in both themes. |
| `--on-frame-warn` | `#f3d374` | `{warn}` | Warnings and numbers in logs and code on the frame. Same in both themes. |
| `--on-frame-signal` | `#d4b8f0` | `{signal}` | Keywords in code on the frame. Same in both themes. |
| `--ink-hover` | `rgba(0, 0, 0, 0.06)` | `{bg-200}` | Hover fill on tinted surfaces such as alerts. Same in both themes. |
| `--hairline` | `rgba(0, 0, 0, 0.12)` | `{line-200}` | Thin outline around swatches and colour wells. Same in both themes. |
| `--media-scrim` | `rgba(10, 10, 10, 0.6)` | `rgba(10, 10, 10, 0.6)` | Labels and counters on top of photos. Same in both themes. |
| `--media-ink` | `#ffffff` | `#ffffff` | Text and lines on top of photos. Same in both themes. |
| `--media-shadow` | `rgba(0, 0, 0, 0.3)` | `rgba(0, 0, 0, 0.3)` | Shadow behind lines drawn on photos. Same in both themes. |
| `--lightbox` | `rgba(8, 8, 8, 0.92)` | `rgba(8, 8, 8, 0.92)` | Full-screen image viewer background. Same in both themes. |
| `--lightbox-ink` | `rgba(255, 255, 255, 0.8)` | `rgba(255, 255, 255, 0.8)` | Captions in the image viewer. Same in both themes. |
| `--paper-muted` | `#706f6a` | `#706f6a` | Secondary text on paper (4.5:1 on white). |
| `--paper-subtle` | `#6b6a65` | `#6b6a65` | Small print on `paper`. Same in both themes. |
| `--serp-ink` | `#202124` | `#202124` | Search ad preview: text. Same in both themes. |
| `--serp-muted` | `#4d5156` | `#4d5156` | Search ad preview: description and URL. Same in both themes. |
| `--serp-link` | `#1a0dab` | `#1a0dab` | Search ad preview: headline link. Same in both themes. |
| `--serp-chip` | `#f1f3f4` | `#f1f3f4` | Search ad preview: favicon chip. Same in both themes. |

### Shadow

| Token | Halo | Pro | Use |
| --- | --- | --- | --- |
| `--shadow-card` | `0 1px 2px rgba(20,20,20,0.04), 0 6px 20px rgba(20,20,20,0.05) / 0 1px 2px rgba(0,0,0,0.4)` | `none` | Resting cards. Pro: none, hairlines divide. |
| `--shadow-lift` | `0 2px 4px rgba(20,20,20,0.06), 0 14px 32px rgba(20,20,20,0.10) / 0 2px 6px rgba(0,0,0,0.5), 0 14px 32px rgba(0,0,0,0.45)` | `none` | Hovered card. Pro: none. |
| `--shadow-float` | `0 16px 40px rgba(0,0,0,0.22) / 0 16px 40px rgba(0,0,0,0.6)` | `0 16px 40px rgba(17,17,20,0.12) / 0 16px 40px rgba(0,0,0,0.55)` | Floating layers: dock, toasts, menus and dialogs. |
| `--shadow-overlay` | `{shadow-float}` | `0 16px 40px rgba(17,17,20,0.12) / 0 16px 40px rgba(0,0,0,0.55)` | Only floating layers: menus, popovers, dialogs, toasts, command palette. Always paired with a line-200 border. |
| `--shadow-glass` | `0 1px 2px rgba(20, 20, 40, 0.06), 0 12px 40px rgba(20, 20, 40, 0.14) / 0 1px 2px rgba(0, 0, 0, 0.3), 0 16px 48px rgba(0, 0, 0, 0.45)` | `0 8px 24px rgba(17, 17, 20, 0.1) / 0 12px 32px rgba(0, 0, 0, 0.5)` | Shadow under glass surfaces. |

### Component knobs

| Token | Halo | Pro | Use |
| --- | --- | --- | --- |
| `--button-radius` | `{radius-pill}` | `{radius-1}` | Corners of buttons (Button, IconButton). One knob for a theme's button shape. |
| `--field-radius` | `{radius-pill}` | `{radius-1}` | Corners of inputs and selects. |
| `--badge-radius` | `{radius-pill}` | `{radius-1}` | Corners of badges and chips. |
| `--panel-bg` | `{surface}` | `{bg-100}` | Background of a panel: a cell of the hairline grid, a section, a side column. |
| `--panel-border` | `transparent` | `{line-200}` | Border colour of a panel standing on its own; transparent where panels float. |
| `--panel-radius` | `{radius-lg}` | `{radius-0}` | Corners of a panel. Pro: square cells of the hairline grid. |
| `--panel-shadow` | `{shadow-card}` | `none` | Resting shadow of a panel. Pro: none, the hairlines divide. |
| `--panel-pad` | `{space-6}` | `{space-4}` | Inner padding of a panel. |
| `--panel-gap` | `{space-4}` | `1px` | Gap between panels in a grid: the hairline in Pro, air between cards in Halo. |
| `--glass-filter` | `blur(24px) saturate(180%) brightness(1.05) / blur(24px) saturate(160%) brightness(0.85)` | `blur(16px) saturate(130%) brightness(1.04) / blur(16px) saturate(120%) brightness(0.8)` | backdrop-filter of glass surfaces: blur, colour lift and a nudge towards the theme's side. |
| `--glass-tint` | `62%` | `40%` | How strongly a tint (StatTile, tinted Card) colours the glass it sits on. |

### Spacing

| Token | Halo | Pro | Use |
| --- | --- | --- | --- |
| `--space-0-5` | `2px` | `2px` | Icon-to-badge nudges, hairline offsets. |
| `--space-1` | `4px` | `4px` | Gap inside badges and kbd groups. |
| `--space-2` | `8px` | `8px` | Gap between icon and label, between buttons in a group. |
| `--space-3` | `12px` | `12px` | Compact horizontal cell and control padding. |
| `--space-4` | `16px` | `16px` | Grid cell padding, comfortable control padding, page gutter on mobile. |
| `--space-5` | `20px` | `20px` | Dialog body padding. |
| `--space-6` | `24px` | `24px` | Cell padding on overview grids; background-grid pitch. |
| `--space-8` | `32px` | `32px` | Gap between stacked sections inside a panel. |
| `--space-10` | `40px` | `40px` | Outer margin of the app frame on large screens. |
| `--space-12` | `48px` | `48px` | Empty-state padding. |
| `--space-16` | `64px` | `64px` | Login and onboarding vertical rhythm. |

### Radius

| Token | Halo | Pro | Use |
| --- | --- | --- | --- |
| `--radius` | `16px` | `2px` | Theme: the base corner radius; Pro is square at 2px, larger values round cards and menus too (shadcn `radius`). |
| `--radius-sm` | `calc(var(--radius) * 0.625)` | `{radius-1}` | Inputs inside cells, row hovers, small tiles. |
| `--radius-md` | `var(--radius)` | `calc((var(--radius) - 2px) * 1)` | Stat cells, event cards, menus: square in Pro. |
| `--radius-lg` | `calc(var(--radius) * 1.375)` | `calc((var(--radius) - 2px) * 1.375)` | Cards and panels: square cells of the hairline grid. |
| `--radius-xl` | `calc(var(--radius) * 1.875)` | `calc((var(--radius) - 2px) * 1.875)` | The workspace sheet and app frame: square in Pro. |
| `--radius-pill` | `999px` | `{radius-1}` | Buttons, chips, badges, tabs and inputs: 2px in Pro. |
| `--radius-0` | `0px` | `0px` | Default for everything structural: cells, panels, tables, dialogs, sheets, cards. |
| `--radius-1` | `{radius-sm}` | `var(--radius)` | Controls: buttons, inputs, badges, kbd, switches, tooltips. |
| `--radius-full` | `9999px` | `9999px` | Only status dots and radio buttons. |

### Motion

| Token | Halo | Pro | Use |
| --- | --- | --- | --- |
| `--dur-fast` | `120ms` | `{duration-fast}` | Press, hover colour changes, chip toggles. |
| `--dur-base` | `220ms` | `{duration-base}` | Tab indicator slide, menu open, card lift. |
| `--dur-enter` | `520ms` | `{duration-base}` | Entrances: short and quiet in Pro. |
| `--dur-slow` | `900ms` | `{duration-base}` | Count-ups, chart draw-ins and progress fills: short in Pro. |
| `--stagger-step` | `55ms` | `0ms` | No staggered entrances in Pro. |
| `--dur-exit` | `160ms` | `{duration-fast}` | Overlays leaving: menus, popovers, dialogs, drawers, toasts. |
| `--motion-time` | `1` | `1` | Multiplier for choreography delays (when the dock, side panels and chart data come in). |
| `--motion-travel` | `1` | `1` | Multiplier for how far things travel when they come in. |
| `--motion-blur` | `0px` | `0px` | Blur things come out of as they rise (expressive Halo only). |
| `--ease-out` | `cubic-bezier(0.22, 1, 0.36, 1)` | `{ease-standard}` | Entrances. |
| `--ease-spring` | `cubic-bezier(0.34, 1.56, 0.64, 1)` | `{ease-standard}` | No overshoot in Pro: the standard curve. |
| `--ease-in-out` | `cubic-bezier(0.65, 0, 0.35, 1)` | `{ease-standard}` | Things moving between two resting places. |
| `--duration-fast` | `{dur-fast}` | `90ms` | Hover and press feedback. |
| `--duration-base` | `{dur-base}` | `140ms` | Menus, popovers, sheets, toasts entering. |
| `--ease-standard` | `{ease-out}` | `cubic-bezier(0.2, 0, 0, 1)` | The only easing curve. |

### Sizes

| Token | Halo | Pro | Use |
| --- | --- | --- | --- |
| `--control-sm` | `32px` | `24px` | Small buttons in dense toolbars. |
| `--control-md` | `40px` | `{control-dense}` | Default control height (follows density in components). |
| `--control-lg` | `48px` | `{control-comfy}` | Large controls. |
| `--row-dense` | `40px` | `28px` | Row height for tables, lists and nav items in compact density. |
| `--row-comfy` | `52px` | `36px` | Row height in comfortable density. |
| `--control-dense` | `{control-sm}` | `28px` | Button and input height in compact density. |
| `--control-comfy` | `{control-md}` | `34px` | Button and input height in comfortable density. |
| `--topbar-h` | `60px` | `44px` | Top bar height. |
| `--sidebar-w` | `44px` | `232px` | Sidebar width, expanded. |
| `--sidebar-w-collapsed` | `44px` | `52px` | Sidebar width, icon-only. |
| `--subnav-w` | `208px` | `{sidebar-w}` | SubNav width. |
| `--side-panel-w` | `304px` | `320px` | Side panel width. |
| `--icon-sm` | `14px` | `14px` | Icons inside badges and dense table cells. |
| `--icon-md` | `16px` | `16px` | Default Lucide icon size. |
| `--icon-lg` | `20px` | `16px` | Icons in navigation: same as icon-md in Pro. |
| `--line-width` | `1px` | `1px` | Every border and grid line (Pro calls it hairline). |



## Theme builder

> Build a shadcn-style theme for Halo live on real components: presets, brand colours, radius and imported shadcn themes, with the CSS to copy.

Pick a preset, change any colour or paste a theme from ui.shadcn.com/themes or tweakcn; the preview uses the real components of the kit. Light and dark are edited separately: switch the theme in the header. "Apply to the whole site" lets you browse every component page in your theme (in this tab only).

### Use the result

Save the CSS as `theme.css` and import it once, after the kit's styles, or let the CLI write and import it:

```sh
npx @twentyfirstmedia/ui theme ./theme.css
npx @twentyfirstmedia/ui theme violet
```

In React you can also pass a theme at runtime: `<UIProvider tokens={theme}>`. See [Theming and tokens](https://ui.twentyfirst.media/halo/theming/) for every variable.


## Motion

> Choreographed page entrances, data that draws itself, layers that animate in and out, page transitions and reveal on scroll, with one switch: off, standard or expressive.

Both kits move with purpose: the shell settles in, cards rise one after another, charts draw and numbers count up once their card is there, and menus, dialogs, drawers and toasts animate in and out. One switch sets how much:

| Level | Halo | Pro |
| --- | --- | --- |
| `standard` (default) | Soft and springy: 520ms entrances, 55ms between cards | Quick and quiet: 140ms, no stagger, no springs |
| `expressive` | Orchestrated: 760ms entrances, 90ms between cards, more travel, a short focus-in blur | Crisp: 360ms entrances, 45ms between cards, sharp easing, no blur or springs |
| `off` | Nothing moves; values and layers appear at once | The same |

```tsx
import { UIProvider } from "@twentyfirstmedia/halo";

<UIProvider motion="expressive">{children}</UIProvider>;
// a setting in your app
<UIProvider motion={settings.reduceMotion ? "off" : "standard"}>{children}</UIProvider>;
```

The level is an attribute, so it works without React too: `data-motion="expressive"` on `<html>` or any subtree. The reader's reduced-motion setting always wins and turns motion off, whatever the app sets.

### The choreography

- **Shell**: the top bar drops in, side panels slide in, the dock springs up and its buttons pop in turn.
- **Content**: wrap a page's sections in `Stagger` and they rise one after another. Below the fold a `Stagger` waits until it scrolls into view (`reveal={false}` plays at once).
- **Data**: bars grow, lines draw, areas and dots fade in, gauges and progress bars fill and `CountUp` counts, each waiting for the card it sits in. New values count from the old one.
- **Layers**: popovers, menus, tooltips, hover cards, comboboxes, dialogs, drawers, the command palette and toasts animate out as well as in. `Modal`, `Drawer` and `CommandPalette` take an optional `open` prop for that; without it, render them only while open, as before.

```tsx
<Stagger className="tf-grid" style={{ "--cols": "repeat(3, minmax(0, 1fr))" } as CSSProperties}>
  <StatTile value="1,284" label="Orders" />
  <Panel title="Revenue">
    <LineChart labels={days} series={series} />
  </Panel>
  …
</Stagger>
<Drawer open={open} title="Order 1042" onClose={() => setOpen(false)}>…</Drawer>
```

### Page transitions

`startViewTransition(update)` runs a route change or a big update as a view transition: the old page fades out and the new one rises in, in the kit's motion. Browsers without view transitions, and motion `off`, get a plain update.

```tsx
import { startViewTransition } from "@twentyfirstmedia/halo";

startViewTransition(() => router.push("/orders"));
```

The kits style `::view-transition-old(root)` and `::view-transition-new(root)`, so transitions started another way (Next.js `experimental.viewTransition` with React's `<ViewTransition>`, Astro, plain `document.startViewTransition`) look the same.

### Your own animations

- `useMotion()` returns the level in effect (`"off"` while the reader asks for reduced motion).
- `usePresence(open)` keeps your own layer mounted while it animates out: render while `mounted`, spread `leaving(closing)` on its root (sets `data-closing` and `inert`).
- The motion tokens drive everything: `--dur-fast`, `--dur-base`, `--dur-enter`, `--dur-slow`, `--dur-exit`, `--stagger-step`, `--ease-out`, `--ease-spring`, `--motion-time` (delays), `--motion-travel` (distances) and `--motion-blur`. Set them like any other token for a motion style of your own.

Only `transform`, `opacity` and the short expressive blur animate; layout never moves under the reader.


## Icons

> 93 icons built into every component, plus a library of about 700 in the same style: passkeys and security, AI, social and brand logos, files, media, commerce, maps and 3D, games and more. Search them below and click one to copy its name.

Every icon is a line drawing on a 24px grid with 2px round-capped strokes in `currentColor`, so it takes the colour and size of the text around it, in both kits. Brand logos (`brand…`) are filled.

```tsx
import { Button, Icon, IconButton } from "@twentyfirstmedia/halo";

<Icon name="truck" size={16} />
<Button icon="plus">Add</Button>
<IconButton icon="trash" label="Delete" />
```

### Built in and library

- **Built in** (93): the icons the components use themselves. They work by name everywhere, with nothing to set up.
- **Library** (about 700): everything else, from `@twentyfirstmedia/halo/icons`. Register what you use once, before rendering, and the names work like the built-in ones in `Icon` and every `icon` prop. Only the icons you register end up in your bundle.

```tsx
// app/icons.ts: import it from your root layout and from your client provider
import { registerIcons } from "@twentyfirstmedia/halo";
import { fingerprint, scanFace, brandGithub } from "@twentyfirstmedia/halo/icons";

registerIcons({ fingerprint, scanFace, brandGithub });
```

`registerIcons(ICON_LIBRARY)` registers all of them (about 60 KB gzip), handy for prototypes and admin tools. The custom elements of `@twentyfirstmedia/elements` have the whole library registered, so `<tf-button icon="fingerprint">` works in plain HTML.

A name nobody registered draws a placeholder and logs a warning once, naming the import to add.

### Passkeys and sign-in

`fingerprint` and `scanFace` for passkeys and biometrics, `keyRound` and `lock` for passwords and keys, `shieldCheck` for verified states, `smartphoneNfc` for security keys and phones, `qrCode` for sign-in on another device.

```tsx
<Button icon="fingerprint" variant="primary">Sign in with a passkey</Button>
```

### Social and brand logos

Brand logos are filled and sized to sit next to the line icons: `brandX`, `brandInstagram`, `brandFacebook`, `brandThreads`, `brandYoutube`, `brandTiktok`, `brandWhatsapp`, `brandTelegram`, `brandDiscord`, `brandBluesky`, `brandMastodon`, `brandGithub` and more (see Brands below). Give logo-only links a label, e.g. `<IconButton icon="brandGithub" label="GitHub" asChild><a href="…" /></IconButton>`.

For AI products there are `brandOpenai`, `brandAnthropic`, `brandClaude`, `brandGooglegemini`, `brandMistralai`, `brandPerplexity`, `brandDeepseek`, `brandOllama`, `brandHuggingface`, `brandModelcontextprotocol` and more; for business `brandLinkedin`, `brandXing`, `brandMicrosoft`, `brandSlack`, `brandMeta`, `brandGoogleads` and `brandGoogleanalytics`.

Logos are trademarks of their owners; use them to link to the brand's own page and follow its guidelines. A logo that is missing (Microsoft Teams, for one) or your own product's logo: register the official file yourself (below).

### Your own icons

Register any drawing on the 24px grid: a path string is stroked like the kit's icons, `{ d, filled: true }` is filled. To type the names, extend `CustomIcons`:

```tsx
import { registerIcons } from "@twentyfirstmedia/halo";

registerIcons({ acme: "M4 18l8-12 8 12z", acmeLogo: { d: "M…", filled: true } });

declare module "@twentyfirstmedia/ui-core" {
  interface CustomIcons {
    acme: true;
    acmeLogo: true;
  }
}
```

The built-in names cannot be replaced, so components always look as designed.

### Licences

Line icons in the library come from [Lucide](https://lucide.dev) (ISC licence), brand logos from [Simple Icons](https://simpleicons.org) (CC0) and, for LinkedIn, Microsoft, Windows, Slack, Skype, Amazon and OpenAI, from [Font Awesome Free](https://fontawesome.com) (CC BY 4.0, attribution: Font Awesome Free by Fonticons, Inc.). All are fitted to the kit's grid; the notices ship in `ICONS-LICENSE` of `@twentyfirstmedia/ui-core`.


## Text and locale

> Built-in text is English by default; replace any of it with UIProvider messages, and format numbers, money and dates for any locale with UIProvider locale.

The kits ship plain English and no translations. Every text a component shows on its own (accessible names, button texts, placeholders, status words, validation messages) can be replaced, and numbers, money, percentages and dates follow a locale you set. Props such as `title`, `label` or `placeholder` on a component still win over both.

```tsx
import { UIProvider } from "@twentyfirstmedia/halo";

<UIProvider
  locale="de-DE"
  messages={{
    close: "Schließen",
    send: "Senden",
    composerHint: "Enter zum Senden · Shift+Enter für eine neue Zeile",
    selectedCount: (n, formatted) => `${formatted ?? n} ausgewählt`,
    agentStatus: { Running: "Läuft", Idle: "Bereit" },
  }}
>
  {children}
</UIProvider>;
```

### Messages

- `messages` is partial: what you leave out stays English. Nested providers merge on top of the outer one, so a section of the app can change a few strings.
- Strings with a value in them are functions (`` removeItem: (name) => `${name} entfernen` ``), so the word order is yours. A few take React nodes where the value is highlighted (`typeToConfirm`, `freeShippingIn`).
- Status words (`agentStatus`, `orderStatus`, `reviewState`, `riskFamily`, `flowStep`) are groups keyed by the status value, which stays English in your data. Groups merge one level deep.
- `DEFAULT_STRINGS` holds every key with its English text; the `UIStrings` type documents each one. Type your own set as `UIMessages` to get completion and checks.
- `useUIStrings()` returns the strings that apply where it is called, for your own components.
- Server components (`StatusScreen`, `AuthCard`) cannot read the provider; their texts are props.

Set `lang` on `<html>` (or the element around a translated part) yourself, so screen readers pronounce the text in the right language.

### Locale

`locale` is a BCP 47 tag (default `en-US`). It applies to every number, amount, percentage and date a component formats, to calendar month and weekday names, and to `CountUp` and `StatTile`, which read string values in that locale: in `de-DE`, `"13,05 €/m²"` counts up to 13.05 and keeps its unit.

The helpers take the locale as their last argument, and `useFormat()` returns them bound to the provider's locale:

```tsx
import { formatMoney, useFormat } from "@twentyfirstmedia/halo";

formatMoney(1290, "EUR", undefined, "de-DE"); // "1.290 €"

function Price({ value }: { value: number }) {
  const { formatMoney } = useFormat();
  return <b>{formatMoney(value)}</b>;
}
```

Money defaults to euros; pass a currency per call. Calendars start on Monday.


## AI agents and MCP

> Give Claude Code, Cursor, VS Code and other coding agents the complete kit docs, so they build with real components instead of guessing.

The kits are newer than most models' training data, and the exact props matter. Two things fix that: an MCP server that answers from the docs of the exact version you installed, and plain Markdown for every page of this site.

### MCP server

The CLI includes an MCP server (stdio, no network access, the docs are bundled). One command sets it up for the clients you use and adds the kit rules to `AGENTS.md`:

```sh
npx @twentyfirstmedia/ui mcp init --kit halo
```

It writes `.mcp.json` (Claude Code), `.cursor/mcp.json` (Cursor) and `.vscode/mcp.json` (VS Code). Pick clients with `--client claude,cursor,vscode` and skip the rules with `--no-rules`.

Or add it by hand. Claude Code:

```sh
claude mcp add twentyfirst-ui -- npx -y @twentyfirstmedia/ui mcp --kit halo
```

Cursor (`.cursor/mcp.json`), Windsurf and Claude Desktop use the same shape:

```json
{
  "mcpServers": {
    "twentyfirst-ui": {
      "command": "npx",
      "args": ["-y", "@twentyfirstmedia/ui", "mcp", "--kit", "halo"]
    }
  }
}
```

VS Code (`.vscode/mcp.json`):

```json
{
  "servers": {
    "twentyfirst-ui": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@twentyfirstmedia/ui", "mcp", "--kit", "halo"]
    }
  }
}
```

Codex (`~/.codex/config.toml`):

```toml
[mcp_servers.twentyfirst-ui]
command = "npx"
args = ["-y", "@twentyfirstmedia/ui", "mcp", "--kit", "halo"]
```

#### Tools

| Tool | What it returns |
| --- | --- |
| `search_docs` | Components, patterns, guides, tokens and icons that match a query |
| `list_components` | Every component page by group with a one-line summary |
| `get_component` | Description, import line, example code and props of a component |
| `get_pattern` | A complete screen built from kit parts, with its code |
| `get_guide` | Installation, CLI, theming, status and approvals, this page |
| `get_tokens` | Token names with Halo and Pro values, by group |
| `list_icons` | Every valid icon name |
| `check_usage` | Checks code: unknown components, props and icons, missing required props, colour literals |

Every page is also a resource (`twentyfirst-ui://components/ApprovalCard`, `twentyfirst-ui://guides/theming`), and the prompts `build_screen` and `review_ui` start the two most common jobs.

### Rules for agents

`mcp init` adds these to `AGENTS.md` (and `CLAUDE.md` when it exists); you can copy them by hand:

```md
- Build UI from Twentyfirst UI components first; import them from `@twentyfirstmedia/halo`. Check names, props and examples with the `twentyfirst-ui` MCP server (`get_component`, `search_docs`) instead of guessing.
- Halo and Pro have the same components, props and markup. Never branch on the kit in code; switch looks with `data-kit` or `<UIProvider kit>`.
- No colour literals or arbitrary Tailwind values: use the shadcn-style theme variables (`var(--primary)`, `bg-card`, `text-muted-foreground`, `border-border`) so both kits, light and dark, and the app's theme keep working.
- Wrap the app once in `UIProvider` and import the kit's `styles.css` once (or `@twentyfirstmedia/ui-core/themes.css` for both kits).
- Format numbers, money, percentages and dates with `formatNumber`, `formatMoney`, `formatPercent`, `formatDate`.
- Icons: only names from `list_icons`; icon-only buttons need a `label`.
- Before finishing, run `check_usage` from the MCP server on new code.
```

### Markdown and llms.txt

- [/llms.txt](https://ui.twentyfirst.media/llms.txt): what the kits are, the rules, and a link to every page.
- [/llms-full.txt](https://ui.twentyfirst.media/llms-full.txt): every guide and component page in one file.
- Every page has a Markdown twin: append `.md` to its path, e.g. [/halo/components/ApprovalCard.md](https://ui.twentyfirst.media/halo/components/ApprovalCard.md). The "Markdown" button at the top of each page copies it.


## Plain HTML and other frameworks

> Every component as a custom element (<tf-button>, <tf-data-table> …) for plain HTML, Vue, Svelte, Angular, Astro and server templates. No React setup needed.

`@twentyfirstmedia/elements` turns every component into a custom element with the same props: `Button` is `<tf-button>`, `DataTable` is `<tf-data-table>`, `UIProvider` is `<tf-provider>`. React is bundled inside, so the page needs no build step and no React tooling. The elements use no shadow DOM: the Halo stylesheet styles them like everywhere else.

### From a CDN

Load the Halo CSS and the elements, then write HTML:

```html
<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/@twentyfirstmedia/halo/dist/styles.css">
<script type="module" src="https://cdn.jsdelivr.net/npm/@twentyfirstmedia/elements/dist/elements.js"></script>

<tf-panel title="Revenue" subtitle="Last 7 days">
  <tf-button slot="action" variant="ghost" size="sm">Export</tf-button>
  <tf-bar-chart label="Revenue per day"
    data='[{"label":"Mon","value":32},{"label":"Tue","value":48},{"label":"Wed","value":41}]'>
  </tf-bar-chart>
</tf-panel>
```

unpkg works the same way (`https://unpkg.com/@twentyfirstmedia/elements/dist/elements.js`). For a classic `<script>` without `type="module"` use `dist/elements.global.js`; it exposes `window.TwentyfirstElements` with `toast` and the `Intl` formatters. Pin a version in production, for example `@twentyfirstmedia/elements@0.1`.

Self-host when you can: the CDN is the only external request. The components themselves never load anything, and the fonts come with the stylesheet.

### From npm

```sh
npm install @twentyfirstmedia/elements @twentyfirstmedia/halo
```

```js
import "@twentyfirstmedia/halo/styles.css";
import { toast } from "@twentyfirstmedia/elements"; // defines every tf-* element
```

The `@twentyfirstmedia/halo` package is only needed for its stylesheet; the elements bring their own copy of the components and React.

### Attributes, properties, events and slots

| Component API | As an element |
| --- | --- |
| `variant="ghost"`, `size="sm"` | the same attribute |
| `defaultValue`, `iconRight` | kebab-case: `default-value`, `icon-right` |
| `disabled`, `selectable` (boolean) | present means true, absent means unset, `"false"` means false |
| `max={8}` (number) | `max="8"` |
| `items`, `columns`, `rows` (arrays, objects) | a property, `el.items = [...]`, or JSON in the attribute: `items='["Day","Week"]'`; lists of strings also take `items="Day, Week"` |
| `format`, `renderExpanded`, `onVerify` (functions) | properties only: `el.format = (v) => ...` |
| `onChange`, `onDecide`, `onClose` | DOM events `change`, `decide`, `close` (the name without `on`, lowercase) |
| `children` | the element's content: text, HTML and other tf-* elements |
| `action`, `trace`, `corner` (ReactNode props) | children with `slot="action"`; a DOM node set as a property works too |
| `actions` (a list of nodes) | every child with `slot="actions"` is one item |
| `panels` on Tabs (a record of nodes) | children with `slot="panels:Overview"` |
| `className`, `style` | the `class` and `style` attributes |

Events bubble, are composed and can be cancelled. `event.detail` holds the callback's argument, or an array when the callback takes several (`decide` gives `[key, text]`). Where a component would pass a React change event, the detail is the control's value (`checked` for switches and checkboxes).

```js
const tabs = document.querySelector("tf-tabs");
tabs.addEventListener("change", (e) => console.log("now on", e.detail));

const card = document.querySelector("tf-approval-card");
card.addEventListener("decide", (e) => {
  const [key, text] = e.detail;
  card.decision = { key, by: "Mara", at: "09:41", text };
});
```

A few rules make plain HTML pleasant:

- **Uncontrolled by default.** Without `value` or `checked`, Tabs, Segmented, Switch and friends keep their own state. Set the attribute to control them: the element then follows the user's input like a native control, unless a listener calls `event.preventDefault()`.
- **Optional callbacks follow listeners.** Some components only show a part when the callback is set, such as the dismiss button of `<tf-alert>`. The element passes those callbacks while something listens for the event on the element or a tf-* element around it.
- **Closing hides the element.** Modal, Drawer, CommandPalette and Alert set the `hidden` attribute after `close` (or `dismiss`) unless the event is cancelled. Remove `hidden` to show them again. `<tf-modal>` opens as a dialog over the page: focus moves in and stays there, Escape and the backdrop close it, and focus returns to where it was.
- **Menus close their popover.** A `<tf-menu>` inside `<tf-popover>` closes it when an item runs or on Escape.
- **Nested elements share context.** A tf-* element inside another one renders in its parent's React tree, so `<tf-text-field name="email">` inside `<tf-form>` shows the form's validation message.
- **Layout is unchanged.** Each element is `display: contents`; the component's root is the flex or grid item. The `id` attribute stays on the element, and `title`, `role` and `lang` move into the component.

Content is read when the element first renders; children added later with `append` are picked up as well. Content that is not shown at the moment (a closed popover, a hidden modal) stays in the document, inside the element, so `getElementById` keeps working.

### Toasts and helpers

```html
<tf-toaster></tf-toaster>
<script type="module">
  import { toast, formatMoney } from "https://cdn.jsdelivr.net/npm/@twentyfirstmedia/elements/dist/elements.js";
  toast({ text: `Paid ${formatMoney(1290)}`, tone: "success" });
</script>
```

### Kit switching and theming

With one kit's `styles.css` no attribute is needed. To switch between Halo and Pro at runtime, load `@twentyfirstmedia/ui-core/dist/themes.css` (both kits) and set `data-kit` on `<html>`. Theme and density work the same way in both setups:

```html
<html data-kit="halo" data-theme="system">
<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/@twentyfirstmedia/ui-core/dist/themes.css">

<script type="module">
  document.documentElement.dataset.kit = "pro";
  document.documentElement.dataset.theme = "dark";
</script>
```

`<tf-provider kit="halo" theme="dark" density="compact">` does the same declaratively; with `scope="subtree"` it applies to its content only. Every colour, radius, shadow and spacing is a CSS variable, so your own CSS can retheme the kit (see [Theming and tokens](https://ui.twentyfirst.media/halo/theming/)):

```css
:root {
  --primary: var(--lilac-ink);
  --radius-lg: 12px;
}
```

### Vue

Tell the compiler that `tf-*` tags are custom elements. Vue binds arrays and objects as properties and listens with `@`:

```js
// vite.config.js
import vue from "@vitejs/plugin-vue";
export default {
  plugins: [vue({ template: { compilerOptions: { isCustomElement: (tag) => tag.startsWith("tf-") } } })],
};
```

```html
<script setup>
import "@twentyfirstmedia/elements";
import { ref } from "vue";
const tab = ref("Overview");
</script>

<template>
  <tf-tabs :items="['Overview', 'Activity']" :value="tab" @change="tab = $event.detail" />
</template>
```

### Svelte

```html
<script>
  import "@twentyfirstmedia/elements";
  let checked = $state(false);
</script>

<tf-switch checked={checked} onchange={(e) => (checked = e.detail)}>Email me updates</tf-switch>
<tf-data-table columns={columns} rows={rows} selectable></tf-data-table>
```

### Angular

Allow custom elements in the component and bind properties with `[ ]` and events with `( )`:

```ts
import { Component, CUSTOM_ELEMENTS_SCHEMA } from "@angular/core";
import "@twentyfirstmedia/elements";

@Component({
  selector: "app-team",
  schemas: [CUSTOM_ELEMENTS_SCHEMA],
  template: `
    <tf-tabs [items]="tabs" (change)="onTab($event)"></tf-tabs>
    <tf-data-table [columns]="columns" [rows]="rows" selectable></tf-data-table>
  `,
})
export class TeamComponent {
  tabs = ["Members", "Invites"];
  tab = "Members";
  columns = [{ key: "name", label: "Name" }];
  rows = [{ id: 1, name: "Ava Vogel" }];
  onTab(e: Event) {
    this.tab = (e as CustomEvent<string>).detail;
  }
}
```

### Astro, Rails, Django and other server templates

Render the tags on the server and load the elements once in the layout. Pass data as JSON in attributes:

```html
---
// Astro
const items = ["Overview", "Activity"];
---
<tf-tabs items={JSON.stringify(items)}></tf-tabs>
<script>
  import "@twentyfirstmedia/elements";
</script>
```

```html
<!-- Django: escape the JSON for the attribute -->
<tf-bar-chart label="Signups" data="{{ signups_json }}"></tf-bar-chart>
```

### Static markup with the kit classes

For markup that needs no behaviour, the kit classes work without any script: the stylesheet alone is enough.

```html
<section class="tf-panel">
  <div class="tf-row">
    <button class="tf-btn tf-btn-primary" type="button">Save</button>
    <button class="tf-btn tf-btn-ghost" type="button">Cancel</button>
    <span class="tf-badge tf-badge-success"><span class="tf-badge-dot"></span>Live</span>
  </div>
</section>
```

Interactive components (tabs, menus, dialogs, tables) need the elements for their keyboard paths and ARIA.

For UI over a map, a video or photos, `class="tf-glass"` turns a surface into glass, and `data-surface="glass"` on a container turns everything floating inside into glass (see [Glass](https://ui.twentyfirst.media/halo/theming/#glass)):

```html
<div data-surface="glass" style="position: relative">
  <canvas id="map"></canvas>
  <section class="tf-panel" style="position: absolute; top: 16px; left: 16px">Layers</section>
</div>
```

### Editor support and types

The package ships a Custom Elements Manifest (`custom-elements.json`) for autocompletion of tags, attributes, events and slots, and VS Code HTML data:

```json
{ "html.customData": ["./node_modules/@twentyfirstmedia/elements/dist/vscode.html-custom-data.json"] }
```

In TypeScript, `document.querySelector("tf-data-table")` is typed with every property of `DataTable`.


## Status and approvals

> One state model and one way to ask a human, in both kits.

State is shape plus colour, so it reads without colour vision: **ok** = dot, **running** = pulsing dot, **signal** = diamond (waits for a human), **warn** = triangle, **danger** = square, **idle** = ring. One status word always maps to the same tone on every page. Only `signal` may draw attention unasked; warnings and errors never animate.

Everything an agent may not do alone goes through `ApprovalCard` with four answers in this order: **A** yes, as shown · **B** yes, with a change · **C** no, discard · **D** different instruction. The card shows the risk family, agent and project, age and escalation time, and the exact payload that will run. A–D work as keys. Once decided it collapses to one line with letter, person and time. `ApprovalInbox` lists open approvals oldest first; J and K move.

See [StatusIndicator](https://ui.twentyfirst.media/halo/components/StatusIndicator/), [ApprovalCard](https://ui.twentyfirst.media/halo/components/ApprovalCard/) and [ApprovalInbox](https://ui.twentyfirst.media/halo/components/ApprovalInbox/) for the props.


## Changelog

> What changed in each release of the Halo and Pro kits, the shared core, the CLI and the custom elements. All five packages are versioned together.

### 0.6.0

#### Minor Changes

- [#42](https://github.com/twentyfirstmedia/ui/pull/42) [`caae958`](https://github.com/twentyfirstmedia/ui/commit/caae958f805737b53dfd465140be42877e3349db) Thanks [@robintrepte](https://github.com/robintrepte)! - Forms, media, maps and fonts.
  
  - `TextField`: `type="password"` gets a show/hide button (`reveal={false}` turns it off), an interactive `action` slot that stays next to error marks, `onKeyDown`.
  - `Checkbox`: a 24px hit area around the same box (WCAG 2.2 target size).
  - `SearchField`: forwards `id`, `name`, `defaultValue`, `onKeyDown`, `onFocus`, `onBlur`, `autoFocus` and `inputProps` (combobox ARIA); `bindShortcut` focuses it with ⌘/Ctrl + the hint's key; the hint is hidden on touch screens.
  - `FileDrop`: `disabled`, `name` (the listed files take part in a form), `onFiles` can return `false` or the files to list.
  - `OtpInput`: empties its cells when `error` turns on (`clearOnError`), `ref.current.reset()`.
  - New `QrCode` (encoded on the device, no service); `TwoFactorSetup` draws it from `qrValue` and offers `trustDevice`.
  - `TilePicker layout="list"`.
  - `CookieConsent`: `equalChoice`, `id`, `aria-describedby` on its text, category texts may hold links.
  - `Gallery`: controlled `index`/`onIndexChange`, `label`, arrow keys on the stage and the thumbnails, focus moves into the lightbox and back.
  - `BeforeAfter`: the page scrolls vertically over it on touch screens, drags end on pointer cancel.
  - `CountUp`: renders its final value on the server and counts up on the client; `animate={false}`.
  - `PlanCard`: `price` takes any node, `pricePrefix`, `priceNote`, `href`/`linkAs` for the action, a "Current plan" badge.
  - `FloatingLayout`: `controls` and `attribution` in the free corner, `startWidth`/`endWidth`, `--floating-safe-*` variables with the space its slots take, the `end` slot as a bottom sheet below 720px (`endSheet`).
  - Tokens `ramp-1`…`ramp-5` in both kits: a calm sequential ramp for maps and heatmaps.
  - Static WOFF fonts under `fonts/og/` for share images (`next/og`) and PDF tools.

- [#42](https://github.com/twentyfirstmedia/ui/pull/42) [`caae958`](https://github.com/twentyfirstmedia/ui/commit/caae958f805737b53dfd465140be42877e3349db) Thanks [@robintrepte](https://github.com/robintrepte)! - Fluid layouts and root props.
  
  - Every component now puts `className` and `style` on its root element (about 160 ignored one or both); a test renders every reference preview and checks it.
  - Nothing pushes past its container: segmented controls, tabs and toggle groups shrink with ellipsis labels (`ToggleGroup block` is new); `MobileTabBar` shares its width evenly; the `TopBar` nav switches to icons as soon as its labels no longer fit, the account button cuts name and address with an ellipsis (the full text in `title`) and the search field shrinks; `CheckoutSteps` stay on one row and show numbers only when narrow (`compact` forces it); an `Alert`'s actions move under the text when narrow; chat source chips grow to two lines and take a `detail` tooltip; `RangeSlider` fields fit narrow columns.
  - `TopBar` and `AppShell` take a node as `brand` (a logo mark with the name).
  - `SideRail`: `expanded`/`defaultExpanded`/`onExpandedChange` show names next to the icons, `toggle` adds the button, every button has a real tooltip while collapsed.
  - `Breadcrumb` (and `PageHeader crumbs`): items with `href` (with `linkAs`) or `onClick`, `onNavigate`, `label`; plain labels are no longer fake `#` links; 24px targets.
  - `Pagination`: link mode (`href` per page, `linkAs`), `label`, previous/next disabled at the ends.
  - `ListRow`: `href`/`linkAs`, `actions` outside the clickable area (no nested buttons), a non-interactive row without `onClick`/`href`, `titleLines`/`subtitleLines`.
  - `SelectMenu size="sm"`; `Table stack` shows rows as labelled cards when the table is narrow.

- [#41](https://github.com/twentyfirstmedia/ui/pull/41) [`ce11edd`](https://github.com/twentyfirstmedia/ui/commit/ce11eddd4524ce9998b1f03453a58f6b7a684131) Thanks [@robintrepte](https://github.com/robintrepte)! - Sidebar overhaul and an app shell with a sidebar.
  
  - `Sidebar`: `variant` (`floating`, `attached`, `shell`); links with `href`, `linkAs` and `external`; `badge` (`"dot"` or a word), `disabled`, item `actions` ("…" menu); collapsible groups with an `action`; tooltips and flyouts when collapsed; `storageKey` and `shortcut` (⌘B / Ctrl+B); an off-canvas drawer on phones (`mobileOpen`, `onMobileOpenChange`); `header`/`footer` as a function of `{ collapsed }`.
  - Fixed: more room between a group heading and a selected first item; counts no longer jump to the corner in narrow shells.
  - Filters: `as="aside"` makes the sidebar a complementary region; items with `checked` are checkbox options (radios in a group with `select: "single"`), a group's `content` holds any control, `collapsible` turns the icons-only mode off.
  - New `UserMenu`; `WorkspaceSwitcher` takes `compact`.
  - `AppShell navigation="sidebar"` with `sidebarGroups`, `workspaces`, `userMenu` and `sidebar`.

### 0.5.0

#### Minor Changes

- [#39](https://github.com/twentyfirstmedia/ui/pull/39) [`90fd777`](https://github.com/twentyfirstmedia/ui/commit/90fd7770132dfb102b7bd4e7f7d3cb7f884e573c) Thanks [@robintrepte](https://github.com/robintrepte)! - The icon library grows to 690 icons.
  
  - Everything product apps on the kit use, among them `panelLeftClose`, `circleCheckBig`, `messageSquarePlus`, `replyAll`, `forward`, `lifeBuoy`, `gavel`, `octagonX`, `arrowDownUp` and `grid3x3`.
  - New categories Games (`swords`, `castle`, `pickaxe`, `dices`, `skull`, chess pieces …) and Maps and 3D (`draftingCompass`, `satellite`, `rotate3d`, `axis3d`, `lasso`, `spline` …); more AI icons (`brainCog`, `circuitBoard`, `scanText`, `textSearch`, `orbit`, `infinity` …).
  - More brand logos: AI (`brandOpenai`, `brandGooglegemini`, `brandMistralai`, `brandPerplexity`, `brandDeepseek`, `brandOllama`, `brandCursor`, `brandGithubcopilot`, `brandModelcontextprotocol` …), business and marketing (`brandLinkedin`, `brandMicrosoft`, `brandSlack`, `brandMeta`, `brandGoogleads`, `brandGoogleanalytics`, `brandTrustpilot`), shops, infrastructure and automation (`brandWoocommerce`, `brandShopify`, `brandWordpress`, `brandCloudflare`, `brandHetzner`, `brandSupabase`, `brandN8n`, `brandZapier` …) and payments and crypto (`brandRevolut`, `brandCoinbase`, `brandBinance`, `brandBitcoin`, `brandEthereum`).
  - LinkedIn, Microsoft, Windows, Slack, Skype, Amazon and OpenAI come from Font Awesome Free (CC BY 4.0); the attribution is in `ICONS-LICENSE`.

### 0.4.0

#### Minor Changes

- [#37](https://github.com/twentyfirstmedia/ui/pull/37) [`c40834a`](https://github.com/twentyfirstmedia/ui/commit/c40834aa1da2300846808e8ce2f42d3a9e12bda6) Thanks [@robintrepte](https://github.com/robintrepte)! - An icon library: 567 more icons in the kit's style, from passkeys and security to social and brand logos, files, media, commerce, places, home and health.
  
  - `@twentyfirstmedia/halo/icons` (and `/pro/icons`, `@twentyfirstmedia/ui-core/icons`) exports each icon by name: `fingerprint`, `scanFace`, `keyRound`, `shieldCheck`, `brandX`, `brandInstagram`, `brandGithub` … Register what you use once with `registerIcons({ fingerprint, brandGithub })` (or `registerIcons(ICON_LIBRARY)`), then use the names in `Icon` and every `icon` prop. Only registered icons are bundled.
  - Line icons are drawn on the kit's 24px grid with 2px round strokes (from Lucide, ISC); brand logos are filled (from Simple Icons, CC0). Licence notices ship in `ICONS-LICENSE`.
  - Your own icons: `registerIcons({ acme: "M…" })`, typed through the `CustomIcons` interface. The 93 built-in icons work as before and cannot be replaced.
  - An unknown icon name now logs a warning once instead of silently drawing a placeholder.
  - `@twentyfirstmedia/elements` registers the whole library, so `<tf-button icon="fingerprint">` works in plain HTML; it also exports `registerIcons`.
  - New docs page "Icons": every icon with search, categories and copy on click. The MCP server's `list_icons`, `search_docs` and `check_usage` know the library.

### 0.3.1

#### Patch Changes

- [#35](https://github.com/twentyfirstmedia/ui/pull/35) [`3a25cd6`](https://github.com/twentyfirstmedia/ui/commit/3a25cd6e9162a69465a5e7794b2f38c970f4ff08) Thanks [@robintrepte](https://github.com/robintrepte)! - `FloatingLayout` on a phone keeps the height it is given: the stacked slot grid counts its padding into the inherited height (`box-sizing: border-box`). Before, the layout grew by twice the padding, and with a fixed height the bottom slot was cut off at the edge. Apps that worked around it with `.tf-floating-ui { box-sizing: border-box; }` can drop that rule.

### 0.3.0

#### Minor Changes

- [#30](https://github.com/twentyfirstmedia/ui/pull/30) [`bef588d`](https://github.com/twentyfirstmedia/ui/commit/bef588d0fb521a5b458113095a7952222efe3c63) Thanks [@robintrepte](https://github.com/robintrepte)! - `Button` and `IconButton` pass native attributes on to their `<button>` (or, with `asChild`, to the child): `id`, `name`, `value`, `form`, `title`, `tabIndex`, `autoFocus`, `aria-label`, `aria-labelledby`, `aria-describedby`, `aria-expanded`, `aria-controls`, `aria-haspopup`, `aria-pressed`, `aria-current` (documented as `NativeButtonProps`), plus any other `<button>` attribute, `data-*`, event handlers and, in React 19, `ref`. `type` also takes `"reset"`, and `IconButton` takes `type`. On `IconButton`, `aria-label` or `title` override the ones `label` sets. With `asChild`, `onClick` and the other attributes now reach the child as well.
  
  In `@twentyfirstmedia/elements`, `<tf-button>` and `<tf-icon-button>` take these as attributes; `aria-*` attributes move from the host to the inner button. The docs and the MCP server list them with both components.

- [#28](https://github.com/twentyfirstmedia/ui/pull/28) [`ef1090f`](https://github.com/twentyfirstmedia/ui/commit/ef1090f32204a227ed0ad717e74ea057f6d4da90) Thanks [@robintrepte](https://github.com/robintrepte)! - `FileDrop` hands over the real files.
  
  - New `onFiles(files: File[])` with the `File` objects the person picked or dropped, after `accept` and `multiple`. Added list entries carry their `file` too, so `onChange` gets them as well.
  - Progress only when the app reports it: with `onFiles`, nothing is simulated; set `progress` on controlled `files` to show a bar (now a labelled `progressbar`). An uncontrolled list with `onFiles` shows each file with its size only.
  - `accept` is checked on drop as well; `onReject` receives what did not match. `onRemove` reports removed or cancelled files.
  - `simulateProgress` keeps the old demo animation; it stays the default without `onFiles`, so existing code behaves as before. Running simulations stop on unmount.

- [#31](https://github.com/twentyfirstmedia/ui/pull/31) [`ece54b1`](https://github.com/twentyfirstmedia/ui/commit/ece54b18c3594f595386608e12c93190aa41d5bb) Thanks [@robintrepte](https://github.com/robintrepte)! - `Gallery` and `BeforeAfter` load images lazily and take `loading` and `referrerPolicy`.
  
  - `Gallery`: the main image loads lazily by default (`loading="eager"` for a gallery at the top of the page), thumbnails always lazily, all images decode asynchronously; `referrerPolicy` applies to every image (new type `ImageReferrerPolicy`).
  - `BeforeAfter`: the slider has an `aria-valuetext` ("Before 40%, After 60%", with `beforeLabel`/`afterLabel`), overridable with `valueText(percent)`; its accessible name is `label`. Page Up/Down, Home and End move the slider; arrow keys no longer scroll the page while it has focus. Both images take `loading` (default lazy) and `referrerPolicy`.

- [#29](https://github.com/twentyfirstmedia/ui/pull/29) [`4cf034a`](https://github.com/twentyfirstmedia/ui/commit/4cf034af9d2a7eafae5281252e6f7857a74f8540) Thanks [@robintrepte](https://github.com/robintrepte)! - `Pagination` can be controlled: `page` with `onChange(page)` (1-based), or `defaultPage` with an optional `onChange` for an uncontrolled pager. `page` without `onChange` stays the start page, as before. Clicking the current page or past either end no longer reports a change.

- [#33](https://github.com/twentyfirstmedia/ui/pull/33) [`d408a82`](https://github.com/twentyfirstmedia/ui/commit/d408a82cc5ab0acf5401c56118acf36e62516a81) Thanks [@robintrepte](https://github.com/robintrepte)! - Every built-in string is overridable, and numbers follow a locale.
  
  - `UIProvider messages`: replace any text a component shows on its own (accessible names such as "Close", "Send", "Previous image", "Select row", button texts, placeholders, status words, validation messages). Partial and nested; props such as `title` or `label` still win. English stays the default and no translations ship. `useUIStrings()`, `DEFAULT_STRINGS`, the `UIStrings` and `UIMessages` types, and one exported group per component file (`MEDIA_STRINGS` …).
  - `UIProvider locale` (BCP 47, default `en-US`): every number, amount, percentage and date in components, calendar month and weekday names. `useFormat()` returns the helpers bound to it; `formatNumber`, `formatMoney`, `formatPercent` and `formatDate` take an optional locale as their last argument.
  - `CountUp` and `StatTile` read string values in the provider locale ("13,05 €/m²" in de-DE counts to 13.05 instead of showing "1,305"). New helpers `parseFormatted`, `formatLike`, `numberSeparators`.
  - `SearchField` takes `label` (accessible name).
  - Fixed: `VoiceMode` with `stateLabel` showed "Listening…".

- [#32](https://github.com/twentyfirstmedia/ui/pull/32) [`3b0992d`](https://github.com/twentyfirstmedia/ui/commit/3b0992dd44ef4f864e96c9735d55a9dbb18b8747) Thanks [@robintrepte](https://github.com/robintrepte)! - `TextField` passes native constraints to its input: `min`, `max`, `step`, `minLength`, `maxLength`, `pattern`, `inputMode`, `readOnly` and `autoFocus` (next to the existing `name`, `required` and `id`), all typed and documented. `PlanCard` takes `disabled` for its button.

### 0.2.1

#### Patch Changes

- [#26](https://github.com/twentyfirstmedia/ui/pull/26) [`863179b`](https://github.com/twentyfirstmedia/ui/commit/863179b194fcd8e43bac596039ef555cc294d03e) Thanks [@robintrepte](https://github.com/robintrepte)! - Published through npm Trusted Publishing: the release workflow no longer uses an npm token, and every package carries a provenance statement linking it to the GitHub Actions run that built it. No code changes.

### 0.2.0

#### Minor Changes

- [#24](https://github.com/twentyfirstmedia/ui/pull/24) [`4529ab5`](https://github.com/twentyfirstmedia/ui/commit/4529ab565c0de3dadb52b248585f1d4bb0ae0b3c) Thanks [@robintrepte](https://github.com/robintrepte)! - Whole dashboards in glass, in both kits.
  
  - New `Ambient`: a calm, living background of soft colour fields from the kit (pastels in Halo, a faint aurora in Pro) that drift slowly, or a photo or video under a scrim, or your own layer. Still with motion off, paused off screen. New tokens `--ambient-base`, `--ambient-1…4`, `--ambient-scrim`.
  - In a glass region, `AppShell` turns into glass (top bar, rail, sidebar; the sheet clears), and `StatTile` and tinted cards lay their tint over the glass (`--glass-tint`).
  - On glass, the faintest text steps up one shade so secondary text stays readable.
  - `AppShell` applies `className`.
  - New pattern: a wellbeing dashboard in glass.

- [#22](https://github.com/twentyfirstmedia/ui/pull/22) [`beb3043`](https://github.com/twentyfirstmedia/ui/commit/beb30433be7abc8ed1adabf0bae2fc4de526e8f7) Thanks [@robintrepte](https://github.com/robintrepte)! - Glass surfaces for UI that floats over maps, 3D scenes, video or photos, in both kits: translucent, blurred and colour-lifted, soft and milky in Halo, dark with a hairline edge in Pro.
  
  - `surface="glass"` on `Panel`, `Card`, `Dock` and `MapView` (legend, controls, popup), and `<UIProvider surface="glass">` for everything floating in a subtree: top-level surfaces, loose controls, menus, popovers, dialogs and drawers. What sits on glass (inputs, tab tracks, badges, highlights) turns translucent too; `surface="solid"` opts one out. Without React: `class="tf-glass"` or `data-surface="glass"`.
  - New `FloatingLayout`: four slots (`top`, `start`, `end`, `bottom`) over a full-bleed `background`, glass by default; on phones the slots stack and the layout grows with them.
  - New glass tokens in both kits (`--glass`, `--glass-strong`, `--glass-control`, `--glass-well`, `--glass-hover`, `--glass-border`, `--glass-highlight`, `--glass-sheen`, `--shadow-glass`, `--glass-filter`), derived from the theme. Body text on glass keeps 4.5:1 over any backdrop; reduced transparency and forced colours switch to solid surfaces, more contrast to the stronger fill.
  - `MapView` takes `height="100%"` (any CSS length).
  - `Dock` now applies `className` and `style`.
  - A `UIProvider` subtree with its own `tokens` keeps the outer theme, so derived colours follow the tokens even without a `theme` prop.
  - New pattern: a city map with glass controls.

- [#22](https://github.com/twentyfirstmedia/ui/pull/22) [`beb3043`](https://github.com/twentyfirstmedia/ui/commit/beb30433be7abc8ed1adabf0bae2fc4de526e8f7) Thanks [@robintrepte](https://github.com/robintrepte)! - Motion with one switch, in both kits.
  
  - `<UIProvider motion="off" | "standard" | "expressive">` (or `data-motion`): `expressive` gives orchestrated page entrances (Halo: longer, more travel, a short focus-in blur; Pro: crisp and staggered), `off` stops everything, e.g. for a setting in your app. The reader's reduced-motion setting always turns motion off.
  - Choreography: charts, progress bars and `CountUp` wait for the card they sit in; a `Stagger` below the fold waits until it scrolls into view (`reveal={false}` plays at once).
  - Layers animate out as well as in: popovers, tooltips, hover cards, comboboxes, dialogs, drawers, the command palette and toasts. `Modal`, `Drawer` and `CommandPalette` take an optional `open` for that.
  - `startViewTransition(update)` for page transitions (the kits style `::view-transition`), `useMotion()` for the level in effect, `usePresence(open)` and `leaving()` for your own layers.
  - New motion tokens: `--dur-exit`, `--motion-time`, `--motion-travel`, `--motion-blur`.
  - Fixed: with `themes.css` or `scoped.css`, keyframes defined in another file of the kit never ran (spinners, skeleton shimmer, pulses, pop-ins).

#### Patch Changes

- [#25](https://github.com/twentyfirstmedia/ui/pull/25) [`688f141`](https://github.com/twentyfirstmedia/ui/commit/688f141210ed82c5c10b375b38c9d06bbc7a7bf2) Thanks [@robintrepte](https://github.com/robintrepte)! - Glass app shell: it keeps the layout of the solid shell and turns its frame into glass, with the top bar and rail sitting on it as they sit on the solid frame (they no longer float as separate pieces). A `ToggleGroup` is only as wide as its items.

### 0.1.1

No changes in this release.

### 0.1.0

#### Minor Changes

- [#12](https://github.com/twentyfirstmedia/ui/pull/12) [`2cf6196`](https://github.com/twentyfirstmedia/ui/commit/2cf6196cc8e81afa0668ce36e35dfe01501e44ea) Thanks [@robintrepte](https://github.com/robintrepte)! - Consistency pass over every component in both kits and themes. The app shell responds to its own width (container queries); kit boxes no longer depend on the host's box-sizing; controls and code use the kit fonts; bold stays on the type scale; status shapes, list icons, stat values, pagination and invoice numbers line up; segmented controls and tabs no longer stretch or break mid-word. Gauge, Funnel and ProgressRing now fill when reduced motion is on. Pro follows its reference more closely: decorative tints and chart series are monochrome, bars are flat, in-flow cards use hairlines, badges sit on the corner. New: `formatPercent`.

- [#8](https://github.com/twentyfirstmedia/ui/pull/8) [`2db7b83`](https://github.com/twentyfirstmedia/ui/commit/2db7b83266449602d1209c346b44ad62a66c416d) Thanks [@robintrepte](https://github.com/robintrepte)! - First release: every component of the Halo reference in `ui-core`, the Halo and Pro kits with the same components, props and markup (switchable at runtime via `data-kit`), tokens and a Tailwind v4 preset per kit, self-hosted fonts and the CLI (`init`, `add`, `list`, `diff`).

- [#10](https://github.com/twentyfirstmedia/ui/pull/10) [`532f835`](https://github.com/twentyfirstmedia/ui/commit/532f83532d4ce4098733020d34277299c025fa08) Thanks [@robintrepte](https://github.com/robintrepte)! - Mobile first: every component works from 320px up in both kits (desktop from 1181px unchanged). The shell, rail and page nav reflow on phones, tables scroll in their own box, dialogs open as bottom sheets, popovers and tooltips stay on screen, text fields use 16px on touch screens and Pro switches to comfortable hit targets on touch unless `data-density` is set. New: `tf-grid` columns via `--cols` / `--cols-md` / `--cols-sm`, `tf-sheet-nav` / `tf-sheet-aside`, `tf-table-scroll`, `useKeepInView`, `useScrollFocus`, `Tooltip` `defaultOpen`.

- [#16](https://github.com/twentyfirstmedia/ui/pull/16) [`350ca53`](https://github.com/twentyfirstmedia/ui/commit/350ca53ea6b1a4dd77759449ac4b56bb8ed2a62a) Thanks [@robintrepte](https://github.com/robintrepte)! - Open source under the MIT license and published on npmjs.com: install with `npm i @twentyfirstmedia/halo` (or `pro`), no registry setup or token. `twentyfirst-ui init` no longer writes an `.npmrc`.

- [#13](https://github.com/twentyfirstmedia/ui/pull/13) [`559cb2d`](https://github.com/twentyfirstmedia/ui/commit/559cb2df5ac851e71ad0f3808b1442f7f79a6401) Thanks [@robintrepte](https://github.com/robintrepte)! - English only: built-in text is plain English and overridable through props; numbers, money, percentages and dates format with Intl in en-US (`formatNumber`, `formatMoney`, `formatPercent`, `formatDate`).
  
  New components in both kits: Accordion, Separator, AspectRatio, Label, Toggle, ToggleGroup, ButtonGroup, ScrollArea, HoverCard, Carousel, Menubar, NavigationMenu, Sidebar, SelectMenu, Form and ResizablePanels. Menu gains keyboard navigation, typeahead, submenus, checkbox/radio and disabled items; Tabs render panels; Drawer takes `side`; Popover flips when there is no room; CommandPalette takes `loading`, `empty` and `onQueryChange`; Button and IconButton take `asChild`; inputs take `id`, `name` and `required`.

- [#18](https://github.com/twentyfirstmedia/ui/pull/18) [`0f19447`](https://github.com/twentyfirstmedia/ui/commit/0f19447291603a148759d10b7a2bf13ea7e95cb6) Thanks [@robintrepte](https://github.com/robintrepte)! - shadcn-style theming in both kits. The kits use shadcn/ui's theme variables (`background`, `foreground`, `card`, `popover`, `primary`, `secondary`, `muted`, `accent`, `destructive`, `border`, `input`, `ring`, `radius`, `chart-1` … `chart-5`, `sidebar-*`) and every component reads them, so a pasted shadcn theme restyles everything, light and dark. The old `--accent`/`--on-accent`/`--accent-hover` are now `--primary`/`--primary-foreground`/`--primary-hover`; `--accent` is the highlight under the pointer, as in shadcn. Token blocks have zero specificity and dark mode also follows the `.dark` class. New: `themeCss`, `parseThemeCss`, `brandTheme`, `THEME_PRESETS` and preset CSS files (`themes/blue.css` …), `UIProvider tokens`, `twentyfirst-ui theme`, Tailwind utilities with shadcn's names.

#### Patch Changes

- [#15](https://github.com/twentyfirstmedia/ui/pull/15) [`2c5ddb6`](https://github.com/twentyfirstmedia/ui/commit/2c5ddb6715c7c296a3379ea241158218185e9262) Thanks [@robintrepte](https://github.com/robintrepte)! - The CLI ships an MCP server for coding agents: `twentyfirst-ui mcp` (stdio, offline, the docs are bundled) with the tools `search_docs`, `list_components`, `get_component`, `get_pattern`, `get_guide`, `get_tokens`, `list_icons` and `check_usage`, every page as a resource, and the prompts `build_screen` and `review_ui`. `twentyfirst-ui mcp init` registers it for Claude Code, Cursor and VS Code and adds the kit rules to `AGENTS.md`.

- [#11](https://github.com/twentyfirstmedia/ui/pull/11) [`acec782`](https://github.com/twentyfirstmedia/ui/commit/acec782abd5f1d188f9ee5e7c8eb563e6c450031) Thanks [@robintrepte](https://github.com/robintrepte)! - Icons are centred: 36 icon drawings were off the middle of their 24px grid (up to 1.75 units), visible in round icon buttons and tinted icons. They are now centred on their bounding box; shapes are unchanged, and `play` stays optically centred.


# Components

## Activity Feed

> What happened and what needs you: ActivityFeed (timeline with status shapes) and DailyBriefing (the morning summary).

Component · AI · Halo kit · [Live page](https://ui.twentyfirst.media/halo/components/ActivityFeed/)

What happened and what needs you: `ActivityFeed` (timeline with status shapes) and `DailyBriefing` (the morning summary).

ActivityFeed: `groups` ({title, items}) or `items` ({time, status, actor, text, link}).
DailyBriefing: `title`, `time`, `tint`, `summary`, `attention` ({text, status, onClick}), `suggestions` (strings), `attentionTitle`, `suggestionsTitle`.

### Example

```tsx
import * as React from "react";
import { ActivityFeed, DailyBriefing } from "@twentyfirstmedia/halo";

export default function Preview() {
  return (
    <div
      className="tf-grid"
      style={
        {
          "--cols": "1fr 1fr",
          gap: 16,
          alignItems: "start",
        } as React.CSSProperties
      }
    >
      <div className="tf-panel">
        <ActivityFeed
          groups={[
            {
              title: "Today",
              items: [
                {
                  time: "09:41",
                  status: "signal",
                  actor: "Atlas",
                  text: "asked to send a reply to Northwind",
                },
                {
                  time: "09:12",
                  status: "warn",
                  actor: "Ads",
                  text: "reached 82% of the monthly budget",
                },
                {
                  time: "08:02",
                  status: "ok",
                  actor: "Ledger",
                  text: "matched 31 payments",
                },
              ],
            },
            {
              title: "Yesterday",
              items: [
                {
                  time: "18:02",
                  status: "danger",
                  actor: "Echo",
                  text: "stopped: the docs connection expired",
                },
              ],
            },
          ]}
        />
      </div>
      <div className="tf-panel">
        <DailyBriefing
          title="Main Brain"
          time="Today, 08:00"
          summary="26 runs overnight, 22 succeeded. €4.18 spent, well under budget. Two drafts wait for you and the docs connection needs a new token."
          attention={[
            {
              text: "Approve the reply to Northwind",
            },
            {
              text: "Reconnect the docs workspace",
              status: "danger",
            },
          ]}
          suggestions={[
            "Move the weekly report to Monday 09:00",
            "Give Ledger read access to the new bank account",
          ]}
        />
      </div>
    </div>
  );
}
```

### Props

#### ActivityFeed

| Prop | Type | Notes |
| --- | --- | --- |
| `groups?` | `{ title?: string; items: ActivityItem[] }[]` |  |
| `items?` | `ActivityItem[]` |  |
| `className?` | `string` | Extra class on the root element. |
| `style?` | `CSSProperties` | Inline style on the root element. |

#### DailyBriefing

| Prop | Type | Notes |
| --- | --- | --- |
| `title` | `string` | Required |
| `time?` | `string` |  |
| `tint?` | `Tint` |  |
| `summary` | `ReactNode` | Required |
| `attention?` | `{ text: ReactNode; status?: Status; onClick?: () => void }[]` |  |
| `suggestions?` | `ReactNode[]` |  |
| `attentionTitle?` | `string` |  |
| `suggestionsTitle?` | `string` |  |
| `className?` | `string` | Extra class on the root element. |
| `style?` | `CSSProperties` | Inline style on the root element. |


## Agent Card

> One agent at a glance (AgentCard) and everything about it beside a chat (AgentDetails).

Component · AI · Halo kit · [Live page](https://ui.twentyfirst.media/halo/components/AgentCard/)

One agent at a glance (`AgentCard`) and everything about it beside a chat (`AgentDetails`).

AgentCard: `name`, `role`, `tint`, `status` + `statusLabel`, `model`, `cost`, `last`, `onClick`, `onChat`.
AgentDetails: `name`, `role`, `tint`, `status` + `statusLabel`, `sections` ({title, meta, items (KeyValue) or children, open}), `actions`.

### Example

```tsx
import * as React from "react";
import { AgentCard, AgentDetails, Button } from "@twentyfirstmedia/halo";

export default function Preview() {
  return (
    <div
      className="tf-grid"
      style={
        {
          "--cols": "1fr 1fr 300px",
          gap: 16,
          alignItems: "start",
        } as React.CSSProperties
      }
    >
      <AgentCard
        name="Atlas"
        role="Support triage"
        tint="sky"
        status="running"
        statusLabel="Working"
        model="Claude Sonnet 5.5"
        cost="€1.84"
        last="Drafted a reply to Northwind"
        onChat={() => {}}
        onClick={() => {}}
      />
      <AgentCard
        name="Ledger"
        role="Bookkeeping"
        tint="butter"
        status="signal"
        statusLabel="Waiting for approval"
        model="Claude Haiku 5.5"
        cost="€0.22"
        last="Proposed 3 bookings"
      />
      <div className="tf-panel">
        <AgentDetails
          name="Atlas"
          role="Support triage · Northwind"
          tint="sky"
          status="running"
          statusLabel="Working"
          sections={[
            {
              title: "Numbers",
              items: [
                ["Model", "Claude Sonnet 5.5"],
                ["Today", "€1.84", true],
                ["This month", "€38.20", true],
                ["Runs", "142"],
              ],
            },
            {
              title: "Tools",
              meta: "3",
              items: [
                ["Mailbox", "read, draft"],
                ["Knowledge base", "read"],
              ],
            },
            {
              title: "Memory",
              open: false,
              children: "Prefers short replies.",
            },
          ]}
          actions={[
            <Button key="c" variant="soft" icon="settings">
              Configure
            </Button>,
          ]}
        />
      </div>
    </div>
  );
}
```

### Props

#### AgentCard

| Prop | Type | Notes |
| --- | --- | --- |
| `name` | `string` | Required |
| `role?` | `string` |  |
| `tint?` | `Tint` |  |
| `status?` | `Status` |  |
| `statusLabel?` | `string` |  |
| `model?` | `string` |  |
| `cost?` | `string` |  |
| `last?` | `ReactNode` |  |
| `onClick?` | `() => void` |  |
| `onChat?` | `() => void` |  |
| `className?` | `string` | Extra class on the root element. |
| `style?` | `CSSProperties` | Inline style on the root element. |

#### AgentDetails

| Prop | Type | Notes |
| --- | --- | --- |
| `name` | `string` | Required |
| `role?` | `string` |  |
| `tint?` | `Tint` |  |
| `status?` | `Status` |  |
| `statusLabel?` | `string` |  |
| `sections?` | `{ title: string; meta?: ReactNode; items?: KeyValueItem[]; children?: ReactNode; open?: boolean; }[]` |  |
| `actions?` | `ReactNode[]` |  |
| `className?` | `string` | Extra class on the root element. |
| `style?` | `CSSProperties` | Inline style on the root element. |

#### Button

| Prop | Type | Notes |
| --- | --- | --- |
| `variant?` | `"primary" \| "secondary" \| "soft" \| "ghost" \| "danger" \| "danger-solid"` |  |
| `size?` | `"md" \| "sm"` |  |
| `icon?` | `IconName` |  |
| `iconRight?` | `IconName` |  |
| `disabled?` | `boolean` |  |
| `type?` | `"button" \| "submit" \| "reset"` |  |
| `onClick?` | `(e: MouseEvent<HTMLButtonElement>) => void` |  |
| `children?` | `ReactNode` |  |
| `asChild?` | `boolean` | Render the single child element (a link, a router Link) with the button's look instead of a <button>. |
| `id?` | `string` |  |
| `name?` | `string` | Form field name and value, sent with the form when this button submits it. |
| `value?` | `string` |  |
| `form?` | `string` | The id of the form this button belongs to, when it sits outside it. |
| `title?` | `string` |  |
| `tabIndex?` | `number` |  |
| `autoFocus?` | `boolean` |  |
| `aria-label?` | `string` |  |
| `aria-labelledby?` | `string` |  |
| `aria-describedby?` | `string` |  |
| `aria-expanded?` | `boolean \| "true" \| "false"` | For disclosure and menu triggers: whether what the button controls is open. |
| `aria-controls?` | `string` |  |
| `aria-haspopup?` | `boolean \| "true" \| "false" \| "menu" \| "listbox" \| "tree" \| "grid" \| "dialog"` |  |
| `aria-pressed?` | `boolean \| "true" \| "false" \| "mixed"` | For toggle buttons. |
| `aria-current?` | `boolean \| "true" \| "false" \| "page" \| "step" \| "location" \| "date" \| "time"` |  |
| `className?` | `string` | Extra class on the root element. |
| `style?` | `CSSProperties` | Inline style on the root element. |


## Alert

> Inline banner for a state the page is in: a warning, a failure, a note.

Component · Overlays · Halo kit · [Live page](https://ui.twentyfirst.media/halo/components/Alert/)

Inline banner for a state the page is in: a warning, a failure, a note. Lives in the page, unlike a toast.

Props: `tone` ("info" | "success" | "warning" | "danger" | "highlight"), `title`, children (one sentence), `icon` (override), `action` (one small Button), `onDismiss`.

- One alert per page section, at the top of what it concerns. Two warnings: merge them.
- Title says the state, body says the consequence or the next step.
- Warning and danger are announced to screen readers; info and success are polite.
- Never use an alert for something that already happened and needs no action: that's a toast.

### Example

```tsx
import { Alert, Button } from "@twentyfirstmedia/halo";

function App() {
  return (
    <div
      className="tf-panel"
      style={{
        gap: 12,
      }}
    >
      <Alert tone="info" title="Bank feed syncs every 4 hours" onDismiss={() => {}}>
        New transactions show up here and get matched automatically.
      </Alert>
      <Alert tone="success" title="Domain verified">
        halo.app is ready to send mail.
      </Alert>
      <Alert
        tone="warning"
        title="halo.dev expires on May 4, 2026"
        action={
          <Button size="sm" variant="secondary">
            Turn on auto-renew
          </Button>
        }
      >
        Auto-renew is off. If it lapses, mail on this domain stops.
      </Alert>
      <Alert
        tone="danger"
        title="Payment failed"
        action={
          <Button size="sm" variant="secondary">
            Update card
          </Button>
        }
      >
        We couldn’t charge the card ending 4242. We retry in 3 days.
      </Alert>
      <Alert tone="highlight" title="3 agent drafts need your review" />
    </div>
  );
}
export default App;
```

### Props

#### Alert

| Prop | Type | Notes |
| --- | --- | --- |
| `tone?` | `Exclude<Tone, "neutral">` |  |
| `title?` | `ReactNode` |  |
| `icon?` | `IconName` |  |
| `action?` | `ReactNode` |  |
| `onDismiss?` | `() => void` |  |
| `children?` | `ReactNode` |  |
| `className?` | `string` | Extra class on the root element. |
| `style?` | `CSSProperties` | Inline style on the root element. |

#### Button

| Prop | Type | Notes |
| --- | --- | --- |
| `variant?` | `"primary" \| "secondary" \| "soft" \| "ghost" \| "danger" \| "danger-solid"` |  |
| `size?` | `"md" \| "sm"` |  |
| `icon?` | `IconName` |  |
| `iconRight?` | `IconName` |  |
| `disabled?` | `boolean` |  |
| `type?` | `"button" \| "submit" \| "reset"` |  |
| `onClick?` | `(e: MouseEvent<HTMLButtonElement>) => void` |  |
| `children?` | `ReactNode` |  |
| `asChild?` | `boolean` | Render the single child element (a link, a router Link) with the button's look instead of a <button>. |
| `id?` | `string` |  |
| `name?` | `string` | Form field name and value, sent with the form when this button submits it. |
| `value?` | `string` |  |
| `form?` | `string` | The id of the form this button belongs to, when it sits outside it. |
| `title?` | `string` |  |
| `tabIndex?` | `number` |  |
| `autoFocus?` | `boolean` |  |
| `aria-label?` | `string` |  |
| `aria-labelledby?` | `string` |  |
| `aria-describedby?` | `string` |  |
| `aria-expanded?` | `boolean \| "true" \| "false"` | For disclosure and menu triggers: whether what the button controls is open. |
| `aria-controls?` | `string` |  |
| `aria-haspopup?` | `boolean \| "true" \| "false" \| "menu" \| "listbox" \| "tree" \| "grid" \| "dialog"` |  |
| `aria-pressed?` | `boolean \| "true" \| "false" \| "mixed"` | For toggle buttons. |
| `aria-current?` | `boolean \| "true" \| "false" \| "page" \| "step" \| "location" \| "date" \| "time"` |  |
| `className?` | `string` | Extra class on the root element. |
| `style?` | `CSSProperties` | Inline style on the root element. |


## Approval Card

> The human-in-the-loop decision: what an agent wants to do, the exact payload, and the four answers A–D.

Component · AI · Halo kit · [Live page](https://ui.twentyfirst.media/halo/components/ApprovalCard/)

The human-in-the-loop decision: what an agent wants to do, the exact payload, and the four answers A–D.

Props: `title` (the action as one sentence), `text` (why), children (the payload, verbatim), `agent`, `project`, `family` ("money" | "infra" | "comms" | "marketing" | "apps" | "legal") or `familyLabel`, `age`, `escalation`, `trace` (node), `note`, `heading`, `onDecide(key, text)`, `decision` ({key, by, at, text}: renders the one-line record), `options` (override A–D; each {key, label, input}), `approveLabel` (relabels A), `compact`. Legacy `onApprove` / `onDeny` / `onEdit` and `state` still work.

- Always four answers in this order: **A** yes, as shown · **B** yes, with a change · **C** no, discard · **D** different instruction. B and D open a text field; ⌘/Ctrl+Enter sends.
- A–D work as keys while the card has focus.
- The payload is exactly what will run: the full mail, the amount and recipient, the command, the DNS change before and after. Never a summary.
- Show the risk family, the age and the escalation time. Nothing runs automatically when time is up.
- After a decision the card collapses to one line: letter, who, when (and the change or instruction).
- The A–D wording can be changed through `options`.

### Example

```tsx
import * as React from "react";
import { ApprovalCard } from "@twentyfirstmedia/halo";
import type { ApprovalDecision } from "@twentyfirstmedia/halo";

function App() {
  const d = React.useState<ApprovalDecision | null>(null);
  return (
    <div
      className="tf-col"
      style={{
        gap: 16,
      }}
    >
      <ApprovalCard
        agent="Atlas"
        project="Support"
        family="comms"
        age="4 min"
        title="Send this email to ida@northwind.io"
        text="Atlas is set to drafts only, so it needs your OK."
        escalation="Escalates to the owner in 1:52 h"
        trace={<a href="#">Open trace</a>}
        decision={d[0]}
        onDecide={(k, t) => {
          d[1]({
            key: k,
            by: "Mara Ellis",
            at: "09:41",
            text: t,
          });
        }}
      >
        <div className="tf-approval-mail">
          {
            "Hi Ida,\n\nhappy to add 40 seats before your renewal on May 1. The quote is attached.\n\nBest,\nMara"
          }
        </div>
      </ApprovalCard>
      <ApprovalCard
        agent="Ledger"
        project="Finance"
        family="money"
        title="Refund €10.00 to the card ending 4242"
        decision={{
          key: "C",
          by: "Lukas",
          at: "Yesterday 18:02",
        }}
      />
      <ApprovalCard
        agent="Scout"
        project="Domains"
        family="infra"
        title="Add TXT record ops-test"
        decision={{
          key: "B",
          by: "Mara Ellis",
          at: "08:10",
          text: "Use TTL 300 instead",
        }}
      />
    </div>
  );
}
export default App;
```

### Props

#### ApprovalCard

| Prop | Type | Notes |
| --- | --- | --- |
| `title` | `ReactNode` | Required |
| `text?` | `ReactNode` |  |
| `children?` | `ReactNode` |  |
| `agent?` | `string` |  |
| `project?` | `string` |  |
| `family?` | `RiskFamily` |  |
| `familyLabel?` | `string` |  |
| `age?` | `string` |  |
| `escalation?` | `ReactNode` |  |
| `trace?` | `ReactNode` |  |
| `note?` | `ReactNode` |  |
| `heading?` | `string` |  |
| `options?` | `ApprovalOption[]` |  |
| `approveLabel?` | `string` |  |
| `onDecide?` | `(key: ApprovalKey, text?: string) => void` |  |
| `decision?` | `ApprovalDecision \| null` |  |
| `compact?` | `boolean` |  |
| `onApprove?` | `() => void` |  |
| `onDeny?` | `() => void` |  |
| `onEdit?` | `(text: string) => void` |  |
| `state?` | `"approved" \| "denied"` |  |
| `className?` | `string` | Extra class on the root element. |
| `style?` | `CSSProperties` | Inline style on the root element. |


## Approval Inbox

> All open approvals across projects, oldest first, next to the selected ApprovalCard.

Component · AI · Halo kit · [Live page](https://ui.twentyfirst.media/halo/components/ApprovalInbox/)

All open approvals across projects, oldest first, next to the selected ApprovalCard.

Props: `items` ({id, title, agent, project, family, familyLabel, age, ageMin, urgent}), `selected`, `onSelect(id)`, `emptyTitle`, `emptyText`, `label`.

- Oldest first: the one closest to escalation is on top; `urgent` turns its age into a warning.
- J / K or ↓ / ↑ move the selection; the card next to it takes A–D.

### Example

```tsx
import * as React from "react";
import { ApprovalInbox } from "@twentyfirstmedia/halo";
import type { ApprovalInboxItem } from "@twentyfirstmedia/halo";

const items: ApprovalInboxItem[] = [
  {
    id: 1,
    title: "Send reply to Northwind",
    agent: "Atlas",
    project: "Support",
    family: "comms",
    age: "2 h 10 min",
    ageMin: 130,
    urgent: true,
  },
  {
    id: 2,
    title: "Refund €10.00 to card ending 4242",
    agent: "Ledger",
    project: "Chatteo",
    family: "money",
    age: "38 min",
    ageMin: 38,
  },
  {
    id: 3,
    title: "Set daily ad budget to €30",
    agent: "Ads",
    project: "Northwind",
    family: "marketing",
    age: "12 min",
    ageMin: 12,
  },
  {
    id: 4,
    title: "Add TXT record ops-test",
    agent: "Scout",
    project: "Domains",
    family: "infra",
    age: "3 min",
    ageMin: 3,
  },
];
function App() {
  const s = React.useState<string | number>(1);
  return (
    <div className="tf-panel tf-panel-flush tf-panel-list">
      <ApprovalInbox items={items} selected={s[0]} onSelect={s[1]} />
    </div>
  );
}
export default App;
```

### Props

#### ApprovalInbox

| Prop | Type | Notes |
| --- | --- | --- |
| `items` | `ApprovalInboxItem[]` | Required |
| `selected?` | `ApprovalInboxItem["id"]` |  |
| `onSelect?` | `(id: ApprovalInboxItem["id"]) => void` |  |
| `emptyTitle?` | `string` |  |
| `emptyText?` | `string` |  |
| `label?` | `string` |  |
| `className?` | `string` | Extra class on the root element. |
| `style?` | `CSSProperties` | Inline style on the root element. |


## Area Chart

> Smooth stacked areas for volume over time, with a crosshair tooltip.

Component · Charts · Halo kit · [Live page](https://ui.twentyfirst.media/halo/components/AreaChart/)

Smooth stacked areas for volume over time, with a crosshair tooltip.

Props: `labels`, `series` ({name, tint, values}), `stacked` (default true), `height`, `width`, `format(v)`, `legend`, `label`.

- Areas are the light tints, edges the `-ink` lines, so the stack reads in both themes.
- Use stacked areas when the total matters; switch to LineChart when you compare series against each other.
- Labels thin out automatically past 12 points.

### Example

```tsx
import { AreaChart } from "@twentyfirstmedia/halo";

export default function Preview() {
  return (
    <div className="tf-panel">
      <div>
        <h3 className="tf-panel-title">Visitors by channel</h3>
        <p className="tf-panel-sub">Stacked, per week</p>
      </div>
      <AreaChart
        height={180}
        labels={["W14", "W15", "W16", "W17", "W18", "W19", "W20", "W21"]}
        format={(v) => (v / 1000).toFixed(1) + "k"}
        series={[
          {
            name: "Organic",
            tint: "sky",
            values: [4200, 4600, 4400, 5100, 5600, 5300, 6100, 6500],
          },
          {
            name: "Newsletter",
            tint: "butter",
            values: [1800, 2600, 1900, 2100, 3400, 2200, 2400, 3900],
          },
          {
            name: "Partners",
            tint: "mint",
            values: [1200, 1300, 1500, 1400, 1600, 1900, 1800, 2100],
          },
        ]}
      />
    </div>
  );
}
```

### Props

#### AreaChart

| Prop | Type | Notes |
| --- | --- | --- |
| `labels` | `string[]` | Required |
| `series` | `Series[]` | Required |
| `stacked?` | `boolean` |  |
| `height?` | `number` |  |
| `width?` | `number` |  |
| `format?` | `(v: number) => string` |  |
| `legend?` | `boolean` |  |
| `label?` | `string` |  |
| `className?` | `string` | Extra class on the root element. |
| `style?` | `CSSProperties` | Inline style on the root element. |


## Backup List

> Admin safety lists: BackupList (snapshots with restore) and BlockList (blocked IPs, emails, accounts).

Component · Admin · Halo kit · [Live page](https://ui.twentyfirst.media/halo/components/BackupList/)

Admin safety lists: `BackupList` (snapshots with restore) and `BlockList` (blocked IPs, emails, accounts).

BackupList: `items` ({id, name, kind, where, retention, size, status}), `onDownload`, `onRestore`, `footer`. Restore is always confirmed (ConfirmDialog) by the app.
BlockList: `items` ({id, value, kind, reason, by, until}), `onAdd`, `onRemove`, `addLabel`, `removeLabel`, `searchPlaceholder`, `emptyText`.

### Example

```tsx
import * as React from "react";
import { BackupList, BlockList } from "@twentyfirstmedia/halo";

export default function Preview() {
  return (
    <div
      className="tf-grid"
      style={
        {
          "--cols": "1fr 1fr",
          gap: 16,
          alignItems: "start",
        } as React.CSSProperties
      }
    >
      <div className="tf-panel tf-panel-flush tf-panel-list">
        <BackupList
          onDownload={() => {}}
          onRestore={() => {}}
          footer="Kept for 30 days · restore test passed Nov 2"
          items={[
            {
              id: 1,
              name: "Today 03:00",
              kind: "Database",
              where: "R2 Frankfurt",
              size: "1.84 GB",
              status: "ok",
            },
            {
              id: 2,
              name: "Yesterday 03:00",
              kind: "Database",
              where: "R2 Frankfurt",
              size: "1.83 GB",
              status: "ok",
            },
            {
              id: 3,
              name: "Sun 03:00",
              kind: "Files",
              where: "R2 Frankfurt",
              size: "12.4 GB",
              status: "warn",
            },
          ]}
        />
      </div>
      <div className="tf-panel">
        <BlockList
          onAdd={() => {}}
          onRemove={() => {}}
          items={[
            {
              id: 1,
              value: "185.220.101.4",
              kind: "IP",
              reason: "Card testing",
              by: "Fraud rule",
              until: "Nov 15",
            },
            {
              id: 2,
              value: "spam@mailinator.com",
              kind: "Email",
              reason: "Chargeback",
              by: "Lukas",
            },
            {
              id: 3,
              value: "@growthhacker_xx",
              kind: "Account",
              reason: "Abuse",
              by: "Mara Ellis",
              until: "Dec 1",
            },
          ]}
        />
      </div>
    </div>
  );
}
```

### Props

#### BackupList

| Prop | Type | Notes |
| --- | --- | --- |
| `items` | `{ id: string \| number; name?: string; time?: string; kind?: string; where?: string; retention?: string; size?: string; status?: Status; }[]` | Required |
| `onDownload?` | `(b: NonNullable<BackupListProps["items"]>[number]) => void` |  |
| `onRestore?` | `(b: NonNullable<BackupListProps["items"]>[number]) => void` |  |
| `footer?` | `ReactNode` |  |
| `label?` | `string` |  |
| `className?` | `string` | Extra class on the root element. |
| `style?` | `CSSProperties` | Inline style on the root element. |

#### BlockList

| Prop | Type | Notes |
| --- | --- | --- |
| `items` | `{ id: string \| number; value: string; kind?: string; reason?: string; by?: string; until?: string; }[]` | Required |
| `onAdd?` | `() => void` |  |
| `onRemove?` | `(b: NonNullable<BlockListProps["items"]>[number]) => void` |  |
| `addLabel?` | `string` |  |
| `removeLabel?` | `string` |  |
| `searchPlaceholder?` | `string` |  |
| `emptyText?` | `string` |  |
| `className?` | `string` | Extra class on the root element. |
| `style?` | `CSSProperties` | Inline style on the root element. |


## Balance Card

> Prepaid balances at providers and the health of the services the shop depends on: BalanceCard and ServiceMonitor.

Component · Admin · Halo kit · [Live page](https://ui.twentyfirst.media/halo/components/BalanceCard/)

Prepaid balances at providers and the health of the services the shop depends on: `BalanceCard` and `ServiceMonitor`.

BalanceCard: `name`, `sub`, `logo` or `icon` + `tint`, `balance`, `currency`, `perDay` (burn rate → "lasts about n days"), `low` (warning threshold), `spark`, `status` / `statusLabel` (override), `onTopUp`, `topUpLabel`, `action`.
ServiceMonitor: `items` ({id, name, status, statusLabel, latency (ms), errorRate (%), checked, history (statuses, oldest first)}), `label`.

### Example

```tsx
import * as React from "react";
import { BalanceCard, ServiceMonitor } from "@twentyfirstmedia/halo";

export default function Preview() {
  return (
    <div
      className="tf-col"
      style={{
        gap: 16,
      }}
    >
      <div
        className="tf-grid"
        style={
          {
            "--cols": "repeat(3, minmax(0, 1fr))",
            gap: 16,
          } as React.CSSProperties
        }
      >
        <BalanceCard
          name="Provider A"
          sub="Followers, likes"
          balance={1840.5}
          perDay={212}
          low={500}
          spark={[2400, 2300, 2150, 2020, 1990, 1910, 1840]}
          onTopUp={() => {}}
        />
        <BalanceCard
          name="Provider B"
          sub="Views"
          balance={310.2}
          perDay={96}
          low={400}
          spark={[900, 780, 640, 520, 470, 380, 310]}
          onTopUp={() => {}}
        />
        <BalanceCard
          name="SMS gateway"
          sub="Verification codes"
          balance={0}
          perDay={4.1}
          low={20}
          icon="phone"
          tint="sky"
          onTopUp={() => {}}
        />
      </div>
      <div className="tf-panel tf-panel-flush tf-panel-list">
        <ServiceMonitor
          items={[
            {
              name: "Checkout",
              status: "ok",
              statusLabel: "Operational",
              latency: 182,
              errorRate: 0.2,
              checked: "30 s ago",
              history: ["ok", "ok", "ok", "ok", "ok", "ok", "ok", "ok", "ok", "ok", "ok", "ok"],
            },
            {
              name: "Provider A API",
              status: "warn",
              statusLabel: "Slow",
              latency: 2310,
              errorRate: 3.4,
              checked: "30 s ago",
              history: [
                "ok",
                "ok",
                "ok",
                "warn",
                "ok",
                "ok",
                "warn",
                "warn",
                "ok",
                "warn",
                "warn",
                "warn",
              ],
            },
            {
              name: "Mail delivery",
              status: "danger",
              statusLabel: "Down",
              latency: null,
              errorRate: 100,
              checked: "1 min ago",
              history: [
                "ok",
                "ok",
                "ok",
                "ok",
                "ok",
                "ok",
                "ok",
                "ok",
                "ok",
                "danger",
                "danger",
                "danger",
              ],
            },
          ]}
        />
      </div>
    </div>
  );
}
```

### Props

#### BalanceCard

| Prop | Type | Notes |
| --- | --- | --- |
| `name` | `string` | Required |
| `sub?` | `ReactNode` |  |
| `logo?` | `ReactNode` |  |
| `icon?` | `IconName` |  |
| `tint?` | `Tint` |  |
| `balance` | `number` | Required |
| `currency?` | `string` |  |
| `perDay?` | `number` |  |
| `low?` | `number` |  |
| `spark?` | `number[]` |  |
| `status?` | `Status` |  |
| `statusLabel?` | `string` |  |
| `onTopUp?` | `() => void` |  |
| `topUpLabel?` | `string` |  |
| `action?` | `ReactNode` |  |
| `className?` | `string` | Extra class on the root element. |
| `style?` | `CSSProperties` | Inline style on the root element. |

#### ServiceMonitor

| Prop | Type | Notes |
| --- | --- | --- |
| `items` | `{ id?: string; name: string; status: Status; statusLabel?: string; latency?: number \| null; errorRate?: number \| null; checked?: string; history?: (Status \| "none")[]; }[]` | Required |
| `label?` | `string` |  |
| `className?` | `string` | Extra class on the root element. |
| `style?` | `CSSProperties` | Inline style on the root element. |


## Bar Chart

> Charts in Twentyfirst UI.

Component · Charts · Halo kit · [Live page](https://ui.twentyfirst.media/halo/components/BarChart/)

### Example

```tsx
import { BarChart } from "@twentyfirstmedia/halo";

export default function Preview() {
  return (
    <div
      className="tf-panel"
      style={{
        maxWidth: 620,
      }}
    >
      <BarChart
        data={[
          {
            label: "Mon",
            value: 32,
          },
          {
            label: "Tue",
            value: 48,
          },
          {
            label: "Wed",
            value: 41,
          },
          {
            label: "Thu",
            value: 66,
            tint: "lilac",
          },
          {
            label: "Fri",
            value: 58,
          },
          {
            label: "Sat",
            value: 22,
          },
          {
            label: "Sun",
            value: 18,
          },
        ]}
      />
    </div>
  );
}
```

### Props

#### BarChart

| Prop | Type | Notes |
| --- | --- | --- |
| `data` | `{ label: string; value: number; tint?: Tint \| "ink" }[]` | Required |
| `tint?` | `Tint \| "ink"` |  |
| `height?` | `number` |  |
| `width?` | `number` |  |
| `barWidth?` | `number` |  |
| `format?` | `(v: number) => string` |  |
| `label?` | `string` |  |
| `className?` | `string` | Extra class on the root element. |
| `style?` | `CSSProperties` | Inline style on the root element. |


## Card

> Data in Twentyfirst UI.

Component · Data · Halo kit · [Live page](https://ui.twentyfirst.media/halo/components/Card/)

### Example

```tsx
import * as React from "react";
import { Badge, Button, Card, IconButton, Stagger, TintIcon } from "@twentyfirstmedia/halo";

export default function Preview() {
  return (
    <Stagger
      className="tf-grid"
      style={
        {
          "--cols": "repeat(3, 1fr)",
        } as React.CSSProperties
      }
    >
      <Card
        title="Quarterly onboarding"
        description="Welcome flow for new workspace admins."
        meta={["Mara Ellis", "12 steps", "348 users"]}
        corner={<TintIcon icon="book" tint="mint" />}
        status={<Badge tone="success">Live</Badge>}
        actions={[
          <IconButton key={1} icon="more" label="More" size="sm" />,
          <IconButton key={2} icon="x" label="Archive" size="sm" />,
          <IconButton key={3} icon="check" label="Approve" size="sm" variant="solid" />,
        ]}
      />
      <Card
        tint="lilac"
        title="Pricing page refresh"
        description="New tiers and a comparison table for annual plans."
        corner={<IconButton icon="play" label="Preview" size="sm" variant="outline" />}
        status={<Badge tone="neutral">86 viewing</Badge>}
        actions={[<IconButton key={1} icon="edit" label="Edit" size="sm" variant="solid" />]}
      />
      <Card
        title="Invoice #2041 is overdue"
        description="Net-30 passed four days ago; reminder bounced."
        meta={["Rui Costa", "High priority"]}
        corner={<TintIcon icon="mail" tint="blush" />}
        status={<Badge tone="warning">Open</Badge>}
        actions={[
          <Button key={1} size="sm" variant="soft">
            Reply
          </Button>,
        ]}
      />
    </Stagger>
  );
}
```

### Props

#### Badge

| Prop | Type | Notes |
| --- | --- | --- |
| `tone?` | `Tone` |  |
| `dot?` | `boolean` |  |
| `live?` | `boolean` |  |
| `children?` | `ReactNode` |  |
| `className?` | `string` | Extra class on the root element. |
| `style?` | `CSSProperties` | Inline style on the root element. |

#### Button

| Prop | Type | Notes |
| --- | --- | --- |
| `variant?` | `"primary" \| "secondary" \| "soft" \| "ghost" \| "danger" \| "danger-solid"` |  |
| `size?` | `"md" \| "sm"` |  |
| `icon?` | `IconName` |  |
| `iconRight?` | `IconName` |  |
| `disabled?` | `boolean` |  |
| `type?` | `"button" \| "submit" \| "reset"` |  |
| `onClick?` | `(e: MouseEvent<HTMLButtonElement>) => void` |  |
| `children?` | `ReactNode` |  |
| `asChild?` | `boolean` | Render the single child element (a link, a router Link) with the button's look instead of a <button>. |
| `id?` | `string` |  |
| `name?` | `string` | Form field name and value, sent with the form when this button submits it. |
| `value?` | `string` |  |
| `form?` | `string` | The id of the form this button belongs to, when it sits outside it. |
| `title?` | `string` |  |
| `tabIndex?` | `number` |  |
| `autoFocus?` | `boolean` |  |
| `aria-label?` | `string` |  |
| `aria-labelledby?` | `string` |  |
| `aria-describedby?` | `string` |  |
| `aria-expanded?` | `boolean \| "true" \| "false"` | For disclosure and menu triggers: whether what the button controls is open. |
| `aria-controls?` | `string` |  |
| `aria-haspopup?` | `boolean \| "true" \| "false" \| "menu" \| "listbox" \| "tree" \| "grid" \| "dialog"` |  |
| `aria-pressed?` | `boolean \| "true" \| "false" \| "mixed"` | For toggle buttons. |
| `aria-current?` | `boolean \| "true" \| "false" \| "page" \| "step" \| "location" \| "date" \| "time"` |  |
| `className?` | `string` | Extra class on the root element. |
| `style?` | `CSSProperties` | Inline style on the root element. |

#### Card

| Prop | Type | Notes |
| --- | --- | --- |
| `title?` | `string` |  |
| `description?` | `string` |  |
| `meta?` | `string[]` |  |
| `corner?` | `ReactNode` |  |
| `status?` | `ReactNode` |  |
| `actions?` | `ReactNode[]` |  |
| `tint?` | `Tint \| "surface"` |  |
| `onClick?` | `() => void` |  |
| `children?` | `ReactNode` |  |
| `eyebrow?` | `ReactNode` |  |
| `surface?` | `Surface` | `"glass"`: translucent glass over what is behind (maps, 3D, video, photos); `"solid"` opts out inside a glass `UIProvider`. |
| `className?` | `string` | Extra class on the root element. |
| `style?` | `CSSProperties` | Inline style on the root element. |

#### IconButton

| Prop | Type | Notes |
| --- | --- | --- |
| `icon` | `IconName` | Required |
| `label` | `string` | Accessible name and tooltip (`aria-label` and `title`); `aria-label` or `title` override them. |
| `variant?` | `"soft" \| "solid" \| "outline" \| "ghost"` |  |
| `size?` | `"sm" \| "md" \| "lg"` |  |
| `type?` | `"button" \| "submit" \| "reset"` |  |
| `onClick?` | `(e: MouseEvent<HTMLButtonElement>) => void` |  |
| `disabled?` | `boolean` |  |
| `asChild?` | `boolean` | Render the single child element (a link) with the button's look; the icon is placed inside it. |
| `children?` | `ReactNode` |  |
| `id?` | `string` |  |
| `name?` | `string` | Form field name and value, sent with the form when this button submits it. |
| `value?` | `string` |  |
| `form?` | `string` | The id of the form this button belongs to, when it sits outside it. |
| `title?` | `string` |  |
| `tabIndex?` | `number` |  |
| `autoFocus?` | `boolean` |  |
| `aria-label?` | `string` |  |
| `aria-labelledby?` | `string` |  |
| `aria-describedby?` | `string` |  |
| `aria-expanded?` | `boolean \| "true" \| "false"` | For disclosure and menu triggers: whether what the button controls is open. |
| `aria-controls?` | `string` |  |
| `aria-haspopup?` | `boolean \| "true" \| "false" \| "menu" \| "listbox" \| "tree" \| "grid" \| "dialog"` |  |
| `aria-pressed?` | `boolean \| "true" \| "false" \| "mixed"` | For toggle buttons. |
| `aria-current?` | `boolean \| "true" \| "false" \| "page" \| "step" \| "location" \| "date" \| "time"` |  |
| `className?` | `string` | Extra class on the root element. |
| `style?` | `CSSProperties` | Inline style on the root element. |

#### Stagger

| Prop | Type | Notes |
| --- | --- | --- |
| `as?` | `string` |  |
| `className?` | `string` |  |
| `style?` | `CSSProperties` |  |
| `delay?` | `number` | Extra delay before the first child, in ms. |
| `reveal?` | `boolean` | Below the fold, wait until the group scrolls into view (default true). |
| `children?` | `ReactNode` |  |

#### TintIcon

| Prop | Type | Notes |
| --- | --- | --- |
| `icon` | `IconName` | Required |
| `tint?` | `Tint \| "plain"` |  |
| `label?` | `string` |  |
| `size?` | `number` |  |
| `className?` | `string` | Extra class on the root element. |
| `style?` | `CSSProperties` | Inline style on the root element. |


## Chat Launcher

> Site-wide chrome for customer-facing apps: ChatLauncher (floating assistant with page context), CookieConsent and AnnouncementBar.

Component · Overlays · Halo kit · [Live page](https://ui.twentyfirst.media/halo/components/ChatLauncher/)

Site-wide chrome for customer-facing apps: `ChatLauncher` (floating assistant with page context), `CookieConsent` and `AnnouncementBar`.

ChatLauncher: `title`, `context` (what the assistant is looking at), `tint`, `open` / `onOpenChange`, `unread`, `headerAction`, children (the thread), `composer`, `inline` (for previews; fixed bottom-right by default).
CookieConsent: `title`, `text`, `policy` (link), `categories` ({id, label, text, required, default}), `onSave(choices)`, `open`, `inline`. "Accept all" and "Only necessary" carry equal weight.
AnnouncementBar: children, `tint`, `icon`, `action`, `onDismiss` (false hides the close button).

### Example

```tsx
import * as React from "react";
import {
  AnnouncementBar,
  ChatLauncher,
  ChatMessage,
  Composer,
  CookieConsent,
  PromptStarters,
} from "@twentyfirstmedia/halo";

function App() {
  const o = React.useState(true);
  return (
    <div
      className="tf-col"
      style={{
        gap: 16,
      }}
    >
      <AnnouncementBar tint="butter" action={<a href="#">See plans</a>}>
        Free plan: 3 stagings left this month.
      </AnnouncementBar>
      <div
        className="tf-grid"
        style={
          {
            "--cols": "1fr 1fr",
            gap: 16,
            alignItems: "end",
          } as React.CSSProperties
        }
      >
        <CookieConsent
          inline
          policy={<a href="#">Privacy policy</a>}
          categories={[
            {
              id: "necessary",
              label: "Necessary",
              text: "Sign-in, security, cart",
              required: true,
            },
            {
              id: "stats",
              label: "Statistics",
              text: "Anonymous usage numbers",
            },
            {
              id: "marketing",
              label: "Marketing",
              text: "Ads and remarketing",
            },
          ]}
          onSave={() => {}}
        />
        <div
          style={{
            display: "flex",
            justifyContent: "flex-end",
          }}
        >
          <ChatLauncher
            inline
            open={o[0]}
            onOpenChange={o[1]}
            title="Homefield assistant"
            context="Looking at: Loft in HafenCity"
            composer={<Composer placeholder="Ask about this listing…" />}
          >
            <ChatMessage
              role="assistant"
              name="Assistant"
              text="This loft is about **4% above** the estimated value. Want me to draft a first message to the agent?"
            />
            <PromptStarters
              items={[
                {
                  title: "Draft a message",
                  icon: "mail",
                },
                {
                  title: "Compare with similar",
                  icon: "chart",
                },
              ]}
            />
          </ChatLauncher>
        </div>
      </div>
    </div>
  );
}
export default App;
```

### Props

#### AnnouncementBar

| Prop | Type | Notes |
| --- | --- | --- |
| `children` | `ReactNode` | Required |
| `tint?` | `Tint` |  |
| `icon?` | `IconName \| false` |  |
| `action?` | `ReactNode` |  |
| `onDismiss?` | `(() => void) \| false` |  |
| `className?` | `string` | Extra class on the root element. |
| `style?` | `CSSProperties` | Inline style on the root element. |

#### ChatLauncher

| Prop | Type | Notes |
| --- | --- | --- |
| `title?` | `string` |  |
| `context?` | `ReactNode` |  |
| `tint?` | `Tint` |  |
| `open?` | `boolean` |  |
| `onOpenChange?` | `(open: boolean) => void` |  |
| `unread?` | `number` |  |
| `headerAction?` | `ReactNode` |  |
| `children?` | `ReactNode` |  |
| `composer?` | `ReactNode` |  |
| `inline?` | `boolean` |  |
| `className?` | `string` | Extra class on the root element. |
| `style?` | `CSSProperties` | Inline style on the root element. |

#### ChatMessage

| Prop | Type | Notes |
| --- | --- | --- |
| `role` | `"user" \| "assistant" \| "system"` | Required |
| `name?` | `string` |  |
| `time?` | `string` |  |
| `model?` | `string` |  |
| `text?` | `string` |  |
| `streaming?` | `boolean` |  |
| `tint?` | `Tint` |  |
| `sources?` | `Source[]` |  |
| `attachments?` | `{ name: string; size?: string; kind?: string }[]` |  |
| `usage?` | `string` |  |
| `onRetry?` | `() => void` |  |
| `onFeedback?` | `(v: "up" \| "down") => void` |  |
| `actions?` | `boolean` |  |
| `before?` | `ReactNode` |  |
| `after?` | `ReactNode` |  |
| `children?` | `ReactNode` |  |
| `feedback?` | `"up" \| "down" \| null` |  |
| `className?` | `string` | Extra class on the root element. |
| `style?` | `CSSProperties` | Inline style on the root element. |

#### Composer

| Prop | Type | Notes |
| --- | --- | --- |
| `value?` | `string` |  |
| `onChange?` | `(v: string) => void` |  |
| `onSend?` | `(text: string, files: (File \| { name: string })[]) => void` |  |
| `busy?` | `boolean` |  |
| `onStop?` | `() => void` |  |
| `placeholder?` | `string` |  |
| `label?` | `string` |  |
| `models?` | `ModelOption[]` |  |
| `model?` | `string` |  |
| `onModel?` | `(id: string) => void` |  |
| `commands?` | `ComposerCommand[]` |  |
| `onCommand?` | `(c: ComposerCommand) => void` |  |
| `attachments?` | `(File \| { name: string })[]` |  |
| `onAttach?` | `(files: FileList) => void` |  |
| `onRemoveAttachment?` | `(i: number) => void` |  |
| `hint?` | `string` |  |
| `left?` | `ReactNode` |  |
| `disabled?` | `boolean` |  |
| `className?` | `string` | Extra class on the root element. |
| `style?` | `CSSProperties` | Inline style on the root element. |

#### CookieConsent

| Prop | Type | Notes |
| --- | --- | --- |
| `title?` | `string` |  |
| `text?` | `ReactNode` |  |
| `policy?` | `ReactNode` |  |
| `categories?` | `{ id: string; label: string; /** What the category covers; may hold a link to the details. */ text?: ReactNode; required?: boolean; default?: boolean; }[]` |  |
| `onSave?` | `(choices: Record<string, boolean>) => void` |  |
| `open?` | `boolean` |  |
| `inline?` | `boolean` |  |
| `equalChoice?` | `boolean` | "Only necessary" and "Accept all" with the same weight (both secondary buttons), as German data protection authorities expect on the first layer. |
| `id?` | `string` | Id of the banner (its text is referenced by `aria-describedby`). |
| `className?` | `string` | Extra class on the root element. |
| `style?` | `CSSProperties` | Inline style on the root element. |

#### PromptStarters

| Prop | Type | Notes |
| --- | --- | --- |
| `items` | `{ icon?: IconName; tint?: Tint; title: string; text?: string; prompt?: string }[]` | Required |
| `onPick?` | `(prompt: string) => void` |  |
| `className?` | `string` | Extra class on the root element. |
| `style?` | `CSSProperties` | Inline style on the root element. |


## Chat Message

> One turn in a conversation with an agent: user bubble on the right, agent reply as rich text on the left.

Component · AI · Halo kit · [Live page](https://ui.twentyfirst.media/halo/components/ChatMessage/)

One turn in a conversation with an agent: user bubble on the right, agent reply as rich text on the left.

Props: `role` ("user" | "assistant" | "system"), `name`, `time`, `model`, `text` (Markdown subset: paragraphs, **bold**, `code`, - lists, 1. lists, ### headings, links, ``` code blocks), `streaming` (blinking caret, no actions yet), `tint` (agent color), `sources` ({title, icon, url | onClick}), `attachments` ({name, size}), `usage` (tokens · cost text), `onRetry`, `onFeedback("up" | "down")`, `actions` (false hides the row), `before` / `after` (slots for tool calls, reasoning, approvals).

- User messages are ink pills, agent replies are plain text on the surface: the agent's words get the space.
- Actions (copy, regenerate, thumbs) appear once streaming ends.
- Number sources in the order they were used; keep titles short.
- `RichText` and `CodeBlock` are exported on their own for docs, notes and logs.

### Example

```tsx
import { ChatMessage } from "@twentyfirstmedia/halo";

const md =
  'Three invoices are overdue, **€2,520** in total:\n\n- **#2041** Harbor & Co · €860\n- **#2058** Pinegate · €1,240\n- **#2063** Orbit Foods · €420\n\nThe fix for the reminder job:\n\n```ts\nconst due = invoices.filter(i => i.dueAt < now && !i.paid);\nawait sendReminders(due, { tone: "friendly" });\n```';
export default function Preview() {
  return (
    <div
      className="tf-panel"
      style={{
        gap: 24,
      }}
    >
      <ChatMessage
        role="user"
        name="Mara Ellis"
        text="Which invoices are overdue? Fix the reminder job too."
        attachments={[
          {
            name: "reminders.ts",
            size: "4 KB",
          },
        ]}
      />
      <ChatMessage
        role="assistant"
        name="Ledger"
        tint="butter"
        time="09:41"
        model="Claude Sonnet 5.5"
        text={md}
        sources={[
          {
            title: "Invoices · due",
            icon: "card",
          },
          {
            title: "jobs/reminders.ts",
            icon: "code",
          },
        ]}
        usage="1,842 tokens · €0.01"
        onRetry={() => {}}
      />
      <ChatMessage role="system" text="Ledger switched to Claude Haiku 5.5" />
      <ChatMessage
        role="assistant"
        name="Ledger"
        tint="butter"
        streaming
        text={"Sending reminders now. Harbor & Co first because"}
      />
    </div>
  );
}
```

### Props

#### ChatMessage

| Prop | Type | Notes |
| --- | --- | --- |
| `role` | `"user" \| "assistant" \| "system"` | Required |
| `name?` | `string` |  |
| `time?` | `string` |  |
| `model?` | `string` |  |
| `text?` | `string` |  |
| `streaming?` | `boolean` |  |
| `tint?` | `Tint` |  |
| `sources?` | `Source[]` |  |
| `attachments?` | `{ name: string; size?: string; kind?: string }[]` |  |
| `usage?` | `string` |  |
| `onRetry?` | `() => void` |  |
| `onFeedback?` | `(v: "up" \| "down") => void` |  |
| `actions?` | `boolean` |  |
| `before?` | `ReactNode` |  |
| `after?` | `ReactNode` |  |
| `children?` | `ReactNode` |  |
| `feedback?` | `"up" \| "down" \| null` |  |
| `className?` | `string` | Extra class on the root element. |
| `style?` | `CSSProperties` | Inline style on the root element. |


## Chat Workspace

> Messenger-style workspace for agents and people: ChatWorkspace (list | thread | details), ChatList, SearchHits, ThinkingLine, FeedbackRating.

Component · AI · Halo kit · [Live page](https://ui.twentyfirst.media/halo/components/ChatWorkspace/)

Messenger-style workspace for agents and people: `ChatWorkspace` (list | thread | details), `ChatList`, `SearchHits`, `ThinkingLine`, `FeedbackRating`.

ChatWorkspace: `list`, `thread`, `details` (third column, hidden on narrow screens).
ChatList: `groups` ({title, mark (tint), items: {id, name, sub, time, tint, avatar, status, unread, pinned}}), `selected`, `onSelect`, `onSearch`, `filters`, `searchPlaceholder`. Order: pinned first, then one group per project, then people.
SearchHits: `items` ({id, chat, time, who, text}), `query` (marked), `onOpen`.
ThinkingLine: `text` ("Reading 3 mails…"). FeedbackRating: `value` / `onRate`, `onSubmit(value, comment)`, `label`, `placeholder`, `thanks`, `askOnUp`.

### Example

```tsx
import * as React from "react";
import {
  ChatList,
  ChatMessage,
  ChatWorkspace,
  FeedbackRating,
  SearchHits,
  ThinkingLine,
} from "@twentyfirstmedia/halo";
import type { ChatListProps } from "@twentyfirstmedia/halo";

const groups: ChatListProps["groups"] = [
  {
    title: "Pinned",
    items: [
      {
        id: "mb",
        name: "Main Brain",
        sub: "Morning briefing is ready",
        time: "08:00",
        tint: "lilac",
        status: "ok",
        pinned: true,
      },
    ],
  },
  {
    title: "Northwind",
    mark: "sky",
    items: [
      {
        id: "atlas",
        name: "Atlas",
        sub: "Waiting for your approval",
        time: "09:41",
        tint: "sky",
        status: "signal",
        unread: 1,
      },
      {
        id: "ads",
        name: "Ads",
        sub: "Budget at 82%",
        time: "09:12",
        tint: "mint",
        status: "warn",
      },
    ],
  },
  {
    title: "People",
    items: [
      {
        id: "lukas",
        name: "Lukas Weber",
        sub: "Sounds good",
        time: "Mon",
        avatar: true,
      },
    ],
  },
];
function App() {
  const s = React.useState("atlas");
  return (
    <div
      style={{
        height: 580,
      }}
    >
      <ChatWorkspace
        className="demo-fill"
        list={<ChatList groups={groups} selected={s[0]} onSelect={s[1]} />}
        thread={
          <div
            className="tf-col"
            style={{
              gap: 20,
            }}
          >
            <ChatMessage role="user" text="Draft a reply to Northwind" />
            <ChatMessage
              role="assistant"
              name="Atlas"
              tint="sky"
              time="09:41"
              text="Drafted. It quotes **40 seats at €24** prorated to May 1."
            />
            <ThinkingLine text="Reading 3 messages…" />
            <FeedbackRating label="Was this useful?" />
          </div>
        }
        details={
          <SearchHits
            query="seats"
            items={[
              {
                id: 1,
                chat: "Atlas",
                time: "09:41",
                who: "Atlas",
                text: "It quotes 40 seats at €24 prorated to May 1.",
              },
              {
                id: 2,
                chat: "Main Brain",
                time: "Mon",
                text: "Northwind asked about seats twice this quarter.",
              },
            ]}
          />
        }
      />
    </div>
  );
}
export default App;
```

### Props

#### ChatList

| Prop | Type | Notes |
| --- | --- | --- |
| `groups` | `{ title: string; mark?: Tint; items: ChatListItem[] }[]` | Required |
| `selected?` | `string` |  |
| `onSelect?` | `(id: string) => void` |  |
| `onSearch?` | `(q: string) => void` |  |
| `filters?` | `ReactNode` |  |
| `searchPlaceholder?` | `string` |  |
| `className?` | `string` | Extra class on the root element. |
| `style?` | `CSSProperties` | Inline style on the root element. |

#### ChatMessage

| Prop | Type | Notes |
| --- | --- | --- |
| `role` | `"user" \| "assistant" \| "system"` | Required |
| `name?` | `string` |  |
| `time?` | `string` |  |
| `model?` | `string` |  |
| `text?` | `string` |  |
| `streaming?` | `boolean` |  |
| `tint?` | `Tint` |  |
| `sources?` | `Source[]` |  |
| `attachments?` | `{ name: string; size?: string; kind?: string }[]` |  |
| `usage?` | `string` |  |
| `onRetry?` | `() => void` |  |
| `onFeedback?` | `(v: "up" \| "down") => void` |  |
| `actions?` | `boolean` |  |
| `before?` | `ReactNode` |  |
| `after?` | `ReactNode` |  |
| `children?` | `ReactNode` |  |
| `feedback?` | `"up" \| "down" \| null` |  |
| `className?` | `string` | Extra class on the root element. |
| `style?` | `CSSProperties` | Inline style on the root element. |

#### ChatWorkspace

| Prop | Type | Notes |
| --- | --- | --- |
| `list` | `ReactNode` | Required |
| `thread` | `ReactNode` | Required |
| `details?` | `ReactNode` |  |
| `className?` | `string` |  |
| `style?` | `CSSProperties` | Inline style on the root element. |

#### FeedbackRating

| Prop | Type | Notes |
| --- | --- | --- |
| `value?` | `"up" \| "down" \| null` |  |
| `onRate?` | `(v: "up" \| "down") => void` |  |
| `onSubmit?` | `(v: "up" \| "down", comment?: string) => void` |  |
| `label?` | `string` |  |
| `placeholder?` | `string` |  |
| `thanks?` | `string` |  |
| `askOnUp?` | `boolean` |  |
| `className?` | `string` | Extra class on the root element. |
| `style?` | `CSSProperties` | Inline style on the root element. |

#### SearchHits

| Prop | Type | Notes |
| --- | --- | --- |
| `items` | `{ id: string \| number; chat: string; time?: string; who?: string; text: string }[]` | Required |
| `query?` | `string` |  |
| `onOpen?` | `(item: NonNullable<SearchHitsProps["items"]>[number]) => void` |  |
| `emptyText?` | `string` |  |
| `className?` | `string` | Extra class on the root element. |
| `style?` | `CSSProperties` | Inline style on the root element. |

#### ThinkingLine

| Prop | Type | Notes |
| --- | --- | --- |
| `text?` | `string` |  |
| `className?` | `string` | Extra class on the root element. |
| `style?` | `CSSProperties` | Inline style on the root element. |


## Combobox

> Searchable select for long lists, single or multiple, with optional create.

Component · Forms · Halo kit · [Live page](https://ui.twentyfirst.media/halo/components/Combobox/)

Searchable select for long lists, single or multiple, with optional create. `TagInput` is the free-text sibling for tags.

Combobox props: `label`, `options` (strings or {value, label, hint, icon, avatar}), `value`/`defaultValue`, `onChange`, `multiple`, `creatable`, `placeholder`, `hint`, `error`, `required`.
TagInput props: `label`, `value`/`defaultValue` (string[]), `onChange`, `placeholder`, `hint`.

- Keyboard: ↑ ↓ to move, Enter to pick, Esc to close, Backspace removes the last token.
- Up to five fixed options without search: use RadioGroup or a native Select instead.
- Selected items in `multiple` show as tokens inside the field; keep their labels short.
- Show a `hint` on people (team, email) so two people with the same name can be told apart.

### Example

```tsx
import * as React from "react";
import { Combobox, TagInput } from "@twentyfirstmedia/halo";

const TZ = [
  "Europe/Berlin (UTC+1)",
  "Europe/London (UTC+0)",
  "Asia/Dubai (UTC+4)",
  "Asia/Singapore (UTC+8)",
  "America/New_York (UTC−5)",
  "America/Los_Angeles (UTC−8)",
];
const PEOPLE = [
  {
    value: "ava",
    label: "Ava Vogel",
    hint: "Engineering",
    avatar: true,
  },
  {
    value: "ben",
    label: "Ben Okafor",
    hint: "Sales",
    avatar: true,
  },
  {
    value: "clara",
    label: "Clara Haddad",
    hint: "Design",
    avatar: true,
  },
  {
    value: "elif",
    label: "Elif Sato",
    hint: "Engineering",
    avatar: true,
  },
];
function App() {
  const t = React.useState<string | string[] | null>("Asia/Dubai (UTC+4)"),
    p = React.useState<string | string[] | null>(["ava", "clara"]),
    tags = React.useState(["urgent", "q3"]);
  return (
    <div
      className="tf-panel tf-grid"
      style={
        {
          "--cols": "1fr 1fr",
          gap: 16,
          alignContent: "start",
        } as React.CSSProperties
      }
    >
      <Combobox
        label="Time zone"
        options={TZ}
        value={t[0]}
        onChange={t[1]}
        placeholder="Search time zones"
      />
      <Combobox
        label="Reviewers"
        multiple
        options={PEOPLE}
        value={p[0]}
        onChange={p[1]}
        placeholder="Add people"
      />
      <Combobox
        label="Label"
        creatable
        options={["Customers", "Agents", "Finance"]}
        placeholder="Pick or create"
        hint="Type a new name to create it"
      />
      <TagInput label="Tags" value={tags[0]} onChange={tags[1]} />
    </div>
  );
}
export default App;
```

### Props

#### Combobox

| Prop | Type | Notes |
| --- | --- | --- |
| `label?` | `string` |  |
| `options` | `(string \| Option)[]` | Required |
| `value?` | `string \| string[] \| null` |  |
| `defaultValue?` | `string \| string[]` |  |
| `onChange?` | `(v: string \| string[] \| null) => void` |  |
| `multiple?` | `boolean` |  |
| `creatable?` | `boolean` |  |
| `placeholder?` | `string` |  |
| `hint?` | `string` |  |
| `error?` | `string` |  |
| `required?` | `boolean` |  |
| `className?` | `string` | Extra class on the root element. |
| `style?` | `CSSProperties` | Inline style on the root element. |

#### TagInput

| Prop | Type | Notes |
| --- | --- | --- |
| `label?` | `string` |  |
| `value?` | `string[]` |  |
| `defaultValue?` | `string[]` |  |
| `onChange?` | `(v: string[]) => void` |  |
| `placeholder?` | `string` |  |
| `hint?` | `string` |  |
| `error?` | `string` |  |
| `className?` | `string` | Extra class on the root element. |
| `style?` | `CSSProperties` | Inline style on the root element. |


## Command Palette

> Overlays in Twentyfirst UI.

Component · Overlays · Halo kit · [Live page](https://ui.twentyfirst.media/halo/components/CommandPalette/)

### Example

```tsx
import { CommandPalette } from "@twentyfirstmedia/halo";

export default function Preview() {
  return (
    <div
      style={{
        position: "relative",
        height: 430,
        borderRadius: "var(--radius-lg)",
        overflow: "hidden",
        background: "var(--canvas)",
      }}
    >
      <CommandPalette
        inline
        onClose={() => {}}
        items={[
          {
            id: 1,
            group: "Pages",
            label: "Invoices",
            hint: "Finance",
            icon: "card",
          },
          {
            id: 2,
            group: "Pages",
            label: "Pipeline",
            hint: "Customers",
            icon: "trend",
          },
          {
            id: 3,
            group: "Actions",
            label: "New invoice",
            icon: "card",
            tint: "butter",
          },
          {
            id: 4,
            group: "Actions",
            label: "Compose mail",
            icon: "edit",
            tint: "sky",
          },
          {
            id: 5,
            group: "Actions",
            label: "New agent",
            icon: "bot",
            tint: "lilac",
          },
          {
            id: 6,
            group: "Records",
            label: "Northwind",
            hint: "Customer · Team",
            icon: "users",
            tint: "sky",
            searchOnly: true,
          },
        ]}
      />
    </div>
  );
}
```

### Props

#### CommandPalette

| Prop | Type | Notes |
| --- | --- | --- |
| `items` | `PaletteItem[]` | Required |
| `onClose?` | `() => void` |  |
| `placeholder?` | `string` |  |
| `inline?` | `boolean` |  |
| `loading?` | `boolean` | Results are on their way (async search): shows a loading row. |
| `empty?` | `ReactNode` | Shown when nothing matches (default: "Nothing matches …"). |
| `onQueryChange?` | `(query: string) => void` | Called with the query as the user types, for searching on a server. |
| `open?` | `boolean` | Optional: with `open` the component stays mounted while it animates out; without it, render it only while open. |
| `className?` | `string` | Extra class on the root element. |
| `style?` | `CSSProperties` | Inline style on the root element. |


## Composer

> Message input for agents: grows with the text, attachments, slash commands, a model picker, and Send that turns into Stop while the agent works.

Component · AI · Halo kit · [Live page](https://ui.twentyfirst.media/halo/components/Composer/)

Message input for agents: grows with the text, attachments, slash commands, a model picker, and Send that turns into Stop while the agent works.

Composer props: `value` / `onChange`, `onSend(text, attachments)`, `busy`, `onStop`, `placeholder`, `models` ({id, label, hint}) + `model` + `onModel`, `commands` ({name, hint, icon, insert}) + `onCommand`, `attachments` + `onAttach(FileList)` + `onRemoveAttachment(i)`, `hint`, `left` (extra tools).
Also here: `PromptStarters` (`items` {icon, tint, title, text, prompt}, `onPick`), `ModelPicker`, `AgentStatus` (`status`, `step`), `UsageMeter` (`used`, `limit`, `format`, `label`, `caption`), `AgentMark`, `TypingDots`.

- Enter sends, Shift+Enter adds a line; typing "/" opens commands (↑ ↓ Enter).
- Drop files anywhere on the composer to attach them.
- Stop must always work: cancel streaming and mark running tools as stopped.
- Show starters only on an empty conversation, three or four, written as things people actually ask.

### Example

```tsx
import * as React from "react";
import { AgentStatus, Composer, PromptStarters, UsageMeter } from "@twentyfirstmedia/halo";

const MODELS = [
  {
    id: "opus",
    label: "Claude Opus 5.5",
    hint: "Deepest reasoning",
  },
  {
    id: "sonnet",
    label: "Claude Sonnet 5.5",
    hint: "Balanced default",
  },
  {
    id: "haiku",
    label: "Claude Haiku 5.5",
    hint: "Fast and cheap",
  },
];
function App() {
  const m = React.useState("sonnet"),
    f = React.useState([
      {
        name: "Q1-report.pdf",
      },
    ]),
    busy = React.useState(false);
  return (
    <div
      className="tf-panel"
      style={{
        gap: 24,
      }}
    >
      <PromptStarters
        items={[
          {
            icon: "edit",
            tint: "sky",
            title: "Draft a reply",
            text: "To the latest customer email",
          },
          {
            icon: "file",
            tint: "mint",
            title: "Summarize today",
            text: "Runs, approvals, costs",
          },
          {
            icon: "search",
            tint: "butter",
            title: "Ask the docs",
            text: "Search the knowledge base",
          },
        ]}
      />
      <Composer
        placeholder="Ask Atlas something, or type / for commands"
        models={MODELS}
        model={m[0]}
        onModel={m[1]}
        attachments={f[0]}
        onAttach={(fl) => {
          f[1](f[0].concat(Array.prototype.slice.call(fl)));
        }}
        onRemoveAttachment={(i) => {
          f[1](f[0].filter((_, k) => k !== i));
        }}
        commands={[
          {
            name: "summarize",
            hint: "Summarize today",
            icon: "file",
          },
          {
            name: "draft",
            hint: "Draft a reply",
            icon: "edit",
          },
          {
            name: "clear",
            hint: "New conversation",
            icon: "trash",
          },
        ]}
        busy={busy[0]}
        onSend={() => {
          busy[1](true);
          setTimeout(() => {
            busy[1](false);
          }, 2500);
        }}
        onStop={() => {
          busy[1](false);
        }}
      />
      <div
        className="tf-row"
        style={{
          justifyContent: "space-between",
        }}
      >
        <AgentStatus
          status={busy[0] ? "Thinking" : "Idle"}
          step={busy[0] ? "Reading 3 messages" : "Drafts only"}
        />
        <div
          style={{
            width: 200,
          }}
        >
          <UsageMeter label="Context" used={21} limit={200} format={(v) => v + "k"} />
        </div>
      </div>
    </div>
  );
}
export default App;
```

### Props

#### AgentStatus

| Prop | Type | Notes |
| --- | --- | --- |
| `status` | `"Running" \| "Thinking" \| "Waiting for approval" \| "Idle" \| "Paused" \| "Error" \| string` | Required |
| `step?` | `string` |  |
| `className?` | `string` | Extra class on the root element. |
| `style?` | `CSSProperties` | Inline style on the root element. |

#### Composer

| Prop | Type | Notes |
| --- | --- | --- |
| `value?` | `string` |  |
| `onChange?` | `(v: string) => void` |  |
| `onSend?` | `(text: string, files: (File \| { name: string })[]) => void` |  |
| `busy?` | `boolean` |  |
| `onStop?` | `() => void` |  |
| `placeholder?` | `string` |  |
| `label?` | `string` |  |
| `models?` | `ModelOption[]` |  |
| `model?` | `string` |  |
| `onModel?` | `(id: string) => void` |  |
| `commands?` | `ComposerCommand[]` |  |
| `onCommand?` | `(c: ComposerCommand) => void` |  |
| `attachments?` | `(File \| { name: string })[]` |  |
| `onAttach?` | `(files: FileList) => void` |  |
| `onRemoveAttachment?` | `(i: number) => void` |  |
| `hint?` | `string` |  |
| `left?` | `ReactNode` |  |
| `disabled?` | `boolean` |  |
| `className?` | `string` | Extra class on the root element. |
| `style?` | `CSSProperties` | Inline style on the root element. |

#### PromptStarters

| Prop | Type | Notes |
| --- | --- | --- |
| `items` | `{ icon?: IconName; tint?: Tint; title: string; text?: string; prompt?: string }[]` | Required |
| `onPick?` | `(prompt: string) => void` |  |
| `className?` | `string` | Extra class on the root element. |
| `style?` | `CSSProperties` | Inline style on the root element. |

#### UsageMeter

| Prop | Type | Notes |
| --- | --- | --- |
| `used` | `number` | Required |
| `limit` | `number` | Required |
| `label?` | `string` |  |
| `caption?` | `string` |  |
| `format?` | `(v: number) => string` |  |
| `className?` | `string` | Extra class on the root element. |
| `style?` | `CSSProperties` | Inline style on the root element. |


## Config PR Summary

> Platform structure: ConfigPRSummary (a proposed config change in plain language) and ModuleRegistry (installed modules).

Component · AI · Halo kit · [Live page](https://ui.twentyfirst.media/halo/components/ConfigPRSummary/)

Platform structure: `ConfigPRSummary` (a proposed config change in plain language) and `ModuleRegistry` (installed modules).

ConfigPRSummary: `title`, `meta`, `status` + `statusLabel`, `summary`, `items` ({kind: "project" | "team" | "agent" | "tool" | "trigger" | "file", name, detail, op: "add" | "change" | "remove"}), `actions`.
ModuleRegistry: `items` ({id, name, version, text, icon, core, enabled, adds}), `onToggle(module)`, `coreLabel`.

### Example

```tsx
import * as React from "react";
import { Button, ConfigPRSummary, ModuleRegistry } from "@twentyfirstmedia/halo";

export default function Preview() {
  return (
    <div
      className="tf-grid"
      style={
        {
          "--cols": "1fr 1fr",
          gap: 16,
          alignItems: "start",
        } as React.CSSProperties
      }
    >
      <ConfigPRSummary
        title="New team: Support for Chatteo"
        meta="Proposed by Main Brain · PR #212"
        status="signal"
        statusLabel="Needs review"
        summary="Adds a support team with two agents. Both start in drafts-only mode."
        items={[
          {
            kind: "team",
            name: "chatteo/support",
          },
          {
            kind: "agent",
            name: "Iris",
            detail: "Mailbox (read, draft) · Knowledge base",
          },
          {
            kind: "agent",
            name: "Nora",
            detail: "WhatsApp (reply within 24 h)",
          },
          {
            kind: "trigger",
            name: "New mail to hello@chatteo.de",
            op: "change",
          },
        ]}
        actions={[
          <Button key="v" variant="secondary" size="sm">
            View PR
          </Button>,
          <Button key="m" size="sm" icon="check">
            Approve
          </Button>,
        ]}
      />
      <div className="tf-panel tf-panel-flush tf-panel-list">
        <ModuleRegistry
          onToggle={() => {}}
          items={[
            {
              id: "chats",
              name: "Chats",
              version: "1.4.0",
              text: "Agents and people in one place",
              core: true,
              icon: "mail",
            },
            {
              id: "crm",
              name: "CRM",
              version: "0.9.2",
              text: "Companies, contacts, pipeline",
              enabled: true,
              icon: "users",
              adds: ["Nav", "Tool", "Jobs"],
            },
            {
              id: "brand",
              name: "Brand studio",
              version: "0.6.0",
              text: "Brand packages for customers",
              enabled: false,
              icon: "sparkle",
              adds: ["Nav", "Tool"],
            },
          ]}
        />
      </div>
    </div>
  );
}
```

### Props

#### Button

| Prop | Type | Notes |
| --- | --- | --- |
| `variant?` | `"primary" \| "secondary" \| "soft" \| "ghost" \| "danger" \| "danger-solid"` |  |
| `size?` | `"md" \| "sm"` |  |
| `icon?` | `IconName` |  |
| `iconRight?` | `IconName` |  |
| `disabled?` | `boolean` |  |
| `type?` | `"button" \| "submit" \| "reset"` |  |
| `onClick?` | `(e: MouseEvent<HTMLButtonElement>) => void` |  |
| `children?` | `ReactNode` |  |
| `asChild?` | `boolean` | Render the single child element (a link, a router Link) with the button's look instead of a <button>. |
| `id?` | `string` |  |
| `name?` | `string` | Form field name and value, sent with the form when this button submits it. |
| `value?` | `string` |  |
| `form?` | `string` | The id of the form this button belongs to, when it sits outside it. |
| `title?` | `string` |  |
| `tabIndex?` | `number` |  |
| `autoFocus?` | `boolean` |  |
| `aria-label?` | `string` |  |
| `aria-labelledby?` | `string` |  |
| `aria-describedby?` | `string` |  |
| `aria-expanded?` | `boolean \| "true" \| "false"` | For disclosure and menu triggers: whether what the button controls is open. |
| `aria-controls?` | `string` |  |
| `aria-haspopup?` | `boolean \| "true" \| "false" \| "menu" \| "listbox" \| "tree" \| "grid" \| "dialog"` |  |
| `aria-pressed?` | `boolean \| "true" \| "false" \| "mixed"` | For toggle buttons. |
| `aria-current?` | `boolean \| "true" \| "false" \| "page" \| "step" \| "location" \| "date" \| "time"` |  |
| `className?` | `string` | Extra class on the root element. |
| `style?` | `CSSProperties` | Inline style on the root element. |

#### ConfigPRSummary

| Prop | Type | Notes |
| --- | --- | --- |
| `title` | `string` | Required |
| `meta?` | `ReactNode` |  |
| `status?` | `Status` |  |
| `statusLabel?` | `string` |  |
| `summary?` | `ReactNode` |  |
| `items` | `{ kind: "project" \| "team" \| "agent" \| "tool" \| "trigger" \| "file"; name: string; detail?: ReactNode; op?: "add" \| "change" \| "remove"; }[]` | Required |
| `actions?` | `ReactNode[]` |  |
| `className?` | `string` | Extra class on the root element. |
| `style?` | `CSSProperties` | Inline style on the root element. |

#### ModuleRegistry

| Prop | Type | Notes |
| --- | --- | --- |
| `items` | `{ id: string; name: string; version?: string; text?: ReactNode; icon?: IconName; core?: boolean; enabled?: boolean; adds?: string[]; }[]` | Required |
| `onToggle?` | `(m: NonNullable<ModuleRegistryProps["items"]>[number]) => void` |  |
| `coreLabel?` | `string` |  |
| `className?` | `string` | Extra class on the root element. |
| `style?` | `CSSProperties` | Inline style on the root element. |


## Confirm Dialog

> Asks before a destructive or hard-to-undo action.

Component · Overlays · Halo kit · [Live page](https://ui.twentyfirst.media/halo/components/ConfirmDialog/)

Asks before a destructive or hard-to-undo action. Focus starts on Cancel; Esc cancels.

Props: `open`, `title` (a question naming the thing), `text` (what happens), `danger`, `icon`, `confirmLabel` (a verb: "Delete domain", never "OK"), `cancelLabel`, `confirmText` (type-to-confirm), `onConfirm`, `onCancel`.

- Prefer undo over confirm: removing a list item is instant with an Undo toast; confirm only when undo is impossible or the blast radius is large.
- Use `confirmText` only for irreversible deletes of whole things (a domain, a workspace).
- Renders into document.body, so it sits above every stacking context.

### Example

```tsx
import { ConfirmDialog } from "@twentyfirstmedia/halo";

function App() {
  return (
    <div
      style={{
        position: "relative",
        height: 360,
        borderRadius: "var(--radius-lg)",
        overflow: "hidden",
        background: "var(--canvas)",
        transform: "translateZ(0)",
      }}
    >
      <ConfirmDialog
        open
        danger
        title="Delete halo.dev?"
        text="DNS records, mailboxes and certificates for this domain are removed. This can’t be undone."
        confirmText="halo.dev"
        confirmLabel="Delete domain"
        onCancel={() => {}}
        onConfirm={() => {}}
      />
    </div>
  );
}
export default App;
```

### Props

#### ConfirmDialog

| Prop | Type | Notes |
| --- | --- | --- |
| `open` | `boolean` | Required |
| `title` | `string` | Required |
| `text?` | `string` |  |
| `danger?` | `boolean` |  |
| `icon?` | `IconName` |  |
| `confirmLabel?` | `string` |  |
| `cancelLabel?` | `string` |  |
| `confirmText?` | `string` |  |
| `onConfirm` | `() => void` | Required |
| `onCancel` | `() => void` | Required |
| `className?` | `string` | Extra class on the root element. |
| `style?` | `CSSProperties` | Inline style on the root element. |


## Connection Card

> Connected services and the live connection: ConnectionCard and ConnectionBanner.

Component · Data · Halo kit · [Live page](https://ui.twentyfirst.media/halo/components/ConnectionCard/)

Connected services and the live connection: `ConnectionCard` and `ConnectionBanner`.

ConnectionCard: `name`, `icon` or `logo` (node, e.g. the service's mark), `text`, `status` ("connected" | "expiring" | "error" | "missing"), `statusLabel`, `action`.
ConnectionBanner: `state` ("reconnecting" | "offline" | "online" hides it), `seconds`, `text`, `onRetry`. Thin bar under the top bar.

### Example

```tsx
import { Button, ConnectionBanner, ConnectionCard } from "@twentyfirstmedia/halo";

export default function Preview() {
  return (
    <div
      className="tf-col"
      style={{
        gap: 8,
      }}
    >
      <ConnectionBanner state="reconnecting" seconds={4} onRetry={() => {}} />
      <ConnectionCard
        name="Stripe · FollowerX GmbH"
        icon="card"
        text="Payments and refunds · 3 agents"
        status="connected"
        statusLabel="Connected"
        action={
          <Button size="sm" variant="soft">
            Manage
          </Button>
        }
      />
      <ConnectionCard
        name="Google Ads"
        icon="trend"
        text="Budgets and campaigns · 1 agent"
        status="expiring"
        statusLabel="Expires in 5 days"
        action={<Button size="sm">Renew</Button>}
      />
      <ConnectionCard
        name="Docs workspace"
        icon="book"
        text="Release notes · Echo"
        status="error"
        statusLabel="Error"
        action={<Button size="sm">Reconnect</Button>}
      />
      <ConnectionBanner state="offline" />
    </div>
  );
}
```

### Props

#### Button

| Prop | Type | Notes |
| --- | --- | --- |
| `variant?` | `"primary" \| "secondary" \| "soft" \| "ghost" \| "danger" \| "danger-solid"` |  |
| `size?` | `"md" \| "sm"` |  |
| `icon?` | `IconName` |  |
| `iconRight?` | `IconName` |  |
| `disabled?` | `boolean` |  |
| `type?` | `"button" \| "submit" \| "reset"` |  |
| `onClick?` | `(e: MouseEvent<HTMLButtonElement>) => void` |  |
| `children?` | `ReactNode` |  |
| `asChild?` | `boolean` | Render the single child element (a link, a router Link) with the button's look instead of a <button>. |
| `id?` | `string` |  |
| `name?` | `string` | Form field name and value, sent with the form when this button submits it. |
| `value?` | `string` |  |
| `form?` | `string` | The id of the form this button belongs to, when it sits outside it. |
| `title?` | `string` |  |
| `tabIndex?` | `number` |  |
| `autoFocus?` | `boolean` |  |
| `aria-label?` | `string` |  |
| `aria-labelledby?` | `string` |  |
| `aria-describedby?` | `string` |  |
| `aria-expanded?` | `boolean \| "true" \| "false"` | For disclosure and menu triggers: whether what the button controls is open. |
| `aria-controls?` | `string` |  |
| `aria-haspopup?` | `boolean \| "true" \| "false" \| "menu" \| "listbox" \| "tree" \| "grid" \| "dialog"` |  |
| `aria-pressed?` | `boolean \| "true" \| "false" \| "mixed"` | For toggle buttons. |
| `aria-current?` | `boolean \| "true" \| "false" \| "page" \| "step" \| "location" \| "date" \| "time"` |  |
| `className?` | `string` | Extra class on the root element. |
| `style?` | `CSSProperties` | Inline style on the root element. |

#### ConnectionBanner

| Prop | Type | Notes |
| --- | --- | --- |
| `state` | `"reconnecting" \| "offline" \| "online"` | Required |
| `seconds?` | `number` |  |
| `text?` | `ReactNode` |  |
| `onRetry?` | `() => void` |  |
| `className?` | `string` | Extra class on the root element. |
| `style?` | `CSSProperties` | Inline style on the root element. |

#### ConnectionCard

| Prop | Type | Notes |
| --- | --- | --- |
| `name` | `string` | Required |
| `icon?` | `IconName` |  |
| `logo?` | `ReactNode` |  |
| `text?` | `ReactNode` |  |
| `status` | `"connected" \| "expiring" \| "error" \| "missing"` | Required |
| `statusLabel?` | `string` |  |
| `action?` | `ReactNode` |  |
| `className?` | `string` | Extra class on the root element. |
| `style?` | `CSSProperties` | Inline style on the root element. |


## Coupon Card

> Discount codes with their usage and what they earned.

Component · Commerce · Halo kit · [Live page](https://ui.twentyfirst.media/halo/components/CouponCard/)

Discount codes with their usage and what they earned.

Props: `code`, `kind` ("percent" | "fixed"), `value` (percent or amount), `currency`, `used`, `limit`, `until`, `min` (minimum order), `revenue`, `text`, `status` + `statusLabel`, `onCopy`, `menu`.

### Example

```tsx
import * as React from "react";
import { CouponCard } from "@twentyfirstmedia/halo";

export default function Preview() {
  return (
    <div
      className="tf-grid"
      style={
        {
          "--cols": "1fr 1fr",
          gap: 16,
        } as React.CSSProperties
      }
    >
      <CouponCard
        code="SPRING20"
        kind="percent"
        value={20}
        used={312}
        limit={500}
        until="Apr 30"
        min={10}
        revenue={8420}
        text="All Instagram packages"
        menu={[
          {
            label: "Edit",
            icon: "edit",
          },
          {
            label: "Duplicate",
            icon: "copy",
          },
          "-",
          {
            label: "Deactivate",
            icon: "pause",
            danger: true,
          },
        ]}
      />
      <CouponCard
        code="WELCOME5"
        kind="fixed"
        value={5}
        used={1204}
        text="First order"
        revenue={21890}
      />
      <CouponCard
        code="BLACKFRIDAY"
        kind="percent"
        value={30}
        used={1000}
        limit={1000}
        until="Nov 29"
        statusLabel="Used up"
      />
    </div>
  );
}
```

### Props

#### CouponCard

| Prop | Type | Notes |
| --- | --- | --- |
| `code` | `string` | Required |
| `kind?` | `"percent" \| "fixed"` |  |
| `value` | `number` | Required |
| `currency?` | `string` |  |
| `used?` | `number` |  |
| `limit?` | `number` |  |
| `until?` | `string` |  |
| `min?` | `number` |  |
| `revenue?` | `number` |  |
| `text?` | `ReactNode` |  |
| `status?` | `Status` |  |
| `statusLabel?` | `string` |  |
| `onCopy?` | `() => void` |  |
| `menu?` | `MenuProps["items"]` |  |
| `className?` | `string` | Extra class on the root element. |
| `style?` | `CSSProperties` | Inline style on the root element. |


## Data Table

> Table with the features list pages need: sorting, row selection with a bulk action bar, column toggles, sticky header and expandable rows.

Component · Data · Halo kit · [Live page](https://ui.twentyfirst.media/halo/components/DataTable/)

Table with the features list pages need: sorting, row selection with a bulk action bar, column toggles, sticky header and expandable rows. `FilterBar` sits above it.

DataTable props: `columns` ({key, label, render, align, sortable, sortValue(row), hideable, hidden, width}), `rows`, `rowKey` ("id"), `selectable`, `bulkActions` ({label, icon, danger, onClick(rows, clear)}), `renderExpanded(row)`, `stickyHeader`, `maxHeight`, `defaultSort` ({key, dir}), `toolbar`, `columnToggle` (false hides), `empty`.
FilterBar props: `filters` ({key, label, icon, options}), `value` / `onChange` ({key: option}), `search` (placeholder), `query` / `onQuery`, `right`.

- Sort cycles ascending → descending → off; the arrow only shows on the sorted or hovered column.
- The bulk bar floats at the bottom of the table while rows are selected; destructive actions are red and go through an Undo toast or ConfirmDialog.
- Active filters are ink chips you can click to change or × to remove. "Clear all" appears from two filters on.
- The header checkbox shows a dash when some, not all, rows are selected.
- Put it in `tf-panel tf-panel-flush` so cells line up at 24px with other panels.

### Example

```tsx
import * as React from "react";
import { Avatar, Badge, DataTable, FilterBar } from "@twentyfirstmedia/halo";
import type { Tone } from "@twentyfirstmedia/halo";

const ROWS = [
  {
    id: 1,
    name: "Ava Vogel",
    email: "ava@halo.app",
    role: "Editor",
    team: "Engineering",
    status: "Active",
    seats: 3,
  },
  {
    id: 2,
    name: "Ben Okafor",
    email: "ben@halo.app",
    role: "Viewer",
    team: "Sales",
    status: "Invited",
    seats: 1,
  },
  {
    id: 3,
    name: "Clara Haddad",
    email: "clara@halo.app",
    role: "Admin",
    team: "Design",
    status: "Active",
    seats: 5,
  },
  {
    id: 4,
    name: "Elif Sato",
    email: "elif@halo.app",
    role: "Editor",
    team: "Engineering",
    status: "Away",
    seats: 2,
  },
  {
    id: 5,
    name: "Jonah Petit",
    email: "jonah@halo.app",
    role: "Editor",
    team: "Growth",
    status: "Active",
    seats: 4,
  },
];
const TONE: Record<string, Tone> = {
  Active: "success",
  Invited: "info",
  Away: "warning",
};
function App() {
  const f = React.useState<Record<string, string>>({
      Team: "Engineering",
    }),
    q = React.useState("");
  const rows = ROWS.filter(
    (r) =>
      (!f[0].Team || r.team === f[0].Team) &&
      (!f[0].Status || r.status === f[0].Status) &&
      (!q[0] || r.name.toLowerCase().indexOf(q[0].toLowerCase()) >= 0),
  );
  return (
    <div
      className="tf-col"
      style={{
        gap: 16,
      }}
    >
      <FilterBar
        search="Search people"
        query={q[0]}
        onQuery={q[1]}
        value={f[0]}
        onChange={f[1]}
        filters={[
          {
            key: "Team",
            label: "Team",
            options: ["Design", "Engineering", "Growth", "Sales"],
          },
          {
            key: "Status",
            label: "Status",
            options: ["Active", "Invited", "Away"],
          },
        ]}
      />
      <div className="tf-panel tf-panel-flush">
        <DataTable
          rows={rows}
          selectable
          stickyHeader
          defaultSort={{
            key: "name",
            dir: "asc",
          }}
          toolbar={<span className="tf-card-desc">{rows.length + " of " + ROWS.length}</span>}
          bulkActions={[
            {
              label: "Change role",
              icon: "edit",
              onClick: () => {},
            },
            {
              label: "Remove",
              icon: "trash",
              danger: true,
              onClick: (r, clear) => {
                clear();
              },
            },
          ]}
          renderExpanded={(r) => (
            <span className="tf-card-desc">{r.email + " · " + r.seats + " seats assigned"}</span>
          )}
          columns={[
            {
              key: "name",
              label: "Name",
              sortable: true,
              hideable: false,
              render: (r) => (
                <span
                  className="tf-row"
                  style={{
                    flexWrap: "nowrap",
                  }}
                >
                  <Avatar name={r.name} size={28} />
                  <b>{r.name}</b>
                </span>
              ),
            },
            {
              key: "role",
              label: "Role",
              sortable: true,
            },
            {
              key: "team",
              label: "Team",
              sortable: true,
            },
            {
              key: "status",
              label: "Status",
              sortable: true,
              render: (r) => <Badge tone={TONE[r.status]}>{r.status}</Badge>,
            },
            {
              key: "seats",
              label: "Seats",
              align: "right",
              sortable: true,
            },
          ]}
        />
      </div>
    </div>
  );
}
export default App;
```

### Props

#### Avatar

| Prop | Type | Notes |
| --- | --- | --- |
| `name` | `string` | Required |
| `src?` | `string` |  |
| `size?` | `number` |  |
| `tint?` | `Tint \| "surface-sunken"` |  |
| `className?` | `string` | Extra class on the root element. |
| `style?` | `CSSProperties` | Inline style on the root element. |

#### Badge

| Prop | Type | Notes |
| --- | --- | --- |
| `tone?` | `Tone` |  |
| `dot?` | `boolean` |  |
| `live?` | `boolean` |  |
| `children?` | `ReactNode` |  |
| `className?` | `string` | Extra class on the root element. |
| `style?` | `CSSProperties` | Inline style on the root element. |

#### DataTable

| Prop | Type | Notes |
| --- | --- | --- |
| `columns` | `DataColumn<R>[]` | Required |
| `rows` | `R[]` | Required |
| `rowKey?` | `string` |  |
| `selectable?` | `boolean` |  |
| `bulkActions?` | `{ label: string; icon?: IconName; danger?: boolean; onClick: (rows: R[], clear: () => void) => void; }[]` |  |
| `renderExpanded?` | `(row: R) => ReactNode` |  |
| `stickyHeader?` | `boolean` |  |
| `maxHeight?` | `number \| string` |  |
| `defaultSort?` | `{ key: string; dir: "asc" \| "desc" }` |  |
| `toolbar?` | `ReactNode` |  |
| `columnToggle?` | `boolean` |  |
| `empty?` | `ReactNode` |  |
| `className?` | `string` | Extra class on the root element. |
| `style?` | `CSSProperties` | Inline style on the root element. |

#### FilterBar

| Prop | Type | Notes |
| --- | --- | --- |
| `filters` | `FilterDef[]` | Required |
| `value` | `Record<string, string>` | Required |
| `onChange` | `(v: Record<string, string>) => void` | Required |
| `search?` | `string` |  |
| `query?` | `string` |  |
| `onQuery?` | `(q: string) => void` |  |
| `right?` | `ReactNode` |  |
| `className?` | `string` | Extra class on the root element. |
| `style?` | `CSSProperties` | Inline style on the root element. |


## Date Picker

> Date field that opens a month calendar in a Popover.

Component · Forms · Halo kit · [Live page](https://ui.twentyfirst.media/halo/components/DatePicker/)

Date field that opens a month calendar in a Popover. `range` picks a from–to span and adds presets.

Props: `label`, `value`/`defaultValue` (Date, or {from, to} with `range`), `onChange`, `range`, `presets` (false to hide), `min`, `max`, `today`, `placeholder`, `hint`, `error`, `required`. `Calendar` is the bare month grid for inline use.

- Weeks start on Monday; dates read DD.MM.YYYY. Today has a dot under the number.
- A range closes after the second click; a single date closes after one.
- Presets cover the ranges people actually pick (7, 30, 90 days, this year); keep them to four.

### Example

```tsx
import * as React from "react";
import { Calendar, DatePicker } from "@twentyfirstmedia/halo";
import type { DateRange } from "@twentyfirstmedia/halo";

function App() {
  const d = React.useState<Date | DateRange | null>(new Date(2026, 3, 16)),
    r = React.useState<Date | DateRange | null>({
      from: new Date(2026, 3, 6),
      to: new Date(2026, 3, 16),
    });
  return (
    <div
      className="tf-panel tf-grid"
      style={
        {
          "--cols": "1fr 1fr",
          gap: 16,
          alignContent: "start",
        } as React.CSSProperties
      }
    >
      <DatePicker label="Due date" value={d[0]} onChange={d[1]} today={new Date(2026, 3, 16)} />
      <DatePicker
        label="Report range"
        range
        value={r[0]}
        onChange={r[1]}
        today={new Date(2026, 3, 16)}
        hint="Presets on the left"
      />
      <div
        style={{
          gridColumn: "1 / -1",
        }}
      >
        <div
          className="tf-popover"
          style={{
            position: "static",
            width: 476,
            maxWidth: "100%",
            animation: "none",
          }}
        >
          <div className="tf-dp with-presets">
            <div className="tf-dp-presets">
              {["Last 7 days", "Last 30 days", "Last 90 days", "This year"].map((x, i) => (
                <button key={x} type="button" className={"tf-dp-preset" + (i === 0 ? " on" : "")}>
                  {x}
                </button>
              ))}
            </div>
            <Calendar range value={r[0]} today={new Date(2026, 3, 16)} onChange={r[1]} />
          </div>
        </div>
      </div>
    </div>
  );
}
export default App;
```

### Props

#### Calendar

| Prop | Type | Notes |
| --- | --- | --- |
| `range?` | `boolean` |  |
| `value?` | `Date \| DateRange \| null` |  |
| `onChange?` | `(v: Date \| DateRange) => void` |  |
| `today?` | `Date` |  |
| `min?` | `Date` |  |
| `max?` | `Date` |  |
| `month?` | `Date` |  |
| `className?` | `string` | Extra class on the root element. |
| `style?` | `CSSProperties` | Inline style on the root element. |

#### DatePicker

| Prop | Type | Notes |
| --- | --- | --- |
| `label?` | `string` |  |
| `range?` | `boolean` |  |
| `value?` | `Date \| DateRange \| null` |  |
| `defaultValue?` | `Date \| DateRange` |  |
| `onChange?` | `(v: Date \| DateRange \| null) => void` |  |
| `presets?` | `boolean` |  |
| `min?` | `Date` |  |
| `max?` | `Date` |  |
| `today?` | `Date` |  |
| `placeholder?` | `string` |  |
| `hint?` | `string` |  |
| `error?` | `string` |  |
| `required?` | `boolean` |  |
| `className?` | `string` | Extra class on the root element. |
| `style?` | `CSSProperties` | Inline style on the root element. |


## Dns Record Table

> Domains and DNS: DnsRecordTable, DomainList (sorted by what needs attention) and MailAuthStatus (MX, SPF, DKIM, DMARC lights).

Component · Data · Halo kit · [Live page](https://ui.twentyfirst.media/halo/components/DnsRecordTable/)

Domains and DNS: `DnsRecordTable`, `DomainList` (sorted by what needs attention) and `MailAuthStatus` (MX, SPF, DKIM, DMARC lights).

DnsRecordTable: `records` ({id, type, name, content, ttl, proxy: true | false | null}), `rowMenu(record)` (Menu items), `selectable`, `bulkActions`, `toolbar`. Built on DataTable.
DomainList: `items` ({name, registrar, dns, days, ssl, sslLabel}), `onOpen`. Under 30 days warns, under 7 days is danger.
MailAuthStatus: `rows` ({domain, mx, spf, dkim, dmarc: {status, label}}), `columns`, `onOpen(row, column)`.

### Example

```tsx
import * as React from "react";
import { DnsRecordTable, DomainList, MailAuthStatus } from "@twentyfirstmedia/halo";

const recs = [
  {
    id: 1,
    type: "A",
    name: "@",
    content: "95.217.14.80",
    ttl: "Auto",
    proxy: true,
  },
  {
    id: 2,
    type: "CNAME",
    name: "www",
    content: "northwind.de",
    ttl: "Auto",
    proxy: true,
  },
  {
    id: 3,
    type: "MX",
    name: "@",
    content: "10 mx.halo-mail.net",
    ttl: "3600",
    proxy: null,
  },
  {
    id: 4,
    type: "TXT",
    name: "@",
    content: "v=spf1 include:_spf.halo-mail.net ~all",
    ttl: "3600",
    proxy: null,
  },
];
export default function Preview() {
  return (
    <div
      className="tf-col"
      style={{
        gap: 16,
      }}
    >
      <div className="tf-panel tf-panel-flush">
        <DnsRecordTable
          records={recs}
          rowMenu={() => [
            {
              label: "Edit",
              icon: "edit",
            },
            "-",
            {
              label: "Delete",
              icon: "trash",
              danger: true,
            },
          ]}
        />
      </div>
      <div
        className="tf-grid"
        style={
          {
            "--cols": "1fr 1fr",
            gap: 16,
          } as React.CSSProperties
        }
      >
        <div className="tf-panel tf-panel-flush tf-panel-list">
          <DomainList
            items={[
              {
                name: "halo.dev",
                registrar: "Cloudflare",
                dns: "Cloudflare",
                days: 18,
                ssl: "ok",
                sslLabel: "Valid",
              },
              {
                name: "northwind.de",
                registrar: "one.com",
                dns: "Cloudflare",
                days: 210,
                ssl: "ok",
                sslLabel: "Valid",
              },
              {
                name: "chatteo.de",
                registrar: "one.com",
                dns: "one.com",
                days: 5,
                ssl: "warn",
                sslLabel: "Renewing",
              },
            ]}
          />
        </div>
        <div className="tf-panel">
          <MailAuthStatus
            rows={[
              {
                domain: "northwind.de",
                mx: {
                  status: "ok",
                  label: "ok",
                },
                spf: {
                  status: "ok",
                  label: "ok",
                },
                dkim: {
                  status: "ok",
                  label: "ok",
                },
                dmarc: {
                  status: "warn",
                  label: "soft",
                },
              },
              {
                domain: "chatteo.de",
                mx: {
                  status: "ok",
                  label: "ok",
                },
                spf: {
                  status: "danger",
                  label: "missing",
                },
                dkim: {
                  status: "idle",
                  label: "—",
                },
                dmarc: {
                  status: "danger",
                  label: "missing",
                },
              },
            ]}
          />
        </div>
      </div>
    </div>
  );
}
```

### Props

#### DnsRecordTable

| Prop | Type | Notes |
| --- | --- | --- |
| `records` | `DnsRecord[]` | Required |
| `rowMenu?` | `(r: DnsRecord) => (MenuItem \| "-")[]` |  |
| `selectable?` | `boolean` |  |
| `bulkActions?` | `BulkAction<DnsRecord>[]` |  |
| `toolbar?` | `ReactNode` |  |
| `className?` | `string` | Extra class on the root element. |
| `style?` | `CSSProperties` | Inline style on the root element. |

#### DomainList

| Prop | Type | Notes |
| --- | --- | --- |
| `items` | `{ name: string; registrar?: string; dns?: string; days?: number; ssl?: Status; sslLabel?: string; }[]` | Required |
| `onOpen?` | `(d: NonNullable<DomainListProps["items"]>[number]) => void` |  |
| `className?` | `string` | Extra class on the root element. |
| `style?` | `CSSProperties` | Inline style on the root element. |

#### MailAuthStatus

| Prop | Type | Notes |
| --- | --- | --- |
| `rows` | `{ domain: string; mx?: { status: Status; label?: string }; spf?: { status: Status; label?: string }; dkim?: { status: Status; label?: string }; dmarc?: { status: Status; label?: string }; }[]` | Required |
| `columns?` | `string[]` |  |
| `onOpen?` | `(row: NonNullable<MailAuthStatusProps["rows"]>[number], column: string) => void` |  |
| `className?` | `string` | Extra class on the root element. |
| `style?` | `CSSProperties` | Inline style on the root element. |


## Drawer

> Right-side sheet for a record's details, sliding in over the page.

Component · Overlays · Halo kit · [Live page](https://ui.twentyfirst.media/halo/components/Drawer/)

Right-side sheet for a record's details, sliding in over the page.

Props: `title`, `subtitle`, `avatar` (name for an Avatar), `onClose`, `width`, `inline` (render inside a positioned container, for previews), children.

- Use for a record you look at without leaving the list: a customer, an invoice, a run.
- Traps keyboard focus, closes on Esc and backdrop click, returns focus to the opener.
- Put Tabs right under the badges when the record has more than one view.

### Example

```tsx
import * as React from "react";
import { Badge, Drawer, StatTile, Tabs } from "@twentyfirstmedia/halo";

export default function Preview() {
  return (
    <div
      style={{
        position: "relative",
        height: 480,
        borderRadius: "var(--radius-lg)",
        overflow: "hidden",
        background: "var(--canvas)",
      }}
    >
      <Drawer
        inline
        title="Northwind"
        subtitle="Logistics · Hamburg · customer since 2021"
        avatar="Northwind"
        onClose={() => {}}
      >
        <div className="tf-row">
          <Badge tone="success">Good</Badge>
          <Badge tone="info" dot={false}>
            Team · 24 seats
          </Badge>
        </div>
        <Tabs block items={["Overview", "Invoices", "Mail"]} />
        <div
          className="tf-grid"
          style={
            {
              "--cols": "1fr 1fr",
              "--cols-sm": "1fr 1fr",
            } as React.CSSProperties
          }
        >
          <StatTile tint="butter" value="€1,240" label="MRR" />
          <StatTile tint="mint" value="€14,880" label="Paid to date" />
        </div>
      </Drawer>
    </div>
  );
}
```

### Props

#### Badge

| Prop | Type | Notes |
| --- | --- | --- |
| `tone?` | `Tone` |  |
| `dot?` | `boolean` |  |
| `live?` | `boolean` |  |
| `children?` | `ReactNode` |  |
| `className?` | `string` | Extra class on the root element. |
| `style?` | `CSSProperties` | Inline style on the root element. |

#### Drawer

| Prop | Type | Notes |
| --- | --- | --- |
| `title` | `string` | Required |
| `subtitle?` | `ReactNode` |  |
| `avatar?` | `string` |  |
| `onClose?` | `() => void` |  |
| `width?` | `number \| string` |  |
| `inline?` | `boolean` |  |
| `children?` | `ReactNode` |  |
| `open?` | `boolean` | Optional: with `open` the component stays mounted while it animates out; without it, render it only while open. |
| `className?` | `string` | Extra class on the root element. |
| `style?` | `CSSProperties` | Inline style on the root element. |

#### StatTile

| Prop | Type | Notes |
| --- | --- | --- |
| `value` | `ReactNode` | Required |
| `label` | `string` | Required |
| `tint?` | `Tint \| "surface" \| "placeholder"` |  |
| `delta?` | `string` |  |
| `delay?` | `number` |  |
| `className?` | `string` | Extra class on the root element. |
| `style?` | `CSSProperties` | Inline style on the root element. |

#### Tabs

| Prop | Type | Notes |
| --- | --- | --- |
| `items` | `string[]` | Required |
| `value?` | `string` |  |
| `defaultValue?` | `string` |  |
| `onChange?` | `(v: string) => void` |  |
| `block?` | `boolean` |  |
| `panels?` | `Record<string, ReactNode>` | Content per tab; renders the tab panels under the bar, wired with tab/tabpanel roles. |
| `label?` | `string` | Accessible name of the tab list. |
| `className?` | `string` | Extra class on the root element. |
| `style?` | `CSSProperties` | Inline style on the root element. |


## Email Preview

> How a mail will look in the inbox and when opened, on desktop and phone.

Component · Admin · Halo kit · [Live page](https://ui.twentyfirst.media/halo/components/EmailPreview/)

How a mail will look in the inbox and when opened, on desktop and phone.

Props: `fromName`, `from`, `subject`, `preheader`, `html` (rendered in a sandboxed iframe, no scripts) or children, `device` / `onDevice` ("desktop" | "mobile"), `checks` ({status, label}).

- The body sits on `paper` and stays white in dark mode, like most mail clients.

### Example

```tsx
import { EmailPreview } from "@twentyfirstmedia/halo";

const html =
  '<div style="font-family:Arial,sans-serif;max-width:560px;margin:0 auto;padding:32px 24px;color:#141414"><div style="font-weight:800;font-size:20px;margin-bottom:24px">Northwind</div><h1 style="font-size:24px;margin:0 0 12px">Your order is on its way</h1><p style="font-size:15px;line-height:24px;color:#444">Hi Ida, your 1,000 Instagram followers start arriving within the next hour. Delivery spreads over 24 hours so it looks natural.</p><a style="display:inline-block;margin-top:16px;padding:12px 20px;border-radius:999px;background:#141414;color:#fff;text-decoration:none;font-weight:700">Track order</a></div>';
export default function Preview() {
  return (
    <div className="tf-panel">
      <EmailPreview
        from="hello@northwind.de"
        fromName="Northwind"
        subject="Your order is on its way"
        preheader="Delivery starts within the hour"
        html={html}
        checks={[
          {
            status: "ok",
            label: "Links work",
          },
          {
            status: "ok",
            label: "Unsubscribe link",
          },
          {
            status: "warn",
            label: "Subject is 46 characters, may cut on phones",
          },
        ]}
      />
    </div>
  );
}
```

### Props

#### EmailPreview

| Prop | Type | Notes |
| --- | --- | --- |
| `from?` | `string` |  |
| `fromName?` | `string` |  |
| `subject?` | `string` |  |
| `preheader?` | `string` |  |
| `html?` | `string` |  |
| `children?` | `ReactNode` |  |
| `device?` | `"desktop" \| "mobile"` |  |
| `onDevice?` | `(d: string) => void` |  |
| `checks?` | `{ status: Status; label: ReactNode }[]` |  |
| `className?` | `string` | Extra class on the root element. |
| `style?` | `CSSProperties` | Inline style on the root element. |


## Event Card

> Data in Twentyfirst UI.

Component · Data · Halo kit · [Live page](https://ui.twentyfirst.media/halo/components/EventCard/)

### Example

```tsx
import { EventCard } from "@twentyfirstmedia/halo";

export default function Preview() {
  return (
    <div
      className="tf-col"
      style={{
        maxWidth: 300,
      }}
    >
      <EventCard kind="meeting" label="Team sync" date="Tue, Apr 14" time="10:30">
        Roadmap check-in with design and growth; bring last sprint numbers.
      </EventCard>
      <EventCard kind="deadline" label="Deadline" date="Fri, Apr 17" time="17:00">
        Send Q2 invoices to all annual customers.
      </EventCard>
    </div>
  );
}
```

### Props

#### EventCard

| Prop | Type | Notes |
| --- | --- | --- |
| `kind?` | `"meeting" \| "deadline" \| "review" \| "launch" \| "incident"` |  |
| `label` | `string` | Required |
| `date` | `string` | Required |
| `time` | `string` | Required |
| `tint?` | `Tint` |  |
| `icon?` | `IconName` |  |
| `actions?` | `boolean` |  |
| `children?` | `ReactNode` |  |
| `className?` | `string` | Extra class on the root element. |
| `style?` | `CSSProperties` | Inline style on the root element. |


## Export Dialog

> Exporting a filtered list: format, period, columns, progress and download.

Component · Overlays · Halo kit · [Live page](https://ui.twentyfirst.media/halo/components/ExportDialog/)

Exporting a filtered list: format, period, columns, progress and download.

Props: `open` / `onClose` (or `inline`), `title`, `text`, `count`, `formats`, `columns` ({key, label, default: false = off}), `ranges` (false hides the period), `range`, `note`, `onExport(options, progress)` (return a promise; call `progress(0–100)`), `onDownload` or `download` (node), `doneText`.

- Columns with personal data start unchecked.

### Example

```tsx
import { ExportDialog } from "@twentyfirstmedia/halo";

export default function Preview() {
  return (
    <div
      style={{
        display: "grid",
        placeItems: "center",
        padding: 24,
        background: "var(--canvas)",
        borderRadius: "var(--radius-lg)",
      }}
    >
      <ExportDialog
        inline
        title="Export orders"
        count={4812}
        formats={["csv", "xlsx", "json"]}
        columns={[
          {
            key: "id",
            label: "Order number",
          },
          {
            key: "date",
            label: "Date",
          },
          {
            key: "customer",
            label: "Customer",
          },
          {
            key: "product",
            label: "Product",
          },
          {
            key: "net",
            label: "Net",
          },
          {
            key: "vat",
            label: "VAT",
          },
          {
            key: "email",
            label: "Email",
            default: false,
          },
          {
            key: "ip",
            label: "IP address",
            default: false,
          },
        ]}
        note="Personal data is only included when you pick those columns."
        onExport={(o, prog) =>
          new Promise((r) => {
            let x = 0;
            const t = setInterval(() => {
              x += 20;
              prog(x);
              if (x >= 100) {
                clearInterval(t);
                r();
              }
            }, 300);
          })
        }
        onClose={() => {}}
      />
    </div>
  );
}
```

### Props

#### ExportDialog

| Prop | Type | Notes |
| --- | --- | --- |
| `open?` | `boolean` |  |
| `inline?` | `boolean` |  |
| `onClose?` | `() => void` |  |
| `title?` | `string` |  |
| `text?` | `ReactNode` |  |
| `count?` | `number` |  |
| `formats?` | `string[]` |  |
| `format?` | `string` |  |
| `columns?` | `{ key: string; label: string; default?: boolean }[]` |  |
| `ranges?` | `boolean` |  |
| `range?` | `{ from: Date \| null; to: Date \| null } \| null` |  |
| `note?` | `ReactNode` |  |
| `onExport?` | `( o: { format: string; columns: string[]; range: DateRange \| null }, progress: (pct: number) => void, ) => void \| Promise<void>` |  |
| `onDownload?` | `() => void` |  |
| `download?` | `ReactNode` |  |
| `doneText?` | `string` |  |
| `className?` | `string` | Extra class on the root element. |
| `style?` | `CSSProperties` | Inline style on the root element. |


## File Drop

> Dashed drop zone plus an upload list.

Component · Forms · Halo kit · [Live page](https://ui.twentyfirst.media/halo/components/FileDrop/)

Dashed drop zone plus an upload list. Click, Enter or drop to add files.

- `onFiles(files)` hands over the real `File` objects the person picked or dropped, after `accept` and `multiple`; upload them yourself. Dropped files that do not match `accept` go to `onReject`; say so with an inline Alert, not a toast.
- Progress is yours to report: control `files` (`{ id, name, size, progress, file }`) and set `progress` from your upload. Below 100 a row shows a progress bar and a cancel button, at 100 it reads "uploaded". With `onFiles` and no `files`, rows show only the size. `onRemove` tells you a file was removed or its upload cancelled.
- Without `onFiles` the list animates made-up progress, as a demo of the look (`simulateProgress` turns that on or off).
- The zone turns mint while a file is held over it, so people know the drop will land.
- Say what is accepted in the hint (types, size).

### Example

```tsx
import * as React from "react";
import { FileDrop } from "@twentyfirstmedia/halo";

function App() {
  const f = React.useState([
    {
      id: "a",
      name: "Receipt-April-Hetzner.pdf",
      size: 184320,
      progress: 100,
    },
    {
      id: "b",
      name: "Team-offsite-photos.zip",
      size: 24117248,
      progress: 46,
    },
  ]);
  return (
    <div className="tf-panel">
      <FileDrop
        files={f[0]}
        onChange={f[1]}
        hint="PDF, PNG or JPG up to 10 MB · drag several at once"
      />
    </div>
  );
}
export default App;
```

### Props

#### FileDrop

| Prop | Type | Notes |
| --- | --- | --- |
| `files?` | `UploadFile[]` | The listed files (controlled); set `progress` per file to show real upload progress. |
| `onChange?` | `(f: UploadFile[]) => void` | The list changed: files added (with their `file`) or removed. |
| `onFiles?` | `(files: File[]) => void \| boolean \| File[]` | The person picked or dropped files: the real `File` objects, after `accept` and `multiple`. Upload them yourself. To show progress, control `files` and set each `progress`; an uncontrolled list shows them with their size only. Return `false` to list none of them, or the files to list (for example after checking their size). |
| `onReject?` | `(files: File[]) => void` | Dropped files that do not match `accept` (show an inline Alert). |
| `onRemove?` | `(f: UploadFile) => void` | A listed file was removed or its upload cancelled. |
| `simulateProgress?` | `boolean` | Animate made-up progress for added files, as a demo of the look. Default: on without `onFiles` (as before), off with it. |
| `title?` | `string` |  |
| `hint?` | `string` |  |
| `accept?` | `string` | Accepted types, as for `<input type="file">` ("image/*,.pdf"); also checked on drop. |
| `multiple?` | `boolean` |  |
| `disabled?` | `boolean` | No picking or dropping; the list stays visible. |
| `name?` | `string` | Takes part in a surrounding form under this name: the listed files are submitted with it. |
| `className?` | `string` | Extra class on the root element. |
| `style?` | `CSSProperties` | Inline style on the root element. |


## Funnel

> Horizontal funnel: each step's share of the first, plus step-to-step conversion on the right.

Component · Charts · Halo kit · [Live page](https://ui.twentyfirst.media/halo/components/Funnel/)

Horizontal funnel: each step's share of the first, plus step-to-step conversion on the right.

Props: `steps` ({label, value, tint}), `tint` (default "sky"), `format(v)`.

- Three to six steps, named as actions people take ("Started trial"), in order.
- The right column is the conversion from the step above; that's the number people act on.

### Example

```tsx
import { Funnel } from "@twentyfirstmedia/halo";

export default function Preview() {
  return (
    <div className="tf-panel">
      <div>
        <h3 className="tf-panel-title">Trial to paid</h3>
        <p className="tf-panel-sub">Where people drop off</p>
      </div>
      <Funnel
        steps={[
          {
            label: "Visited pricing",
            value: 7495,
          },
          {
            label: "Started trial",
            value: 3609,
          },
          {
            label: "Invited a teammate",
            value: 2221,
          },
          {
            label: "Became paying",
            value: 1388,
          },
        ]}
      />
    </div>
  );
}
```

### Props

#### Funnel

| Prop | Type | Notes |
| --- | --- | --- |
| `steps` | `{ label: string; value: number; tint?: Tint }[]` | Required |
| `tint?` | `Tint` |  |
| `format?` | `(v: number) => string` |  |
| `className?` | `string` | Extra class on the root element. |
| `style?` | `CSSProperties` | Inline style on the root element. |


## Gallery

> Images: Gallery (photos with thumbnails and full screen), BeforeAfter (drag to compare, e.g.

Component · Media · Halo kit · [Live page](https://ui.twentyfirst.media/halo/components/Gallery/)

Images: `Gallery` (photos with thumbnails and full screen), `BeforeAfter` (drag to compare, e.g. virtual staging or upscaling) and `ImageVariants` (the sizes and formats generated from one image).

Gallery: `items` ({src, alt, caption, art, tint}), `start`, `ratio`, `thumbs`, `fullscreen`, `badge`, `loading`, `referrerPolicy`. Arrow keys and Esc work in full screen.
BeforeAfter: `before`, `after` ({src, alt} or {art}), `start` (0–100), `ratio`, `beforeLabel`, `afterLabel`, `label`, `valueText`, `loading`, `referrerPolicy`. Drag, click or use ← → (Page Up/Down for bigger steps, Home and End for the ends).
ImageVariants: `variants` ({id, label, src, size, format, weight, ratio, status}), `selected` / `onSelect`, `alt`, `tint`, `actions`.

- Images load lazily (`loading="eager"` for a gallery at the top of the page; thumbnails always load lazily) and decode off the main thread.
- `referrerPolicy="no-referrer"` keeps your page address from hosts the photos come from.
- The compare slider tells screen readers both shares ("Before 40%, After 60%", with your labels); `valueText` words it your way.

### Example

```tsx
import * as React from "react";
import { BeforeAfter, Gallery, ImageVariants } from "@twentyfirstmedia/halo";
import type { Tint } from "@twentyfirstmedia/halo";

const art = (t: Tint, s: string) => (
  <div
    style={{
      position: "absolute",
      inset: 0,
      background: "linear-gradient(160deg, var(--" + t + ") 0%, var(--surface) 120%)",
      display: "grid",
      placeItems: "center",
      color: "var(--" + t + "-ink)",
      font: "var(--type-title-weight) 14px/1 var(--font-sans)",
    }}
  >
    {s}
  </div>
);
const before = {
  art: (
    <div
      style={{
        position: "absolute",
        inset: 0,
        background: "linear-gradient(180deg, #ddd8cf 0 62%, #b9ad9c 62%)",
      }}
    />
  ),
};
const after = {
  art: (
    <div
      style={{
        position: "absolute",
        inset: 0,
        background: "linear-gradient(180deg, #e9e2d6 0 62%, #a68b6a 62%)",
      }}
    >
      <div
        style={{
          position: "absolute",
          left: "18%",
          bottom: "22%",
          width: "38%",
          height: "22%",
          borderRadius: "var(--radius-md)",
          background: "#5b6b5a",
        }}
      />
      <div
        style={{
          position: "absolute",
          right: "16%",
          bottom: "38%",
          width: "14%",
          height: "30%",
          borderRadius: "var(--radius-sm)",
          background: "#3d3a36",
        }}
      />
    </div>
  ),
};
export default function Preview() {
  return (
    <div
      className="tf-grid"
      style={
        {
          "--cols": "1fr 1fr",
          gap: 16,
          alignItems: "start",
        } as React.CSSProperties
      }
    >
      <div
        className="tf-panel"
        style={{
          gap: 12,
        }}
      >
        <Gallery
          badge="Virtual staging"
          items={[
            {
              art: art("sky", "Living room"),
              caption: "Living room",
            },
            {
              art: art("mint", "Kitchen"),
            },
            {
              art: art("butter", "Bedroom"),
            },
            {
              art: art("lilac", "Balcony"),
            },
            {
              art: art("blush", "Bathroom"),
            },
          ]}
        />
      </div>
      <div
        className="tf-col"
        style={{
          gap: 16,
        }}
      >
        <div
          className="tf-panel"
          style={{
            gap: 12,
          }}
        >
          <b>Virtual staging</b>
          <BeforeAfter before={before} after={after} afterLabel="Staged · Scandinavian" />
        </div>
        <div className="tf-panel">
          <ImageVariants
            tint="sky"
            variants={[
              {
                id: 1,
                label: "Original",
                size: "4032 × 3024",
                format: "JPEG",
                weight: "3.8 MB",
                ratio: "4 / 3",
              },
              {
                id: 2,
                label: "Listing",
                size: "1600 × 1200",
                format: "WebP",
                weight: "214 KB",
                ratio: "4 / 3",
                status: "ok",
              },
              {
                id: 3,
                label: "Square",
                size: "1080 × 1080",
                format: "WebP",
                weight: "168 KB",
                ratio: "1 / 1",
                status: "ok",
              },
              {
                id: 4,
                label: "Upscaled 2×",
                size: "8064 × 6048",
                format: "PNG",
                status: "running",
                ratio: "4 / 3",
              },
            ]}
          />
        </div>
      </div>
    </div>
  );
}
```

### Props

#### BeforeAfter

| Prop | Type | Notes |
| --- | --- | --- |
| `before` | `MediaPane` | Required |
| `after` | `MediaPane` | Required |
| `start?` | `number` |  |
| `ratio?` | `string` |  |
| `beforeLabel?` | `string` |  |
| `afterLabel?` | `string` |  |
| `label?` | `string` | Accessible name of the slider (default "Compare before and after"). |
| `valueText?` | `(percent: number) => string` | What screen readers hear for a position (0–100, the share of "before"). Default: "Before 40%, After 60%", with your `beforeLabel`/`afterLabel`. |
| `loading?` | `"lazy" \| "eager"` | Loading of both images (default `"lazy"`). |
| `referrerPolicy?` | `ImageReferrerPolicy` | `referrerPolicy` of both images. |
| `className?` | `string` | Extra class on the root element. |
| `style?` | `CSSProperties` | Inline style on the root element. |

#### Gallery

| Prop | Type | Notes |
| --- | --- | --- |
| `items` | `GalleryItem[]` | Required |
| `loading?` | `"lazy" \| "eager"` | Loading of the main image: `"lazy"` (default) waits until the gallery is near the viewport; use `"eager"` for a gallery at the top of the page. Thumbnails always load lazily. |
| `referrerPolicy?` | `ImageReferrerPolicy` | `referrerPolicy` of every image, e.g. `"no-referrer"` for photos from other hosts. |
| `start?` | `number` | First image when uncontrolled. |
| `index?` | `number` | The shown image (controlled, 0-based), with `onIndexChange`. |
| `onIndexChange?` | `(index: number) => void` |  |
| `label?` | `string` | Accessible name of the gallery (default "Images"), e.g. the listing's title. |
| `ratio?` | `string` |  |
| `thumbs?` | `boolean` |  |
| `fullscreen?` | `boolean` |  |
| `badge?` | `ReactNode` |  |
| `className?` | `string` | Extra class on the root element. |
| `style?` | `CSSProperties` | Inline style on the root element. |

#### ImageVariants

| Prop | Type | Notes |
| --- | --- | --- |
| `variants` | `ImageVariant[]` | Required |
| `selected?` | `string \| number` |  |
| `onSelect?` | `(id: string \| number) => void` |  |
| `alt?` | `string` |  |
| `tint?` | `Tint` |  |
| `actions?` | `ReactNode` |  |
| `className?` | `string` | Extra class on the root element. |
| `style?` | `CSSProperties` | Inline style on the root element. |


## Gauge

> Half-ring showing one value against a maximum: a goal, a budget, a quota.

Component · Charts · Halo kit · [Live page](https://ui.twentyfirst.media/halo/components/Gauge/)

Half-ring showing one value against a maximum: a goal, a budget, a quota.

Props: `value`, `max`, `caption`, `format(v)`, `tint`, or `thresholds` ([warn, danger] switches mint → butter → blush), `size`, `stroke`, `showRange`, `label`.

- One gauge per idea; never put gauges in a row to compare things — use a BarChart.
- Use `thresholds` for limits (budgets, storage), a fixed `tint` for goals where more is better.

### Example

```tsx
import { Gauge } from "@twentyfirstmedia/halo";

export default function Preview() {
  return (
    <div
      className="tf-panel"
      style={{
        flexDirection: "row",
        justifyContent: "space-around",
        flexWrap: "wrap",
        gap: 24,
      }}
    >
      <Gauge
        value={60}
        max={75}
        caption="80% of monthly target"
        format={(v) => "€" + v + "k"}
        tint="mint"
      />
      <Gauge
        value={72}
        max={100}
        thresholds={[60, 85]}
        caption="Agent budget used"
        format={(v) => v + "%"}
      />
      <Gauge
        value={91}
        max={100}
        thresholds={[60, 85]}
        caption="Storage used"
        format={(v) => v + "%"}
      />
    </div>
  );
}
```

### Props

#### Gauge

| Prop | Type | Notes |
| --- | --- | --- |
| `value` | `number` | Required |
| `max?` | `number` |  |
| `caption?` | `string` |  |
| `format?` | `(v: number) => string` |  |
| `tint?` | `Tint \| "ink"` |  |
| `thresholds?` | `[number, number]` |  |
| `size?` | `number` |  |
| `stroke?` | `number` |  |
| `showRange?` | `boolean` |  |
| `label?` | `string` |  |
| `className?` | `string` | Extra class on the root element. |
| `style?` | `CSSProperties` | Inline style on the root element. |


## Heatmap

> Grid of cells shaded by value, for patterns across two dimensions (weekday × hour, week × day).

Component · Charts · Halo kit · [Live page](https://ui.twentyfirst.media/halo/components/Heatmap/)

Grid of cells shaded by value, for patterns across two dimensions (weekday × hour, week × day).

Props: `rows`, `cols` (labels), `values` (rows × cols numbers), `colEvery` (label every nth column), `caption`, `format(v)`, `label`.

- Five steps of one hue (mint-ink mixed into the surface), so it reads by lightness in both themes and for color-blind viewers.
- The footer shows the hovered cell's exact value; keep the Less–More scale visible.

### Example

```tsx
import { Heatmap } from "@twentyfirstmedia/halo";

const vals = [0, 1, 2, 3, 4, 5, 6].map((d) =>
  Array.from(
    {
      length: 24,
    },
    (_, hr) => {
      const w = d < 5 ? 1 : 0.35;
      return Math.round(
        48 *
          w *
          (Math.exp(-Math.pow((hr - 11) / 3.2, 2)) +
            0.7 * Math.exp(-Math.pow((hr - 16) / 2.6, 2))) +
          ((d * 31 + hr * 17) % 7),
      );
    },
  ),
);
export default function Preview() {
  return (
    <div className="tf-panel">
      <div>
        <h3 className="tf-panel-title">When people sign up</h3>
        <p className="tf-panel-sub">By weekday and hour</p>
      </div>
      <Heatmap
        rows={["Mon", "Tue", "Wed", "Thu", "Fri", "Sat", "Sun"]}
        cols={Array.from(
          {
            length: 24,
          },
          (_, i) => (i < 10 ? "0" : "") + i,
        )}
        colEvery={3}
        values={vals}
        caption="Hover a cell for the count"
        format={(v) => v + " sign-ups"}
      />
    </div>
  );
}
```

### Props

#### Heatmap

| Prop | Type | Notes |
| --- | --- | --- |
| `rows` | `string[]` | Required |
| `cols` | `string[]` | Required |
| `values` | `number[][]` | Required |
| `colEvery?` | `number` |  |
| `caption?` | `string` |  |
| `format?` | `(v: number) => string` |  |
| `label?` | `string` |  |
| `className?` | `string` | Extra class on the root element. |
| `style?` | `CSSProperties` | Inline style on the root element. |


## Inbox List

> Webmail pieces: AccountSwitcher (one login, every address), InboxList (with agent state per mail), MailThread, SignatureEditor, AttachmentPreview.

Component · Data · Halo kit · [Live page](https://ui.twentyfirst.media/halo/components/InboxList/)

Webmail pieces: `AccountSwitcher` (one login, every address), `InboxList` (with agent state per mail), `MailThread`, `SignatureEditor`, `AttachmentPreview`.

AccountSwitcher: `accounts` ({address, domain, unread}), `value` (null = all inboxes), `onChange`, `unread`, `allLabel`.
InboxList: `items` ({id, from, time, subject, snippet, unread, to, agent: {label, tone}, tags}), `selected`, `onOpen`.
MailThread: `subject`, `messages` ({id, from, to, time, snippet, body, agent, tint, agentNote, attachments}), `reply` (node). Oldest collapsed, newest open; agent mails carry a signal edge.
SignatureEditor: `value` / `onChange` ({name, role, company, phone, website}), `fields`, `note`, `extra`.
AttachmentPreview: `name`, `meta`, children (the document on paper), `facts` (KeyValue), `found`, `actions`, `onClose`.

### Example

```tsx
import * as React from "react";
import { AccountSwitcher, InboxList, MailThread } from "@twentyfirstmedia/halo";

const accounts = [
  {
    address: "support@northwind.de",
    domain: "northwind.de",
    unread: 3,
  },
  {
    address: "hello@chatteo.de",
    domain: "chatteo.de",
    unread: 1,
  },
  {
    address: "robin@twentyfirst.media",
    domain: "twentyfirst.media",
  },
];
function App() {
  const a = React.useState<string | null>(null),
    s = React.useState<string | number>(1);
  return (
    <div
      className="tf-grid"
      style={
        {
          "--cols": "360px 1fr",
          gap: 16,
          alignItems: "start",
        } as React.CSSProperties
      }
    >
      <div
        className="tf-panel"
        style={{
          gap: 12,
        }}
      >
        <AccountSwitcher accounts={accounts} value={a[0]} onChange={a[1]} unread={4} />
        <InboxList
          selected={s[0]}
          onOpen={(m) => {
            s[1](m.id);
          }}
          items={[
            {
              id: 1,
              from: "Ida Nolan",
              time: "08:40",
              subject: "Seat upgrade before renewal",
              snippet: "We are growing faster than planned and need 40 more seats.",
              unread: true,
              to: "support@",
              agent: {
                label: "Draft ready",
                tone: "highlight",
              },
            },
            {
              id: 2,
              from: "Hetzner",
              time: "07:12",
              subject: "Invoice 2026-0412",
              snippet: "Your invoice is attached.",
              tags: ["Receipt"],
            },
          ]}
        />
      </div>
      <div className="tf-panel">
        <MailThread
          subject="Seat upgrade before renewal"
          messages={[
            {
              id: 1,
              from: "Ida Nolan",
              to: "to support@northwind.de",
              time: "Mon 16:20",
              snippet: "Hi! Quick question about seats…",
              body: "Hi! Quick question about seats before our renewal.",
            },
            {
              id: 2,
              from: "Atlas",
              agent: true,
              tint: "sky",
              agentNote: "sent after approval",
              to: "to ida@northwind.io",
              time: "Tue 09:41",
              body: "Hi Ida,\n\nhappy to add 40 seats before your renewal on May 1.\n\nBest,\nMara",
              attachments: [
                {
                  name: "Quote-0412.pdf",
                  size: "84 KB",
                },
              ],
            },
          ]}
        />
      </div>
    </div>
  );
}
export default App;
```

### Props

#### AccountSwitcher

| Prop | Type | Notes |
| --- | --- | --- |
| `accounts` | `{ address: string; domain?: string; unread?: number }[]` | Required |
| `value?` | `string \| null` |  |
| `onChange?` | `(address: string \| null) => void` |  |
| `unread?` | `number` |  |
| `allLabel?` | `string` |  |
| `className?` | `string` | Extra class on the root element. |
| `style?` | `CSSProperties` | Inline style on the root element. |

#### InboxList

| Prop | Type | Notes |
| --- | --- | --- |
| `items` | `{ id: string \| number; from: string; time?: string; subject: string; snippet?: string; unread?: boolean; to?: string; agent?: { label: string; tone?: Tone }; tags?: string[]; }[]` | Required |
| `selected?` | `string \| number` |  |
| `onOpen?` | `(m: NonNullable<InboxListProps["items"]>[number]) => void` |  |
| `className?` | `string` | Extra class on the root element. |
| `style?` | `CSSProperties` | Inline style on the root element. |

#### MailThread

| Prop | Type | Notes |
| --- | --- | --- |
| `subject` | `string` | Required |
| `messages` | `{ id: string \| number; from: string; to?: string; time?: string; snippet?: string; body: ReactNode; agent?: boolean; tint?: Tint; agentNote?: string; attachments?: { name: string; size?: string }[]; }[]` | Required |
| `reply?` | `ReactNode` |  |
| `className?` | `string` | Extra class on the root element. |
| `style?` | `CSSProperties` | Inline style on the root element. |


## Kanban Column

> Data in Twentyfirst UI.

Component · Data · Halo kit · [Live page](https://ui.twentyfirst.media/halo/components/KanbanColumn/)

### Example

```tsx
import { AvatarStack, Badge, Card, KanbanColumn } from "@twentyfirstmedia/halo";

export default function Preview() {
  return (
    <div
      style={{
        maxWidth: 300,
      }}
    >
      <KanbanColumn title="In review" dot="lilac">
        <Card
          title="Billing settings flow"
          meta={["Due Fri"]}
          status={<Badge tone="highlight">Review</Badge>}
          actions={[<AvatarStack key={1} names={["Mara Ellis", "Sun Lee"]} size={24} />]}
        />
        <Card
          title="Empty states for reports"
          meta={["Due Mon"]}
          status={<Badge tone="warning">Changes</Badge>}
        />
      </KanbanColumn>
    </div>
  );
}
```

### Props

#### AvatarStack

| Prop | Type | Notes |
| --- | --- | --- |
| `names` | `string[]` | Required |
| `max?` | `number` |  |
| `size?` | `number` |  |
| `className?` | `string` | Extra class on the root element. |
| `style?` | `CSSProperties` | Inline style on the root element. |

#### Badge

| Prop | Type | Notes |
| --- | --- | --- |
| `tone?` | `Tone` |  |
| `dot?` | `boolean` |  |
| `live?` | `boolean` |  |
| `children?` | `ReactNode` |  |
| `className?` | `string` | Extra class on the root element. |
| `style?` | `CSSProperties` | Inline style on the root element. |

#### Card

| Prop | Type | Notes |
| --- | --- | --- |
| `title?` | `string` |  |
| `description?` | `string` |  |
| `meta?` | `string[]` |  |
| `corner?` | `ReactNode` |  |
| `status?` | `ReactNode` |  |
| `actions?` | `ReactNode[]` |  |
| `tint?` | `Tint \| "surface"` |  |
| `onClick?` | `() => void` |  |
| `children?` | `ReactNode` |  |
| `eyebrow?` | `ReactNode` |  |
| `surface?` | `Surface` | `"glass"`: translucent glass over what is behind (maps, 3D, video, photos); `"solid"` opts out inside a glass `UIProvider`. |
| `className?` | `string` | Extra class on the root element. |
| `style?` | `CSSProperties` | Inline style on the root element. |

#### KanbanColumn

| Prop | Type | Notes |
| --- | --- | --- |
| `title` | `string` | Required |
| `dot?` | `Tint` |  |
| `delay?` | `number` |  |
| `children?` | `ReactNode` |  |
| `onAdd?` | `() => void` |  |
| `className?` | `string` | Extra class on the root element. |
| `style?` | `CSSProperties` | Inline style on the root element. |


## Key Value

> Small building blocks for detail panels: KeyValue (label/value list), Kbd (keyboard keys), Spinner, Collapsible.

Component · Foundations · Halo kit · [Live page](https://ui.twentyfirst.media/halo/components/KeyValue/)

Small building blocks for detail panels: `KeyValue` (label/value list), `Kbd` (keyboard keys), `Spinner`, `Collapsible`.

KeyValue: `items` ([label, value, mono] or {k, v, mono}), `dense`. Empty values show a dash.
Kbd: `keys` (array). Spinner: `size` ("lg"), `label`. Collapsible: `title`, `meta`, `defaultOpen` / `open` + `onOpenChange`, children.

- Keep keys short nouns; values that are codes, IDs or addresses use `mono`.
- Show a spinner only after ~300 ms; inside a button it replaces the icon.

### Example

```tsx
import * as React from "react";
import { Collapsible, Kbd, KeyValue, Spinner, StatusIndicator } from "@twentyfirstmedia/halo";

export default function Preview() {
  return (
    <div
      className="tf-grid"
      style={
        {
          "--cols": "1fr 1fr",
          gap: 16,
        } as React.CSSProperties
      }
    >
      <div
        className="tf-panel"
        style={{
          gap: 12,
        }}
      >
        <KeyValue
          items={[
            ["Server", "ax41-fsn1"],
            ["Address", "95.217.14.80", true],
            ["Kernel", "6.8.0-45"],
            ["Backups", <StatusIndicator status="ok" label="Nightly · 03:00" />],
            ["Notes", null],
          ]}
        />
      </div>
      <div
        className="tf-panel"
        style={{
          gap: 16,
        }}
      >
        <div className="tf-row">
          <span>Search</span>
          <Kbd keys={["⌘", "K"]} />
          <span>Approve</span>
          <Kbd keys={["A"]} />
          <Spinner />
          <Spinner size="lg" />
        </div>
        <Collapsible title="Advanced settings" meta="3 changed" defaultOpen>
          <KeyValue
            dense
            items={[
              ["Timeout", "30 s"],
              ["Retries", "3"],
            ]}
          />
        </Collapsible>
        <Collapsible title="Raw payload">Hidden until opened</Collapsible>
      </div>
    </div>
  );
}
```

### Props

#### Collapsible

| Prop | Type | Notes |
| --- | --- | --- |
| `title` | `ReactNode` | Required |
| `meta?` | `ReactNode` |  |
| `defaultOpen?` | `boolean` |  |
| `open?` | `boolean` |  |
| `onOpenChange?` | `(open: boolean) => void` |  |
| `children?` | `ReactNode` |  |
| `className?` | `string` | Extra class on the root element. |
| `style?` | `CSSProperties` | Inline style on the root element. |

#### Kbd

| Prop | Type | Notes |
| --- | --- | --- |
| `keys?` | `string[]` |  |
| `children?` | `ReactNode` |  |
| `className?` | `string` | Extra class on the root element. |
| `style?` | `CSSProperties` | Inline style on the root element. |

#### KeyValue

| Prop | Type | Notes |
| --- | --- | --- |
| `items` | `KeyValueItem[]` | Required |
| `dense?` | `boolean` |  |
| `className?` | `string` | Extra class on the root element. |
| `style?` | `CSSProperties` | Inline style on the root element. |

#### Spinner

| Prop | Type | Notes |
| --- | --- | --- |
| `size?` | `"lg"` |  |
| `label?` | `string` |  |
| `className?` | `string` | Extra class on the root element. |
| `style?` | `CSSProperties` | Inline style on the root element. |

#### StatusIndicator

| Prop | Type | Notes |
| --- | --- | --- |
| `status` | `Status` | Required |
| `label?` | `ReactNode` |  |
| `size?` | `"sm"` |  |
| `className?` | `string` | Extra class on the root element. |
| `style?` | `CSSProperties` | Inline style on the root element. |


## Ledger Table

> Bookkeeping: LedgerTable (bookings with project and agent suggestions), PnLStatement and ReceiptSuggestion.

Component · Data · Halo kit · [Live page](https://ui.twentyfirst.media/halo/components/LedgerTable/)

Bookkeeping: `LedgerTable` (bookings with project and agent suggestions), `PnLStatement` and `ReceiptSuggestion`.

LedgerTable: `rows` ({id, date, ref, text, category, project, projectTint, net, vat, gross, suggested, status, statusLabel}), `categories` (makes the category editable in place) + `onEdit(row, change)`, `currency`, `selectable`, `bulkActions`, `toolbar`, `maxHeight`.
PnLStatement: `columns` (months), `rows` ({kind: "section" | "subtotal" | "total", label, values}), `currency`, `total` (false hides it).
ReceiptSuggestion: `file`, `source`, `fields` ({label, value, mono, confidence 0–1}), `suggestion`, `onConfirm`, `onDiscard`, `confirmLabel`, `discardLabel`, children.

- Agent suggestions carry the signal diamond until a person confirms them.
- Negative amounts are blush; amounts use the locale's currency format.

### Example

```tsx
import * as React from "react";
import { LedgerTable, PnLStatement, ReceiptSuggestion } from "@twentyfirstmedia/halo";
import type { LedgerRow } from "@twentyfirstmedia/halo";

const rows: LedgerRow[] = [
  {
    id: 1,
    date: "Apr 2",
    ref: "RE-0412",
    text: "Hetzner Online GmbH",
    category: "Hosting",
    project: "Northwind",
    projectTint: "sky",
    net: 84.03,
    vat: 15.97,
    gross: 100.0,
    status: "ok",
    statusLabel: "Booked",
  },
  {
    id: 2,
    date: "Apr 3",
    ref: "ST-2231",
    text: "Stripe payout",
    category: "Revenue",
    project: "Chatteo",
    projectTint: "mint",
    net: 4210.0,
    vat: 0,
    gross: 4210.0,
    status: "ok",
    statusLabel: "Booked",
  },
  {
    id: 3,
    date: "Apr 4",
    ref: "MAIL-88",
    text: "Google Ireland Ltd.",
    category: "Marketing",
    project: "Northwind",
    projectTint: "sky",
    net: -320.0,
    vat: 0,
    gross: -320.0,
    suggested: "Ledger",
    status: "signal",
    statusLabel: "Suggested",
  },
];
export default function Preview() {
  return (
    <div
      className="tf-col"
      style={{
        gap: 16,
      }}
    >
      <div className="tf-panel tf-panel-flush">
        <LedgerTable
          rows={rows}
          selectable
          categories={["Hosting", "Revenue", "Marketing", "Software"]}
          bulkActions={[
            {
              label: "Confirm",
              icon: "check",
              onClick: (r, c) => {
                c();
              },
            },
          ]}
        />
      </div>
      <div
        className="tf-grid"
        style={
          {
            "--cols": "1.4fr 1fr",
            gap: 16,
          } as React.CSSProperties
        }
      >
        <div className="tf-panel">
          <PnLStatement
            columns={["Jan", "Feb", "Mar"]}
            rows={[
              {
                kind: "section",
                label: "Revenue",
              },
              {
                label: "Subscriptions",
                values: [18200, 19400, 21100],
              },
              {
                label: "One-off",
                values: [2100, 1800, 2600],
              },
              {
                kind: "section",
                label: "Costs",
              },
              {
                label: "Hosting",
                values: [-820, -840, -910],
              },
              {
                label: "Marketing",
                values: [-4200, -3900, -5100],
              },
              {
                kind: "total",
                label: "Result",
                values: [15280, 16460, 17690],
              },
            ]}
          />
        </div>
        <ReceiptSuggestion
          file="Rechnung_2026-0412.pdf"
          source="From billing@hetzner.com · Apr 2"
          fields={[
            {
              label: "Vendor",
              value: "Hetzner Online GmbH",
              confidence: 0.99,
            },
            {
              label: "Date",
              value: "Apr 2, 2026",
              mono: true,
              confidence: 0.98,
            },
            {
              label: "Gross",
              value: "€100.00",
              mono: true,
              confidence: 0.97,
            },
            {
              label: "VAT",
              value: "19%",
              confidence: 0.72,
            },
          ]}
          suggestion="Hosting · Northwind · as every month"
          onConfirm={() => {}}
          onDiscard={() => {}}
        />
      </div>
    </div>
  );
}
```

### Props

#### LedgerTable

| Prop | Type | Notes |
| --- | --- | --- |
| `rows` | `LedgerRow[]` | Required |
| `categories?` | `string[]` |  |
| `onEdit?` | `(row: LedgerRow, change: Partial<LedgerRow>) => void` |  |
| `currency?` | `string` |  |
| `selectable?` | `boolean` |  |
| `bulkActions?` | `BulkAction<LedgerRow>[]` |  |
| `toolbar?` | `ReactNode` |  |
| `maxHeight?` | `number` |  |
| `columnToggle?` | `boolean` |  |
| `className?` | `string` | Extra class on the root element. |
| `style?` | `CSSProperties` | Inline style on the root element. |

#### PnLStatement

| Prop | Type | Notes |
| --- | --- | --- |
| `columns` | `string[]` | Required |
| `rows` | `{ kind?: "section" \| "subtotal" \| "total"; label: string; values?: number[] }[]` | Required |
| `currency?` | `string` |  |
| `total?` | `boolean` |  |
| `label?` | `string` |  |
| `className?` | `string` | Extra class on the root element. |
| `style?` | `CSSProperties` | Inline style on the root element. |

#### ReceiptSuggestion

| Prop | Type | Notes |
| --- | --- | --- |
| `file` | `string` | Required |
| `source?` | `ReactNode` |  |
| `fields` | `{ label: string; value: ReactNode; mono?: boolean; confidence?: number }[]` | Required |
| `suggestion?` | `ReactNode` |  |
| `onConfirm?` | `() => void` |  |
| `onDiscard?` | `() => void` |  |
| `confirmLabel?` | `string` |  |
| `discardLabel?` | `string` |  |
| `children?` | `ReactNode` |  |
| `className?` | `string` | Extra class on the root element. |
| `style?` | `CSSProperties` | Inline style on the root element. |


## Line Chart

> Charts in Twentyfirst UI.

Component · Charts · Halo kit · [Live page](https://ui.twentyfirst.media/halo/components/LineChart/)

### Example

```tsx
import { LineChart } from "@twentyfirstmedia/halo";

export default function Preview() {
  return (
    <div
      className="tf-panel"
      style={{
        maxWidth: 620,
      }}
    >
      <LineChart
        labels={["Jan", "Feb", "Mar", "Apr", "May", "Jun"]}
        format={(v) => "€" + Math.round(v / 1000) + "k"}
        series={[
          {
            values: [18000, 22000, 21000, 29000, 34000, 41000],
            tint: "mint",
            area: true,
          },
          {
            values: [12000, 14000, 17000, 16000, 21000, 24000],
            tint: "sky",
          },
        ]}
      />
    </div>
  );
}
```

### Props

#### LineChart

| Prop | Type | Notes |
| --- | --- | --- |
| `labels` | `string[]` | Required |
| `series` | `{ values: number[]; tint?: Tint \| "ink"; area?: boolean }[]` | Required |
| `height?` | `number` |  |
| `width?` | `number` |  |
| `format?` | `(v: number) => string` |  |
| `label?` | `string` |  |
| `className?` | `string` | Extra class on the root element. |
| `style?` | `CSSProperties` | Inline style on the root element. |


## List Row

> Data in Twentyfirst UI.

Component · Data · Halo kit · [Live page](https://ui.twentyfirst.media/halo/components/ListRow/)

### Example

```tsx
import { ListRow } from "@twentyfirstmedia/halo";

export default function Preview() {
  return (
    <div
      className="tf-list"
      style={{
        maxWidth: 380,
      }}
    >
      <ListRow
        avatar="Jonah Petit"
        title="Jonah Petit"
        subtitle="Can we move the review to Thursday?"
        meta="09:12"
        unread
        active
      />
      <ListRow
        avatar="Sun Lee"
        title="Sun Lee"
        subtitle="Payout file for March is attached"
        meta="Yesterday"
      />
      <ListRow
        icon="bell"
        tint="butter"
        title="Billing"
        subtitle="Card ending 4417 expires soon"
        meta="Mon"
      />
    </div>
  );
}
```

### Props

#### ListRow

| Prop | Type | Notes |
| --- | --- | --- |
| `avatar?` | `string` |  |
| `icon?` | `IconName` |  |
| `tint?` | `Tint \| "plain"` |  |
| `leading?` | `ReactNode` |  |
| `title` | `ReactNode` | Required |
| `subtitle?` | `ReactNode` |  |
| `meta?` | `ReactNode` |  |
| `trailing?` | `ReactNode` |  |
| `unread?` | `boolean` |  |
| `active?` | `boolean` |  |
| `onClick?` | `() => void` |  |
| `href?` | `string` | Makes the row a link (with `linkAs` for a router's link). |
| `linkAs?` | `ElementType` |  |
| `actions?` | `ReactNode` | Buttons of the row's own (rename, remove …), outside the clickable area so nothing interactive is nested. Without `onClick` and `href` the row is not interactive at all. |
| `titleLines?` | `number` | Lines the title may take before it ends in an ellipsis (default: it wraps freely). |
| `subtitleLines?` | `number` | Lines the subtitle may take (default 1); badges and facts wrap within them. |
| `className?` | `string` | Extra class on the root element. |
| `style?` | `CSSProperties` | Inline style on the root element. |


## Listing Card

> Property listings from portals or your own stock: ListingCard (grid card or list row) and ResultsToolbar (count, selection, bulk actions, sort, view).

Component · Real estate · Halo kit · [Live page](https://ui.twentyfirst.media/halo/components/ListingCard/)

Property listings from portals or your own stock: `ListingCard` (grid card or list row) and `ResultsToolbar` (count, selection, bulk actions, sort, view).

ListingCard: `listing` ({id, title, price (null = on request), rent, currency, pricePerSqm, area, rooms, place, image, photos, source, seller ("private" | "agent"), sellerLabel, phone, isNew, age, status, wished}), `layout` ("card" | "row"), `selected` + `onSelect`, `onWish`, `statusOptions` + `onStatus` (StatusSelect), `onOpen`.
ResultsToolbar: `title`, `total`, `meta`, `selected`, `onSelectAll(all)`, `bulkActions` ({label, icon, variant, busy, busyLabel, onClick}; shown while something is selected), `sortOptions` + `sort` + `onSort`, `views` ("grid" | "list" | "map") + `view` + `onView`.

- Area in m², money and counts follow `setLocale`.

### Example

```tsx
import * as React from "react";
import { ListingCard, ResultsToolbar } from "@twentyfirstmedia/halo";
import type { Listing, StatusSelectProps } from "@twentyfirstmedia/halo";

const st: StatusSelectProps["options"] = [
  {
    value: "unread",
    label: "New",
    status: "running",
  },
  {
    value: "read",
    label: "Seen",
    status: "idle",
  },
  {
    value: "contacted",
    label: "Contacted",
    status: "ok",
  },
];
const L0: Listing[] = [
  {
    id: 1,
    title: "Bright 3-room flat with balcony near Isebek canal",
    price: 649000,
    pricePerSqm: 7726,
    area: 84,
    rooms: 3,
    place: "Eppendorf, Hamburg",
    source: "ImmoScout",
    seller: "private",
    phone: true,
    photos: 14,
    isNew: true,
    age: "2 h",
    status: "unread",
    tint: "sky",
  },
  {
    id: 2,
    title: "Loft in HafenCity with water view",
    price: 1190000,
    pricePerSqm: 10625,
    area: 112,
    rooms: 2.5,
    place: "HafenCity, Hamburg",
    source: "Kleinanzeigen",
    seller: "agent",
    photos: 22,
    age: "1 d",
    status: "contacted",
    tint: "lilac",
    wished: true,
  },
  {
    id: 3,
    title: "2-room flat, renovated old building",
    price: 1480,
    rent: true,
    area: 58,
    rooms: 2,
    place: "Altona, Hamburg",
    source: "Immowelt",
    seller: "agent",
    photos: 9,
    age: "3 d",
    status: "read",
    tint: "mint",
  },
];
function App() {
  const sel = React.useState<(string | number)[]>([1]),
    list = React.useState(L0),
    view = React.useState("grid"),
    sort = React.useState("new");
  function tog(x: Listing) {
    sel[1](sel[0].indexOf(x.id) > -1 ? sel[0].filter((i) => i !== x.id) : sel[0].concat([x.id]));
  }
  return (
    <div
      className="tf-col"
      style={{
        gap: 16,
      }}
    >
      <ResultsToolbar
        title="Hamburg · flats to buy"
        total={128}
        meta="updated 06:00"
        selected={sel[0].length}
        onSelectAll={(all) => {
          sel[1](all ? list[0].map((x) => x.id) : []);
        }}
        bulkActions={[
          {
            label: "Send to CRM",
            icon: "send",
            variant: "primary",
          },
          {
            label: "Mark as seen",
            icon: "eye",
          },
        ]}
        sortOptions={[
          {
            value: "new",
            label: "Newest",
          },
          {
            value: "price",
            label: "Price",
          },
          {
            value: "sqm",
            label: "Price per m²",
          },
        ]}
        sort={sort[0]}
        onSort={sort[1]}
        views={["grid", "list", "map"]}
        view={view[0]}
        onView={view[1]}
      />
      <div
        className="tf-grid"
        style={
          view[0] === "list"
            ? {
                display: "flex",
                flexDirection: "column",
                gap: 12,
              }
            : ({
                "--cols": "repeat(3, minmax(0, 1fr))",
                gap: 16,
              } as React.CSSProperties)
        }
      >
        {list[0].map((x) => (
          <ListingCard
            key={x.id}
            listing={x}
            layout={view[0] === "list" ? "row" : "card"}
            selected={sel[0].indexOf(x.id) > -1}
            onSelect={tog}
            onWish={() => {}}
            statusOptions={st}
            onStatus={(l, s) => {
              list[1](
                list[0].map((y) =>
                  y.id === l.id
                    ? Object.assign({}, y, {
                        status: s,
                      })
                    : y,
                ),
              );
            }}
          />
        ))}
      </div>
    </div>
  );
}
export default App;
```

### Props

#### ListingCard

| Prop | Type | Notes |
| --- | --- | --- |
| `listing` | `Listing` | Required |
| `layout?` | `"card" \| "row"` |  |
| `selected?` | `boolean` |  |
| `onSelect?` | `(l: Listing) => void` |  |
| `onWish?` | `(l: Listing) => void` |  |
| `statusOptions?` | `StatusSelectProps["options"]` |  |
| `onStatus?` | `(l: Listing, status: string) => void` |  |
| `onOpen?` | `(l: Listing) => void` |  |
| `className?` | `string` | Extra class on the root element. |
| `style?` | `CSSProperties` | Inline style on the root element. |

#### ResultsToolbar

| Prop | Type | Notes |
| --- | --- | --- |
| `title?` | `string` |  |
| `total` | `number` | Required |
| `meta?` | `string` |  |
| `selected?` | `number` |  |
| `onSelectAll?` | `(all: boolean) => void` |  |
| `bulkActions?` | `{ label: string; icon?: IconName; variant?: ButtonProps["variant"]; busy?: boolean; busyLabel?: string; onClick?: () => void; }[]` |  |
| `sortOptions?` | `{ value: string; label: string }[]` |  |
| `sort?` | `string` |  |
| `onSort?` | `(v: string) => void` |  |
| `views?` | `("grid" \| "list" \| "map")[]` |  |
| `view?` | `string` |  |
| `onView?` | `(v: string) => void` |  |
| `className?` | `string` | Extra class on the root element. |
| `style?` | `CSSProperties` | Inline style on the root element. |


## Live Feed

> Real-time activity: LiveFeed (events as they happen, with pause and filters) and BarList (ranked values with inline bars, e.g.

Component · Data · Halo kit · [Live page](https://ui.twentyfirst.media/halo/components/LiveFeed/)

Real-time activity: `LiveFeed` (events as they happen, with pause and filters) and `BarList` (ranked values with inline bars, e.g. top countries or services).

LiveFeed: `items` ({id, type, icon, tint, title, text, amount, currency, time, fresh}), `types` ({value, label} filter chips), `paused` / `onPause`, `maxHeight`, `emptyText`. While paused, new events are held back and counted.
BarList: `items` ({id, label, mark, value, share (0–1), tint}), `format`, `onPick(item)`, `label`.

- Show at most ~50 events; older ones belong in a table.
- `fresh` slides a row in once; it never blinks or repeats.

### Example

```tsx
import * as React from "react";
import { BarList, LiveFeed, formatMoney } from "@twentyfirstmedia/halo";
import type { LiveFeedItem, LiveFeedProps } from "@twentyfirstmedia/halo";

const types: LiveFeedProps["types"] = [
  {
    value: "order",
    label: "Orders",
  },
  {
    value: "payment",
    label: "Payments",
  },
  {
    value: "error",
    label: "Errors",
  },
];
const seed: LiveFeedItem[] = [
  {
    id: 1,
    type: "order",
    icon: "cart",
    tint: "mint",
    title: "1,000 Instagram followers",
    text: "Order #48213 · Germany · PayPal",
    amount: 12.9,
    time: "2s",
  },
  {
    id: 2,
    type: "payment",
    icon: "card",
    tint: "sky",
    title: "Payment received",
    text: "Stripe · card ending 4242",
    amount: 39,
    time: "14s",
  },
  {
    id: 3,
    type: "error",
    icon: "zap",
    tint: "blush",
    title: "Provider timeout",
    text: "SMM provider B · retried",
    time: "41s",
  },
  {
    id: 4,
    type: "order",
    icon: "cart",
    tint: "mint",
    title: "5,000 TikTok views",
    text: "Order #48212 · Austria",
    amount: 4.9,
    time: "1m",
  },
];
function App() {
  const it = React.useState<LiveFeedItem[]>(seed);
  React.useEffect(() => {
    let n = 100;
    const t = setInterval(() => {
      n++;
      it[1]((l): LiveFeedItem[] => [
        {
          id: n,
          type: "order",
          icon: "cart",
          tint: "mint",
          title: ((n % 3) + 1) * 500 + " starter kits",
          text: "Order #" + (48213 + n - 100) + " · Switzerland",
          amount: 2.9 + (n % 5),
          time: "now",
          fresh: true,
        },
        ...l.slice(0, 7),
      ]);
    }, 2600);
    return () => {
      clearInterval(t);
    };
  }, []);
  return (
    <div
      className="tf-grid"
      style={
        {
          "--cols": "1.4fr 1fr",
          gap: 16,
          alignItems: "start",
        } as React.CSSProperties
      }
    >
      <div className="tf-panel">
        <LiveFeed items={it[0]} types={types} maxHeight={420} />
      </div>
      <div
        className="tf-panel"
        style={{
          gap: 12,
        }}
      >
        <b>Revenue by country</b>
        <BarList
          format={(v) => formatMoney(v)}
          items={[
            {
              label: "Germany",
              mark: "🇩🇪",
              value: 18240,
              share: 0.52,
            },
            {
              label: "Austria",
              mark: "🇦🇹",
              value: 6120,
              share: 0.17,
            },
            {
              label: "Switzerland",
              mark: "🇨🇭",
              value: 5480,
              share: 0.16,
              tint: "mint",
            },
            {
              label: "Netherlands",
              mark: "🇳🇱",
              value: 2210,
              share: 0.06,
              tint: "butter",
            },
            {
              label: "Other",
              value: 3100,
              share: 0.09,
              tint: "lilac",
            },
          ]}
        />
      </div>
    </div>
  );
}
export default App;
```

### Props

#### BarList

| Prop | Type | Notes |
| --- | --- | --- |
| `items` | `{ id?: string; label: ReactNode; mark?: ReactNode; value: number; share?: number; tint?: Tint; }[]` | Required |
| `format?` | `(v: number) => string` |  |
| `onPick?` | `(item: NonNullable<BarListProps["items"]>[number]) => void` |  |
| `label?` | `string` |  |
| `className?` | `string` | Extra class on the root element. |
| `style?` | `CSSProperties` | Inline style on the root element. |

#### LiveFeed

| Prop | Type | Notes |
| --- | --- | --- |
| `items` | `LiveFeedItem[]` | Required |
| `types?` | `{ value: string; label: string }[]` |  |
| `paused?` | `boolean` |  |
| `onPause?` | `(paused: boolean) => void` |  |
| `maxHeight?` | `number` |  |
| `emptyText?` | `string` |  |
| `className?` | `string` | Extra class on the root element. |
| `style?` | `CSSProperties` | Inline style on the root element. |


## Locale Field

> Content in several languages and switching context: LocaleField, LocaleSwitcher, WorkspaceSwitcher.

Component · Forms · Halo kit · [Live page](https://ui.twentyfirst.media/halo/components/LocaleField/)

Content in several languages and switching context: `LocaleField`, `LocaleSwitcher`, `WorkspaceSwitcher`.

LocaleField: `label`, `locales` ({code, label, flag}), `value` / `defaultValue` ({[code]: text}) + `onChange`, `source` (language others copy from; default the first), `active`, `multiline`, `rows`, `onTranslate(text, to)` (return or resolve the translation), `hint`, `error`. Missing languages carry a warn diamond; empty fields show the source text as placeholder.
LocaleSwitcher: `languages` ({code, label, short, flag}), `language` / `onLanguage`, `currencies`, `currency` / `onCurrency`, `variant` ("frame" for the dark top bar).
WorkspaceSwitcher: `items` ({id, name, sub, tint, logo}), `value` / `onChange`, `label`, `footer`, `variant` ("frame").

### Example

```tsx
import * as React from "react";
import { LocaleField, LocaleSwitcher, WorkspaceSwitcher } from "@twentyfirstmedia/halo";

const langs = [
  {
    code: "de",
    label: "Deutsch",
    short: "de",
    flag: "🇩🇪",
  },
  {
    code: "en",
    label: "English",
    short: "en",
    flag: "🇬🇧",
  },
  {
    code: "fr",
    label: "Français",
    short: "fr",
    flag: "🇫🇷",
  },
];
export default function Preview() {
  return (
    <div
      className="tf-grid"
      style={
        {
          "--cols": "1.3fr 1fr",
          gap: 16,
          alignItems: "start",
        } as React.CSSProperties
      }
    >
      <div
        className="tf-panel"
        style={{
          gap: 20,
        }}
      >
        <LocaleField
          label="Product name"
          locales={[
            {
              code: "de",
              label: "DE",
            },
            {
              code: "en",
              label: "EN",
            },
            {
              code: "fr",
              label: "FR",
            },
            {
              code: "es",
              label: "ES",
            },
          ]}
          defaultValue={{
            de: "Instagram Follower kaufen",
            en: "Buy Instagram followers",
          }}
          onTranslate={(t, to) => "[" + to + "] " + t}
        />
        <LocaleField
          label="Short description"
          multiline
          active="en"
          locales={[
            {
              code: "de",
              label: "DE",
            },
            {
              code: "en",
              label: "EN",
            },
          ]}
          defaultValue={{
            de: "Echte Follower, Lieferung in einer Stunde.",
          }}
        />
      </div>
      <div
        className="tf-panel"
        style={{
          gap: 16,
          alignItems: "flex-start",
        }}
      >
        <WorkspaceSwitcher
          label="Shops"
          items={[
            {
              id: "fp",
              name: "Northwind",
              sub: "northwind.de",
              tint: "sky",
            },
            {
              id: "fm",
              name: "FollowerMarket",
              sub: "followermarket.com",
              tint: "mint",
            },
            {
              id: "fr",
              name: "FollowerRocket",
              sub: "followerrocket.de",
              tint: "butter",
            },
          ]}
        />
        <LocaleSwitcher languages={langs} currencies={["EUR", "CHF", "USD"]} />
      </div>
    </div>
  );
}
```

### Props

#### LocaleField

| Prop | Type | Notes |
| --- | --- | --- |
| `label?` | `ReactNode` |  |
| `locales` | `{ code: string; label?: string; flag?: string }[]` | Required |
| `value?` | `Record<string, string>` |  |
| `defaultValue?` | `Record<string, string>` |  |
| `onChange?` | `(v: Record<string, string>) => void` |  |
| `source?` | `string` |  |
| `active?` | `string` |  |
| `multiline?` | `boolean` |  |
| `rows?` | `number` |  |
| `placeholder?` | `string` |  |
| `onTranslate?` | `(text: string, to: string) => string \| Promise<string>` |  |
| `hint?` | `ReactNode` |  |
| `error?` | `ReactNode` |  |
| `className?` | `string` | Extra class on the root element. |
| `style?` | `CSSProperties` | Inline style on the root element. |

#### LocaleSwitcher

| Prop | Type | Notes |
| --- | --- | --- |
| `languages?` | `{ code: string; label: string; short?: string; flag?: string }[]` |  |
| `language?` | `string` |  |
| `onLanguage?` | `(code: string) => void` |  |
| `currencies?` | `string[]` |  |
| `currency?` | `string` |  |
| `onCurrency?` | `(c: string) => void` |  |
| `variant?` | `"frame"` |  |
| `className?` | `string` | Extra class on the root element. |
| `style?` | `CSSProperties` | Inline style on the root element. |

#### WorkspaceSwitcher

| Prop | Type | Notes |
| --- | --- | --- |
| `items` | `{ id: string; name: string; sub?: string; tint?: Tint; logo?: ReactNode }[]` | Required |
| `value?` | `string` |  |
| `onChange?` | `(id: string) => void` |  |
| `label?` | `string` |  |
| `footer?` | `ReactNode` |  |
| `variant?` | `"frame"` |  |
| `width?` | `number` |  |
| `compact?` | `boolean` | Only the workspace's mark, its name as the accessible name (a collapsed sidebar). |
| `className?` | `string` | Extra class on the root element. |
| `style?` | `CSSProperties` | Inline style on the root element. |


## Log View

> Monospace output: LogView for logs with line numbers and levels, CodeViewer for JSON, YAML and code.

Component · Foundations · Halo kit · [Live page](https://ui.twentyfirst.media/halo/components/LogView/)

Monospace output: `LogView` for logs with line numbers and levels, `CodeViewer` for JSON, YAML and code.

LogView: `lines` (strings or {time, text, level: "ok" | "warn" | "err" | "hl", fresh}), `title`, `right`, `numbers` (false hides them), `follow` (default true: sticks to the newest line unless the pointer is over it), `maxHeight`.
CodeViewer: `value` (string or object, pretty-printed as JSON), `lang`. Built on CodeBlock with copy.

### Example

```tsx
import { CodeViewer, LogView } from "@twentyfirstmedia/halo";
import type { LogLine } from "@twentyfirstmedia/halo";

const lines: LogLine[] = [
  {
    time: "09:41:02",
    text: "pull  ghcr.io/halo/web:8f2a91c",
    level: "hl",
  },
  {
    time: "09:41:09",
    text: "build  146 modules transformed",
  },
  {
    time: "09:41:22",
    text: "test   146 passed, 0 failed",
    level: "ok",
  },
  {
    time: "09:41:23",
    text: "warn   bundle is 512 kB, above the 500 kB budget",
    level: "warn",
  },
  {
    time: "09:41:30",
    text: "health GET /v1/health → 503",
    level: "err",
  },
];
export default function Preview() {
  return (
    <div
      className="tf-col"
      style={{
        gap: 16,
      }}
    >
      <LogView title="deploy #482" lines={lines} />
      <CodeViewer
        value={{
          tool: "cloudflare.dns",
          action: "create",
          record: {
            type: "TXT",
            name: "ops-test",
            ttl: 300,
          },
        }}
      />
    </div>
  );
}
```

### Props

#### CodeViewer

| Prop | Type | Notes |
| --- | --- | --- |
| `value` | `string \| object` | Required |
| `lang?` | `string` |  |
| `className?` | `string` | Extra class on the root element. |
| `style?` | `CSSProperties` | Inline style on the root element. |

#### LogView

| Prop | Type | Notes |
| --- | --- | --- |
| `lines` | `LogLine[]` | Required |
| `title?` | `ReactNode` |  |
| `right?` | `ReactNode` |  |
| `numbers?` | `boolean` |  |
| `follow?` | `boolean` |  |
| `maxHeight?` | `number` |  |
| `className?` | `string` | Extra class on the root element. |
| `style?` | `CSSProperties` | Inline style on the root element. |


## Map View

> Points on a map: price pins for listings or bubbles for where orders come from.

Component · Data · Halo kit · [Live page](https://ui.twentyfirst.media/halo/components/MapView/)

Points on a map: price pins for listings or bubbles for where orders come from. The map itself (tiles from MapLibre, Leaflet or Google, an SVG or an image) goes in `background`; Halo draws pins, popups, legend and controls on top in its own style.

Props: `points` ({id, label, sub, lat, lng, value, text (pin label), tint, pulse}), `bounds` ({n, s, w, e}; what the background shows), `background` (node), `bubbles` (size by value instead of pins), `selected` / `onSelect`, `renderPopup(point)`, `legend`, `controls`, `height`, `label`.

- With a real map library, pass its projection's bounds or render the pins through its overlay API with the same classes (`tf-map-pin`, `tf-map-pop`).
- Price pins show the short price; the popup carries the details.

### Example

```tsx
import * as React from "react";
import { IconButton, MapView } from "@twentyfirstmedia/halo";
import type { MapPoint } from "@twentyfirstmedia/halo";

const world: MapPoint[] = [
  {
    id: "de",
    label: "Germany",
    lat: 51,
    lng: 10,
    value: 820,
    sub: "820 orders today",
  },
  {
    id: "at",
    label: "Austria",
    lat: 47.5,
    lng: 14.5,
    value: 260,
    tint: "mint",
  },
  {
    id: "ch",
    label: "Switzerland",
    lat: 46.8,
    lng: 8.2,
    value: 210,
    tint: "mint",
  },
  {
    id: "us",
    label: "United States",
    lat: 39,
    lng: -98,
    value: 140,
    tint: "butter",
  },
  {
    id: "ae",
    label: "UAE",
    lat: 24,
    lng: 54,
    value: 90,
    tint: "lilac",
    pulse: true,
  },
  {
    id: "br",
    label: "Brazil",
    lat: -12,
    lng: -52,
    value: 60,
    tint: "blush",
  },
];
const city: MapPoint[] = [
  {
    id: 1,
    label: "3-room flat, Eppendorf",
    sub: "€649,000 · 84 m²",
    lat: 53.59,
    lng: 9.98,
    text: "€649k",
  },
  {
    id: 2,
    label: "Loft, HafenCity",
    sub: "€1,190,000 · 112 m²",
    lat: 53.541,
    lng: 10.0,
    text: "€1.19m",
    tint: "lilac",
  },
  {
    id: 3,
    label: "2-room flat, Altona",
    sub: "€1,480 / month",
    lat: 53.55,
    lng: 9.935,
    text: "€1,480",
    tint: "mint",
  },
  {
    id: 4,
    label: "House, Blankenese",
    lat: 53.565,
    lng: 9.81,
    text: "€2.4m",
    tint: "butter",
  },
];
export default function Preview() {
  return (
    <div
      className="tf-grid"
      style={
        {
          "--cols": "1fr 1fr",
          gap: 16,
        } as React.CSSProperties
      }
    >
      <div
        className="tf-panel"
        style={{
          gap: 12,
        }}
      >
        <b>Orders by country</b>
        <MapView bubbles points={world} height={360} legend="Bubble size = orders today" />
      </div>
      <div
        className="tf-panel"
        style={{
          gap: 12,
        }}
      >
        <b>Listings</b>
        <MapView
          points={city}
          bounds={{
            n: 53.62,
            s: 53.52,
            w: 9.78,
            e: 10.06,
          }}
          height={360}
          selected={2}
          controls={[
            <IconButton key={1} icon="plus" label="Zoom in" size="sm" />,
            <IconButton key={2} icon="minus" label="Zoom out" size="sm" />,
          ]}
        />
      </div>
    </div>
  );
}
```

### Props

#### IconButton

| Prop | Type | Notes |
| --- | --- | --- |
| `icon` | `IconName` | Required |
| `label` | `string` | Accessible name and tooltip (`aria-label` and `title`); `aria-label` or `title` override them. |
| `variant?` | `"soft" \| "solid" \| "outline" \| "ghost"` |  |
| `size?` | `"sm" \| "md" \| "lg"` |  |
| `type?` | `"button" \| "submit" \| "reset"` |  |
| `onClick?` | `(e: MouseEvent<HTMLButtonElement>) => void` |  |
| `disabled?` | `boolean` |  |
| `asChild?` | `boolean` | Render the single child element (a link) with the button's look; the icon is placed inside it. |
| `children?` | `ReactNode` |  |
| `id?` | `string` |  |
| `name?` | `string` | Form field name and value, sent with the form when this button submits it. |
| `value?` | `string` |  |
| `form?` | `string` | The id of the form this button belongs to, when it sits outside it. |
| `title?` | `string` |  |
| `tabIndex?` | `number` |  |
| `autoFocus?` | `boolean` |  |
| `aria-label?` | `string` |  |
| `aria-labelledby?` | `string` |  |
| `aria-describedby?` | `string` |  |
| `aria-expanded?` | `boolean \| "true" \| "false"` | For disclosure and menu triggers: whether what the button controls is open. |
| `aria-controls?` | `string` |  |
| `aria-haspopup?` | `boolean \| "true" \| "false" \| "menu" \| "listbox" \| "tree" \| "grid" \| "dialog"` |  |
| `aria-pressed?` | `boolean \| "true" \| "false" \| "mixed"` | For toggle buttons. |
| `aria-current?` | `boolean \| "true" \| "false" \| "page" \| "step" \| "location" \| "date" \| "time"` |  |
| `className?` | `string` | Extra class on the root element. |
| `style?` | `CSSProperties` | Inline style on the root element. |

#### MapView

| Prop | Type | Notes |
| --- | --- | --- |
| `points?` | `MapPoint[]` |  |
| `bounds?` | `{ n: number; s: number; w: number; e: number }` |  |
| `background?` | `ReactNode` |  |
| `bubbles?` | `boolean` |  |
| `selected?` | `MapPoint["id"] \| null` |  |
| `onSelect?` | `(id: MapPoint["id"] \| null) => void` |  |
| `renderPopup?` | `(p: MapPoint) => ReactNode` |  |
| `legend?` | `ReactNode` |  |
| `controls?` | `ReactNode` |  |
| `height?` | `number \| string` | Height in px (default 320) or any CSS length, e.g. "100%" to fill a FloatingLayout. |
| `label?` | `string` |  |
| `surface?` | `Surface` | `"glass"`: the legend, controls and popup float as glass over the map (for a live map in `background`). |
| `className?` | `string` |  |
| `style?` | `CSSProperties` | Inline style on the root element. |


## Memory Viewer

> What an agent remembers (MemoryViewer) and how its runtime settings differ from code (OverrideDiff).

Component · AI · Halo kit · [Live page](https://ui.twentyfirst.media/halo/components/MemoryViewer/)

What an agent remembers (`MemoryViewer`) and how its runtime settings differ from code (`OverrideDiff`).

MemoryViewer: `items` ({id, scope, source, date, text}), `onEdit(item)`, `onDelete(item)`. Search and scope chips built in.
OverrideDiff: `title`, `versions`, `by`, `before`, `after` (text, diffed by line), `onDiscard`, `onPromote`, `discardLabel`, `promoteLabel`.

### Example

```tsx
import * as React from "react";
import { MemoryViewer, OverrideDiff } from "@twentyfirstmedia/halo";

const mem = [
  {
    id: 1,
    scope: "Agent",
    source: "Chat",
    date: "Apr 12",
    text: "Ida at Northwind prefers short replies and a quote attached.",
  },
  {
    id: 2,
    scope: "Project",
    source: "Feedback",
    date: "Apr 9",
    text: "Never promise refunds; hand them to a person.",
  },
  {
    id: 3,
    scope: "Global",
    source: "Import",
    date: "Apr 2",
    text: "Company is FollowerX GmbH, Hamburg.",
  },
];
export default function Preview() {
  return (
    <div
      className="tf-grid"
      style={
        {
          "--cols": "1fr 1fr",
          gap: 16,
          alignItems: "start",
        } as React.CSSProperties
      }
    >
      <div className="tf-panel">
        <MemoryViewer items={mem} onEdit={() => {}} onDelete={() => {}} />
      </div>
      <OverrideDiff
        title="Instruction"
        versions="Code default v1 → Override v3"
        by="Main Brain after feedback"
        before={"You are Atlas, the support agent.\nBe friendly.\nAnswer within one day."}
        after={
          "You are Atlas, the support agent.\nBe brief and friendly.\nAnswer within one day.\nNever promise refunds."
        }
        onDiscard={() => {}}
        onPromote={() => {}}
      />
    </div>
  );
}
```

### Props

#### MemoryViewer

| Prop | Type | Notes |
| --- | --- | --- |
| `items` | `{ id: string \| number; scope: string; source?: string; date?: string; text: string }[]` | Required |
| `onEdit?` | `(item: NonNullable<MemoryViewerProps["items"]>[number]) => void` |  |
| `onDelete?` | `(item: NonNullable<MemoryViewerProps["items"]>[number]) => void` |  |
| `className?` | `string` | Extra class on the root element. |
| `style?` | `CSSProperties` | Inline style on the root element. |

#### OverrideDiff

| Prop | Type | Notes |
| --- | --- | --- |
| `title?` | `string` |  |
| `versions?` | `ReactNode` |  |
| `by?` | `ReactNode` |  |
| `before` | `string` | Required |
| `after` | `string` | Required |
| `onDiscard?` | `() => void` |  |
| `onPromote?` | `() => void` |  |
| `discardLabel?` | `string` |  |
| `promoteLabel?` | `string` |  |
| `className?` | `string` | Extra class on the root element. |
| `style?` | `CSSProperties` | Inline style on the root element. |


## Menu

> Overlays in Twentyfirst UI.

Component · Overlays · Halo kit · [Live page](https://ui.twentyfirst.media/halo/components/Menu/)

### Example

```tsx
import * as React from "react";
import { Menu } from "@twentyfirstmedia/halo";

export default function Preview() {
  const [grid, setGrid] = React.useState(true);
  const [density, setDensity] = React.useState("comfortable");
  return (
    <div className="tf-row" style={{ gap: 24, alignItems: "flex-start", paddingBottom: 120 }}>
      <Menu
        items={[
          {
            label: "Open",
            icon: "eye",
            shortcut: "↵",
          },
          {
            label: "Rename",
            icon: "edit",
            shortcut: "R",
          },
          {
            label: "Duplicate",
            icon: "file",
          },
          {
            label: "Share link",
            icon: "link",
          },
          "-",
          {
            label: "Delete",
            icon: "trash",
            danger: true,
          },
        ]}
      />
      <Menu
        label="View"
        items={[
          { label: "Show grid", type: "checkbox", checked: grid, onClick: () => setGrid(!grid) },
          { label: "Show minimap", type: "checkbox", checked: false },
          "-",
          {
            label: "Comfortable",
            type: "radio",
            group: "density",
            checked: density === "comfortable",
            onClick: () => setDensity("comfortable"),
          },
          {
            label: "Compact",
            type: "radio",
            group: "density",
            checked: density === "compact",
            onClick: () => setDensity("compact"),
          },
          "-",
          {
            label: "Sort by",
            icon: "list",
            items: [
              { label: "Name", type: "radio", checked: true },
              { label: "Last change", type: "radio" },
              { label: "Size", type: "radio" },
            ],
          },
          { label: "Export as PDF", icon: "download", disabled: true },
        ]}
      />
    </div>
  );
}
```

### Props

#### Menu

| Prop | Type | Notes |
| --- | --- | --- |
| `items` | `(MenuItem \| "-")[]` | Required |
| `label?` | `string` | Accessible name of the menu. |
| `autoFocus?` | `boolean` | Focus the first item on mount (menus opened from a button or the keyboard). |
| `onClose?` | `() => void` | Called after an item runs, and on Escape, so the owner can close the menu. |
| `className?` | `string` | Extra class on the root element. |
| `style?` | `CSSProperties` | Inline style on the root element. |


## Mobile Tab Bar

> Phone chrome: MobileTabBar (bottom navigation) and PushNotification (how an approval arrives on the lock screen).

Component · Overlays · Halo kit · [Live page](https://ui.twentyfirst.media/halo/components/MobileTabBar/)

Phone chrome: `MobileTabBar` (bottom navigation) and `PushNotification` (how an approval arrives on the lock screen).

MobileTabBar: `items` ({id, label, icon, count}), `active`, `onPick`, `label`.
PushNotification: `app`, `time`, `title`, `text`, `actions` ({label, onClick}). Only A can be answered from the notification; B–D open the app.

### Example

```tsx
import * as React from "react";
import { MobileTabBar, PushNotification } from "@twentyfirstmedia/halo";

function App() {
  const a = React.useState("approvals");
  return (
    <div
      className="tf-col"
      style={{
        gap: 16,
        alignItems: "center",
      }}
    >
      <PushNotification
        app="Halo"
        time="now"
        title="Approval needed · Atlas"
        text="Send this email to ida@northwind.io?"
        actions={[
          {
            label: "A · Run it",
          },
          {
            label: "Open",
          },
        ]}
      />
      <div
        style={{
          width: 390,
          boxSizing: "border-box",
          maxWidth: "100%",
        }}
      >
        <MobileTabBar
          active={a[0]}
          onPick={a[1]}
          items={[
            {
              id: "home",
              label: "Home",
              icon: "home",
            },
            {
              id: "approvals",
              label: "Approvals",
              icon: "check",
              count: 3,
            },
            {
              id: "mail",
              label: "Mail",
              icon: "mail",
            },
            {
              id: "more",
              label: "More",
              icon: "menu",
            },
          ]}
        />
      </div>
    </div>
  );
}
export default App;
```

### Props

#### MobileTabBar

| Prop | Type | Notes |
| --- | --- | --- |
| `items` | `{ id: string; label: string; icon: IconName; count?: number }[]` | Required |
| `active?` | `string` |  |
| `onPick?` | `(id: string) => void` |  |
| `label?` | `string` |  |
| `className?` | `string` | Extra class on the root element. |
| `style?` | `CSSProperties` | Inline style on the root element. |

#### PushNotification

| Prop | Type | Notes |
| --- | --- | --- |
| `app?` | `string` |  |
| `time?` | `string` |  |
| `title` | `string` | Required |
| `text?` | `ReactNode` |  |
| `actions?` | `{ label: string; onClick?: () => void }[]` |  |
| `className?` | `string` | Extra class on the root element. |
| `style?` | `CSSProperties` | Inline style on the root element. |


## Modal

> Overlays in Twentyfirst UI.

Component · Overlays · Halo kit · [Live page](https://ui.twentyfirst.media/halo/components/Modal/)

### Example

```tsx
import { Button, Input, Modal } from "@twentyfirstmedia/halo";

export default function Preview() {
  return (
    <div
      style={{
        height: 340,
        position: "relative",
        borderRadius: "var(--radius-lg)",
        overflow: "hidden",
        background: "var(--canvas)",
      }}
    >
      <Modal
        style={{
          position: "absolute",
          inset: 0,
        }}
        icon="users"
        tint="sky"
        title="Invite teammates"
        text="They get access to every project in this workspace."
        actions={[
          <Button key={1} variant="ghost">
            Cancel
          </Button>,
          <Button key={2} icon="send">
            Send invites
          </Button>,
        ]}
      >
        <Input label="Email addresses" placeholder="name@company.com, …" />
      </Modal>
    </div>
  );
}
```

### Props

#### Button

| Prop | Type | Notes |
| --- | --- | --- |
| `variant?` | `"primary" \| "secondary" \| "soft" \| "ghost" \| "danger" \| "danger-solid"` |  |
| `size?` | `"md" \| "sm"` |  |
| `icon?` | `IconName` |  |
| `iconRight?` | `IconName` |  |
| `disabled?` | `boolean` |  |
| `type?` | `"button" \| "submit" \| "reset"` |  |
| `onClick?` | `(e: MouseEvent<HTMLButtonElement>) => void` |  |
| `children?` | `ReactNode` |  |
| `asChild?` | `boolean` | Render the single child element (a link, a router Link) with the button's look instead of a <button>. |
| `id?` | `string` |  |
| `name?` | `string` | Form field name and value, sent with the form when this button submits it. |
| `value?` | `string` |  |
| `form?` | `string` | The id of the form this button belongs to, when it sits outside it. |
| `title?` | `string` |  |
| `tabIndex?` | `number` |  |
| `autoFocus?` | `boolean` |  |
| `aria-label?` | `string` |  |
| `aria-labelledby?` | `string` |  |
| `aria-describedby?` | `string` |  |
| `aria-expanded?` | `boolean \| "true" \| "false"` | For disclosure and menu triggers: whether what the button controls is open. |
| `aria-controls?` | `string` |  |
| `aria-haspopup?` | `boolean \| "true" \| "false" \| "menu" \| "listbox" \| "tree" \| "grid" \| "dialog"` |  |
| `aria-pressed?` | `boolean \| "true" \| "false" \| "mixed"` | For toggle buttons. |
| `aria-current?` | `boolean \| "true" \| "false" \| "page" \| "step" \| "location" \| "date" \| "time"` |  |
| `className?` | `string` | Extra class on the root element. |
| `style?` | `CSSProperties` | Inline style on the root element. |

#### Input

| Prop | Type | Notes |
| --- | --- | --- |
| `type?` | `string` |  |
| `placeholder?` | `string` |  |
| `value?` | `string` |  |
| `defaultValue?` | `string` |  |
| `disabled?` | `boolean` |  |
| `onChange?` | `(e: ChangeEvent<HTMLInputElement>) => void` |  |
| `label?` | `string` |  |
| `hint?` | `string` |  |
| `error?` | `string` |  |
| `className?` | `string` | Extra class on the root element. |
| `style?` | `CSSProperties` | Inline style on the root element. |

#### Modal

| Prop | Type | Notes |
| --- | --- | --- |
| `title` | `string` | Required |
| `text?` | `string` |  |
| `icon?` | `IconName` |  |
| `tint?` | `Tint` |  |
| `actions?` | `ReactNode[]` |  |
| `onClose?` | `() => void` |  |
| `style?` | `CSSProperties` |  |
| `children?` | `ReactNode` |  |
| `open?` | `boolean` | Optional: with `open` the component stays mounted while it animates out; without it, render it only while open. |
| `className?` | `string` | Extra class on the root element. |


## Notification List

> Overlays in Twentyfirst UI.

Component · Overlays · Halo kit · [Live page](https://ui.twentyfirst.media/halo/components/NotificationList/)

### Example

```tsx
import { NotificationList } from "@twentyfirstmedia/halo";

export default function Preview() {
  return (
    <div
      style={{
        width: 380,
        boxSizing: "border-box",
        maxWidth: "100%",
        background: "var(--surface)",
        borderRadius: "var(--radius-lg)",
        padding: 8,
        boxShadow: "var(--shadow-float)",
      }}
    >
      <NotificationList
        items={[
          {
            id: 1,
            icon: "bot",
            tint: "lilac",
            title: "Atlas needs your approval",
            text: "4 reply drafts are waiting",
            time: "07:55",
            unread: true,
          },
          {
            id: 2,
            icon: "flag",
            tint: "blush",
            title: "Invoice #2041 is overdue",
            text: "Harbor & Co · €860",
            time: "07:30",
            unread: true,
          },
          {
            id: 3,
            icon: "zap",
            tint: "mint",
            title: "halo-web is live",
            text: "Add seat selector to checkout",
            time: "Yesterday",
          },
          {
            id: 4,
            icon: "users",
            tint: "sky",
            title: "Ava Brandt joined",
            text: "Invited as Viewer",
            time: "Mon",
          },
        ]}
      />
    </div>
  );
}
```

### Props

#### NotificationList

| Prop | Type | Notes |
| --- | --- | --- |
| `items` | `NotificationItem[]` | Required |
| `onOpen?` | `(n: NotificationItem) => void` |  |
| `onReadAll?` | `() => void` |  |
| `className?` | `string` | Extra class on the root element. |
| `style?` | `CSSProperties` | Inline style on the root element. |


## Number Input

> Number entry three ways: NumberInput with − / + steppers, Slider for a value on a known scale, OtpInput for one-time codes.

Component · Forms · Halo kit · [Live page](https://ui.twentyfirst.media/halo/components/NumberInput/)

Number entry three ways: `NumberInput` with − / + steppers, `Slider` for a value on a known scale, `OtpInput` for one-time codes.

NumberInput: `label`, `value`/`defaultValue`, `onChange(n)`, `min`, `max`, `step`, `unit`, `hint`.
Slider: `label`, `min`, `max`, `step`, `value`/`defaultValue`, `onChange(n)`, `format(v)`, `marks` (false hides min/max), `hint`.
OtpInput: `length` (6), `onComplete(code)`, `error` (shakes and turns red), `label`.

- NumberInput for small exact counts (seats, days); arrow keys step too.
- Slider when the range matters more than the exact value (budgets, thresholds); always show the value bubble.
- OtpInput moves focus forward as you type, back on Backspace, and fills every box on paste.

### Example

```tsx
import * as React from "react";
import { NumberInput, OtpInput, Slider } from "@twentyfirstmedia/halo";

function App() {
  const s = React.useState(12),
    b = React.useState(120);
  return (
    <div
      className="tf-panel"
      style={{
        gap: 24,
      }}
    >
      <div
        style={{
          display: "flex",
          gap: 32,
          flexWrap: "wrap",
          alignItems: "flex-start",
        }}
      >
        <NumberInput
          label="Seats"
          value={s[0]}
          onChange={s[1]}
          min={1}
          max={200}
          hint="€24 per seat"
        />
        <NumberInput label="VAT" defaultValue={19} min={0} max={25} unit="%" />
        <div className="tf-field">
          <span className="tf-field-label">Verification code</span>
          <OtpInput onComplete={() => {}} />
          <span className="tf-field-hint">Paste works too</span>
        </div>
      </div>
      <Slider
        label="Monthly agent budget"
        min={0}
        max={500}
        step={10}
        value={b[0]}
        onChange={b[1]}
        format={(v) => "€" + v}
        hint="Agents pause and ask you once they reach it"
      />
    </div>
  );
}
export default App;
```

### Props

#### NumberInput

| Prop | Type | Notes |
| --- | --- | --- |
| `label?` | `string` |  |
| `value?` | `number` |  |
| `defaultValue?` | `number` |  |
| `onChange?` | `(n: number) => void` |  |
| `min?` | `number` |  |
| `max?` | `number` |  |
| `step?` | `number` |  |
| `unit?` | `string` |  |
| `hint?` | `string` |  |
| `error?` | `string` |  |
| `className?` | `string` | Extra class on the root element. |
| `style?` | `CSSProperties` | Inline style on the root element. |

#### OtpInput

| Prop | Type | Notes |
| --- | --- | --- |
| `length?` | `number` |  |
| `onComplete?` | `(code: string) => void` |  |
| `error?` | `boolean` |  |
| `clearOnError?` | `boolean` | Empties the cells when `error` turns on, ready for the next try (default true). |
| `ref?` | `Ref<OtpInputHandle>` | `ref.current.reset()` empties the cells on demand. |
| `label?` | `string` |  |
| `className?` | `string` | Extra class on the root element. |
| `style?` | `CSSProperties` | Inline style on the root element. |

#### Slider

| Prop | Type | Notes |
| --- | --- | --- |
| `label?` | `string` |  |
| `min?` | `number` |  |
| `max?` | `number` |  |
| `step?` | `number` |  |
| `value?` | `number` |  |
| `defaultValue?` | `number` |  |
| `onChange?` | `(n: number) => void` |  |
| `format?` | `(n: number) => string` |  |
| `marks?` | `boolean` |  |
| `hint?` | `string` |  |
| `className?` | `string` | Extra class on the root element. |
| `style?` | `CSSProperties` | Inline style on the root element. |


## Order Summary

> Cart and checkout pieces: CartLine rows, the OrderSummary with discount code and free-shipping progress, and CheckoutSteps.

Component · Commerce · Halo kit · [Live page](https://ui.twentyfirst.media/halo/components/OrderSummary/)

Cart and checkout pieces: `CartLine` rows, the `OrderSummary` with discount code and free-shipping progress, and `CheckoutSteps`.

CartLine props: `name`, `variant`, `note`, `art` + `tint`, `price`, `qty`, `onQty(n)`, `onRemove` (the − button becomes a bin at 1).
OrderSummary props: `lines` ({name, variant, art, tint, price, qty}), `showLines`, `discount` ({code, pct | amount, label}), `onCoupon(code)` (return false to show "isn’t valid"; null removes), `shipping` (fixed) or `freeShippingFrom` (default 75, else €4.90), `vat` (19, prices include it), `title`, `action` (the CTA).
CheckoutSteps props: `steps` (Cart, Details, Shipping, Payment), `current`, `onPick` (go back only).

- Keep the summary in a sticky side column on desktop; it moves under the form on phones.
- Show what's left for free shipping; it is the strongest nudge in a cart.
- Removing a line shows an Undo toast instead of a confirm.

### Example

```tsx
import * as React from "react";
import { Button, CartLine, CheckoutSteps, OrderSummary } from "@twentyfirstmedia/halo";
import type { CartLineProps, Discount } from "@twentyfirstmedia/halo";

type OrderLine = Omit<CartLineProps, "onQty" | "onRemove"> & { key: string };

function App() {
  const lines = React.useState<OrderLine[]>([
      {
        key: "a",
        name: "Halo Cotton Tee",
        variant: "M · Sky",
        art: "tee",
        tint: "sky",
        price: 32,
        qty: 1,
      },
      {
        key: "b",
        name: "Studio Mug",
        art: "mug",
        tint: "butter",
        price: 18,
        qty: 2,
        note: "Only 6 left",
      },
    ]),
    d = React.useState<Discount | null>(null),
    step = React.useState(1);
  return (
    <div
      className="tf-col"
      style={{
        gap: 16,
      }}
    >
      <CheckoutSteps current={step[0]} onPick={step[1]} />
      <div
        className="tf-grid"
        style={
          {
            "--cols": "minmax(0, 1fr) 340px",
            gap: 16,
            alignItems: "start",
          } as React.CSSProperties
        }
      >
        <div className="tf-panel">
          {lines[0].map((l) => (
            <CartLine
              {...l}
              key={l.key}
              onQty={(n) => {
                lines[1](
                  lines[0].map((z) =>
                    z.key === l.key
                      ? Object.assign({}, z, {
                          qty: n,
                        })
                      : z,
                  ),
                );
              }}
              onRemove={() => {
                lines[1](lines[0].filter((z) => z.key !== l.key));
              }}
            />
          ))}
        </div>
        <div className="tf-panel">
          <OrderSummary
            lines={lines[0]}
            showLines
            discount={d[0]}
            freeShippingFrom={75}
            onCoupon={(c) => {
              if (c === null) return d[1](null);
              if (c !== "HALO10") return false;
              d[1]({
                code: "HALO10",
                pct: 10,
                label: "10% off everything",
              });
            }}
            action={<Button icon="lock">Pay now</Button>}
          />
        </div>
      </div>
    </div>
  );
}
export default App;
```

### Props

#### Button

| Prop | Type | Notes |
| --- | --- | --- |
| `variant?` | `"primary" \| "secondary" \| "soft" \| "ghost" \| "danger" \| "danger-solid"` |  |
| `size?` | `"md" \| "sm"` |  |
| `icon?` | `IconName` |  |
| `iconRight?` | `IconName` |  |
| `disabled?` | `boolean` |  |
| `type?` | `"button" \| "submit" \| "reset"` |  |
| `onClick?` | `(e: MouseEvent<HTMLButtonElement>) => void` |  |
| `children?` | `ReactNode` |  |
| `asChild?` | `boolean` | Render the single child element (a link, a router Link) with the button's look instead of a <button>. |
| `id?` | `string` |  |
| `name?` | `string` | Form field name and value, sent with the form when this button submits it. |
| `value?` | `string` |  |
| `form?` | `string` | The id of the form this button belongs to, when it sits outside it. |
| `title?` | `string` |  |
| `tabIndex?` | `number` |  |
| `autoFocus?` | `boolean` |  |
| `aria-label?` | `string` |  |
| `aria-labelledby?` | `string` |  |
| `aria-describedby?` | `string` |  |
| `aria-expanded?` | `boolean \| "true" \| "false"` | For disclosure and menu triggers: whether what the button controls is open. |
| `aria-controls?` | `string` |  |
| `aria-haspopup?` | `boolean \| "true" \| "false" \| "menu" \| "listbox" \| "tree" \| "grid" \| "dialog"` |  |
| `aria-pressed?` | `boolean \| "true" \| "false" \| "mixed"` | For toggle buttons. |
| `aria-current?` | `boolean \| "true" \| "false" \| "page" \| "step" \| "location" \| "date" \| "time"` |  |
| `className?` | `string` | Extra class on the root element. |
| `style?` | `CSSProperties` | Inline style on the root element. |

#### CartLine

| Prop | Type | Notes |
| --- | --- | --- |
| `name` | `string` | Required |
| `variant?` | `string` |  |
| `note?` | `string` |  |
| `art` | `ArtKind` | Required |
| `tint?` | `Tint` |  |
| `price` | `number` | Required |
| `qty` | `number` | Required |
| `onQty?` | `(n: number) => void` |  |
| `onRemove?` | `() => void` |  |
| `className?` | `string` | Extra class on the root element. |
| `style?` | `CSSProperties` | Inline style on the root element. |

#### CheckoutSteps

| Prop | Type | Notes |
| --- | --- | --- |
| `steps?` | `string[]` |  |
| `current?` | `number` |  |
| `onPick?` | `(i: number) => void` |  |
| `compact?` | `boolean` | Numbers only, with the label of the current step (screen readers still hear every label). Narrow containers (up to 560px) get this on their own. |
| `className?` | `string` | Extra class on the root element. |
| `style?` | `CSSProperties` | Inline style on the root element. |

#### OrderSummary

| Prop | Type | Notes |
| --- | --- | --- |
| `lines` | `{ name: string; variant?: string; art: ArtKind; tint?: Tint; price: number; qty: number; }[]` | Required |
| `showLines?` | `boolean` |  |
| `discount?` | `Discount \| null` |  |
| `onCoupon?` | `(code: string \| null) => boolean \| void` |  |
| `shipping?` | `number \| null` |  |
| `freeShippingFrom?` | `number` |  |
| `vat?` | `number` |  |
| `title?` | `string \| false` |  |
| `action?` | `ReactNode` |  |
| `className?` | `string` | Extra class on the root element. |
| `style?` | `CSSProperties` | Inline style on the root element. |


## Order Timeline

> Five-step fulfilment progress for an order: Placed, Paid, Packed, Shipped, Delivered.

Component · Commerce · Halo kit · [Live page](https://ui.twentyfirst.media/halo/components/OrderTimeline/)

Five-step fulfilment progress for an order: Placed, Paid, Packed, Shipped, Delivered.

Props: `status` (one of the five, or "Refunded" / "Cancelled" which dims the line and shows a badge), `times` ({step: text}).

- Use the same five words as the order status badges, so list and detail agree.
- The current step gets a sky ring and a clock until it's done.

### Example

```tsx
import { OrderTimeline } from "@twentyfirstmedia/halo";

export default function Preview() {
  return (
    <div
      className="tf-panel"
      style={{
        gap: 32,
      }}
    >
      <OrderTimeline
        status="Shipped"
        times={{
          Placed: "Apr 12, 09:14",
          Paid: "Apr 12, 09:15",
          Packed: "Apr 12, 15:40",
          Shipped: "Apr 13, 08:02",
        }}
      />
      <OrderTimeline
        status="Paid"
        times={{
          Placed: "Just now",
          Paid: "Just now",
        }}
      />
      <OrderTimeline status="Refunded" />
    </div>
  );
}
```

### Props

#### OrderTimeline

| Prop | Type | Notes |
| --- | --- | --- |
| `status` | `"Placed" \| "Paid" \| "Packed" \| "Shipped" \| "Delivered" \| "Refunded" \| "Cancelled"` | Required |
| `times?` | `Record<string, string>` |  |
| `className?` | `string` | Extra class on the root element. |
| `style?` | `CSSProperties` | Inline style on the root element. |


## Org Chart

> The hierarchy as a chart: orchestrator, leads per team, executing agents and people.

Component · AI · Halo kit · [Live page](https://ui.twentyfirst.media/halo/components/OrgChart/)

The hierarchy as a chart: orchestrator, leads per team, executing agents and people.

Props: `root` ({name, role, tint, status, avatar, children}). Scrolls sideways when wide.

### Example

```tsx
import { OrgChart } from "@twentyfirstmedia/halo";

export default function Preview() {
  return (
    <div className="tf-panel">
      <OrgChart
        root={{
          name: "Main Brain",
          role: "Orchestrator",
          tint: "lilac",
          status: "ok",
          children: [
            {
              name: "Atlas",
              role: "Support lead",
              tint: "sky",
              status: "running",
              children: [
                {
                  name: "Triage",
                  role: "Tags mail",
                  tint: "sky",
                  status: "idle",
                },
                {
                  name: "Drafts",
                  role: "Writes replies",
                  tint: "sky",
                  status: "signal",
                },
              ],
            },
            {
              name: "Ledger",
              role: "Finance lead",
              tint: "butter",
              status: "ok",
            },
            {
              name: "Robin",
              role: "Owner",
              avatar: true,
            },
          ],
        }}
      />
    </div>
  );
}
```

### Props

#### OrgChart

| Prop | Type | Notes |
| --- | --- | --- |
| `root` | `OrgNode` | Required |
| `className?` | `string` | Extra class on the root element. |
| `style?` | `CSSProperties` | Inline style on the root element. |


## Panel

> Data in Twentyfirst UI.

Component · Data · Halo kit · [Live page](https://ui.twentyfirst.media/halo/components/Panel/)

### Example

```tsx
import { EventCard, IconButton, Panel, Tabs } from "@twentyfirstmedia/halo";

export default function Preview() {
  return (
    <div
      style={{
        maxWidth: 340,
        background: "var(--canvas)",
        padding: 12,
        borderRadius: "var(--radius-lg)",
      }}
    >
      <Panel
        title="Schedule"
        subtitle="5 items waiting · 2 today"
        action={<IconButton icon="plus" label="Add" />}
      >
        <Tabs block items={["Events", "Approvals", "History"]} />
        <EventCard kind="review" label="Design review" date="Wed, Apr 15" time="14:00">
          Walk through the new billing settings flow.
        </EventCard>
      </Panel>
    </div>
  );
}
```

### Props

#### EventCard

| Prop | Type | Notes |
| --- | --- | --- |
| `kind?` | `"meeting" \| "deadline" \| "review" \| "launch" \| "incident"` |  |
| `label` | `string` | Required |
| `date` | `string` | Required |
| `time` | `string` | Required |
| `tint?` | `Tint` |  |
| `icon?` | `IconName` |  |
| `actions?` | `boolean` |  |
| `children?` | `ReactNode` |  |
| `className?` | `string` | Extra class on the root element. |
| `style?` | `CSSProperties` | Inline style on the root element. |

#### IconButton

| Prop | Type | Notes |
| --- | --- | --- |
| `icon` | `IconName` | Required |
| `label` | `string` | Accessible name and tooltip (`aria-label` and `title`); `aria-label` or `title` override them. |
| `variant?` | `"soft" \| "solid" \| "outline" \| "ghost"` |  |
| `size?` | `"sm" \| "md" \| "lg"` |  |
| `type?` | `"button" \| "submit" \| "reset"` |  |
| `onClick?` | `(e: MouseEvent<HTMLButtonElement>) => void` |  |
| `disabled?` | `boolean` |  |
| `asChild?` | `boolean` | Render the single child element (a link) with the button's look; the icon is placed inside it. |
| `children?` | `ReactNode` |  |
| `id?` | `string` |  |
| `name?` | `string` | Form field name and value, sent with the form when this button submits it. |
| `value?` | `string` |  |
| `form?` | `string` | The id of the form this button belongs to, when it sits outside it. |
| `title?` | `string` |  |
| `tabIndex?` | `number` |  |
| `autoFocus?` | `boolean` |  |
| `aria-label?` | `string` |  |
| `aria-labelledby?` | `string` |  |
| `aria-describedby?` | `string` |  |
| `aria-expanded?` | `boolean \| "true" \| "false"` | For disclosure and menu triggers: whether what the button controls is open. |
| `aria-controls?` | `string` |  |
| `aria-haspopup?` | `boolean \| "true" \| "false" \| "menu" \| "listbox" \| "tree" \| "grid" \| "dialog"` |  |
| `aria-pressed?` | `boolean \| "true" \| "false" \| "mixed"` | For toggle buttons. |
| `aria-current?` | `boolean \| "true" \| "false" \| "page" \| "step" \| "location" \| "date" \| "time"` |  |
| `className?` | `string` | Extra class on the root element. |
| `style?` | `CSSProperties` | Inline style on the root element. |

#### Panel

| Prop | Type | Notes |
| --- | --- | --- |
| `side?` | `boolean` |  |
| `title?` | `string` |  |
| `subtitle?` | `string` |  |
| `action?` | `ReactNode` |  |
| `children?` | `ReactNode` |  |
| `surface?` | `Surface` | `"glass"`: translucent glass over what is behind (maps, 3D, video, photos); `"solid"` opts out inside a glass `UIProvider`. |
| `className?` | `string` | Extra class on the root element. |
| `style?` | `CSSProperties` | Inline style on the root element. |

#### Tabs

| Prop | Type | Notes |
| --- | --- | --- |
| `items` | `string[]` | Required |
| `value?` | `string` |  |
| `defaultValue?` | `string` |  |
| `onChange?` | `(v: string) => void` |  |
| `block?` | `boolean` |  |
| `panels?` | `Record<string, ReactNode>` | Content per tab; renders the tab panels under the bar, wired with tab/tabpanel roles. |
| `label?` | `string` | Accessible name of the tab list. |
| `className?` | `string` | Extra class on the root element. |
| `style?` | `CSSProperties` | Inline style on the root element. |


## Plan Card

> Pricing tier for plan pages and upgrade dialogs.

Component · Commerce · Halo kit · [Live page](https://ui.twentyfirst.media/halo/components/PlanCard/)

Pricing tier for plan pages and upgrade dialogs. Wrap several in `.tf-plans` for an even grid.

Props: `name`, `text`, `price` (number, 0 = "Free", null = "Let’s talk"), `was` (struck price, e.g. monthly vs yearly), `per`, `features` (strings; prefix "-" for not included), `featured` (dark card + flag), `flag`, `current` (disables the button), `disabled` (disables the button, e.g. while a checkout starts or when the plan is not available), `cta`, `onPick`.

- One featured plan, the one most customers should pick. It inverts to the frame color.
- List the same features in the same order on every card, so rows can be compared; mark missing ones instead of leaving them out.
- Pair with a Segmented Monthly / Yearly switch that states the saving.

### Example

```tsx
import { PlanCard } from "@twentyfirstmedia/halo";

export default function Preview() {
  return (
    <div className="tf-plans">
      <PlanCard
        name="Starter"
        price={9}
        was={12}
        per="per seat / month, billed yearly"
        text="For small teams getting organised"
        features={[
          "3 projects",
          "1 agent · Haiku only",
          "Shop with up to 50 products",
          "-Approvals and audit log",
          "-SSO",
        ]}
      />
      <PlanCard
        name="Team"
        price={24}
        was={29}
        per="per seat / month, billed yearly"
        text="Everything a growing company runs on"
        featured
        features={[
          "Unlimited projects",
          "10 agents · all models",
          "Unlimited products, 3 channels",
          "Approvals and audit log",
          "-SSO",
        ]}
      />
      <PlanCard
        name="Business"
        price={null}
        text="Security, control and an SLA"
        cta="Talk to sales"
        current={false}
        features={["Everything in Team", "SSO and SCIM", "EU data residency", "99.9% uptime SLA"]}
      />
    </div>
  );
}
```

### Props

#### PlanCard

| Prop | Type | Notes |
| --- | --- | --- |
| `name` | `string` | Required |
| `text?` | `string` |  |
| `price` | `number \| null \| ReactNode` | A number is formatted as money (0 = "Free", null = "Let's talk"); any other node is shown as it is, e.g. a placeholder ("—") or a price the app formatted itself. |
| `pricePrefix?` | `ReactNode` | Before the price, e.g. "from". |
| `priceNote?` | `ReactNode` | Under the price: net or gross, billed yearly, VAT note … |
| `was?` | `number` |  |
| `per?` | `string` |  |
| `features?` | `string[]` |  |
| `featured?` | `boolean` |  |
| `flag?` | `string` |  |
| `current?` | `boolean` |  |
| `cta?` | `string` |  |
| `disabled?` | `boolean` | Disable the button, e.g. while a checkout starts or when the plan cannot be picked. |
| `onPick?` | `() => void` |  |
| `href?` | `string` | The action as a link (checkout or sign-up page), with `linkAs` for a router's link. |
| `linkAs?` | `ElementType` |  |
| `className?` | `string` | Extra class on the root element. |
| `style?` | `CSSProperties` | Inline style on the root element. |


## Product Card

> Product tile for catalogs and grids, plus the pieces it is made of: Price, Rating, StockBadge and ProductArt.

Component · Commerce · Halo kit · [Live page](https://ui.twentyfirst.media/halo/components/ProductCard/)

Product tile for catalogs and grids, plus the pieces it is made of: `Price`, `Rating`, `StockBadge` and `ProductArt`.

ProductCard props: `name`, `meta`, `art` + `tint` (or swap in your own image inside `.tf-product-media`), `price`, `compareAt`, `rating`, `reviews`, `badge` + `badgeTone`, `stock`, `wished` + `onWish`, `added` + `onAdd`, `onClick`.
Price: `value`, `compareAt` (shows the struck price and −%), `size` ("lg"), `currency`, `showSave`. Rating: `value`, `count`, `size`. StockBadge: `stock`, `low` (10), `compact`. ProductArt: `kind` (tee, mug, bottle, cap, tote, sneaker, watch, lamp), `tint`, `size`.

- One badge per card at most (Bestseller, New, Sold out). Sale is shown by the price, not a badge.
- Quick-add only for products without variants; otherwise open the product page.
- Low stock is a warning badge with the number left; out of stock disables add.

### Example

```tsx
import * as React from "react";
import { Price, ProductArt, ProductCard, Rating, StockBadge } from "@twentyfirstmedia/halo";
import type { ProductCardProps } from "@twentyfirstmedia/halo";

function App() {
  const w = React.useState<string[]>(["p2"]),
    a = React.useState<string[]>([]);
  const P: (ProductCardProps & { id: string })[] = [
    {
      id: "p1",
      name: "Halo Cotton Tee",
      meta: "Apparel",
      art: "tee",
      tint: "sky",
      price: 32,
      compareAt: 39,
      rating: 4.7,
      reviews: 128,
      badge: "Bestseller",
    },
    {
      id: "p2",
      name: "Studio Mug",
      meta: "Home",
      art: "mug",
      tint: "butter",
      price: 18,
      rating: 4.9,
      reviews: 96,
    },
    {
      id: "p3",
      name: "Field Bottle",
      meta: "Outdoor",
      art: "bottle",
      tint: "mint",
      price: 28,
      rating: 4.6,
      reviews: 61,
      badge: "New",
    },
    {
      id: "p4",
      name: "Canvas Tote",
      meta: "Bags",
      art: "tote",
      tint: "lilac",
      price: 24,
      rating: 4.8,
      reviews: 143,
      stock: 0,
      badge: "Sold out",
      badgeTone: "neutral",
    },
  ];
  return (
    <div
      className="tf-grid"
      style={
        {
          "--cols": "repeat(4, minmax(0, 1fr))",
          "--cols-sm": "repeat(2, minmax(0, 1fr))",
          "--cols-md": "repeat(2, minmax(0, 1fr))",
          gap: 16,
        } as React.CSSProperties
      }
    >
      {P.map((x) => (
        <ProductCard
          key={x.id}
          {...x}
          wished={w[0].indexOf(x.id) > -1}
          added={a[0].indexOf(x.id) > -1}
          onWish={() => {
            w[1](w[0].indexOf(x.id) > -1 ? w[0].filter((i) => i !== x.id) : w[0].concat([x.id]));
          }}
          onAdd={() => {
            a[1](a[0].concat([x.id]));
          }}
        />
      ))}
      <div
        className="tf-panel"
        style={{
          gridColumn: "1 / -1",
          flexDirection: "row",
          flexWrap: "wrap",
          gap: 24,
          alignItems: "center",
        }}
      >
        <Price value={32} compareAt={39} size="lg" />
        <Rating value={4.6} count={61} />
        <StockBadge stock={84} />
        <StockBadge stock={6} />
        <StockBadge stock={0} />
        <div
          style={{
            display: "flex",
            flexWrap: "wrap",
            gap: 8,
          }}
        >
          {ProductArt.kinds.map((k, i) => (
            <ProductArt
              key={k}
              kind={k}
              tint={(["sky", "mint", "butter", "lilac", "blush"] as const)[i % 5]}
              size={40}
            />
          ))}
        </div>
      </div>
    </div>
  );
}
export default App;
```

### Props

#### Price

| Prop | Type | Notes |
| --- | --- | --- |
| `value` | `number` | Required |
| `compareAt?` | `number` |  |
| `currency?` | `string` |  |
| `size?` | `"lg"` |  |
| `showSave?` | `boolean` |  |
| `className?` | `string` | Extra class on the root element. |
| `style?` | `CSSProperties` | Inline style on the root element. |

#### ProductArt

| Prop | Type | Notes |
| --- | --- | --- |
| `kind` | `ArtKind` | Required |
| `tint?` | `Tint \| "plain"` |  |
| `size?` | `number` |  |
| `label?` | `string` |  |
| `className?` | `string` | Extra class on the root element. |
| `style?` | `CSSProperties` | Inline style on the root element. |

#### ProductCard

| Prop | Type | Notes |
| --- | --- | --- |
| `name` | `string` | Required |
| `meta?` | `string` |  |
| `art` | `ArtKind` | Required |
| `tint?` | `Tint` |  |
| `price` | `number` | Required |
| `compareAt?` | `number` |  |
| `rating?` | `number` |  |
| `reviews?` | `number` |  |
| `badge?` | `string` |  |
| `badgeTone?` | `Tone` |  |
| `stock?` | `number` |  |
| `wished?` | `boolean` |  |
| `onWish?` | `() => void` |  |
| `added?` | `boolean` |  |
| `onAdd?` | `() => void` |  |
| `onClick?` | `() => void` |  |
| `className?` | `string` | Extra class on the root element. |
| `style?` | `CSSProperties` | Inline style on the root element. |

#### Rating

| Prop | Type | Notes |
| --- | --- | --- |
| `value` | `number` | Required |
| `count?` | `number` |  |
| `size?` | `number` |  |
| `className?` | `string` | Extra class on the root element. |
| `style?` | `CSSProperties` | Inline style on the root element. |

#### StockBadge

| Prop | Type | Notes |
| --- | --- | --- |
| `stock` | `number` | Required |
| `low?` | `number` |  |
| `compact?` | `boolean` |  |
| `className?` | `string` | Extra class on the root element. |
| `style?` | `CSSProperties` | Inline style on the root element. |


## Radio Group

> One choice out of a few, always visible.

Component · Forms · Halo kit · [Live page](https://ui.twentyfirst.media/halo/components/RadioGroup/)

One choice out of a few, always visible. `RadioGroup` for 2–5 options with labels and hints, `Segmented` for 2–4 short options that switch a value inline.

RadioGroup props: `label`, `options` (strings or {value, label, hint, disabled}), `value`/`defaultValue`, `onChange(value)`, `cards` (bordered tiles in a grid), `hint`.
Segmented props: `options` (strings or {value, label, icon}), `value`/`defaultValue`, `onChange(value)`, `size` ("sm"), `block`, `label` (accessible name).

- Six or more options, or options that need search: use Combobox.
- Segmented sets a value (billing period, density); Tabs switch views of content. Don't mix them up.
- `cards` when each option needs a sentence to explain it (plans, themes).

### Example

```tsx
import * as React from "react";
import { RadioGroup, Segmented } from "@twentyfirstmedia/halo";

function App() {
  const a = React.useState("Team"),
    b = React.useState("Monthly");
  return (
    <div
      className="tf-panel"
      style={{
        gap: 24,
      }}
    >
      <RadioGroup
        label="Plan"
        cards
        value={a[0]}
        onChange={a[1]}
        options={[
          {
            value: "Starter",
            label: "Starter",
            hint: "€9 per seat · 3 projects",
          },
          {
            value: "Team",
            label: "Team",
            hint: "€24 per seat · unlimited",
          },
          {
            value: "Business",
            label: "Business",
            hint: "SSO, audit log, SLA",
          },
        ]}
      />
      <div
        style={{
          display: "flex",
          gap: 48,
          flexWrap: "wrap",
          alignItems: "flex-start",
        }}
      >
        <RadioGroup
          label="Invoice reminders"
          defaultValue="due"
          options={[
            {
              value: "never",
              label: "Never",
            },
            {
              value: "due",
              label: "On the due date",
            },
            {
              value: "weekly",
              label: "Weekly until paid",
              hint: "Stops when the bank feed matches it",
            },
          ]}
        />
        <div className="tf-field">
          <span className="tf-field-label">Billing</span>
          <Segmented label="Billing" value={b[0]} onChange={b[1]} options={["Monthly", "Yearly"]} />
        </div>
        <div className="tf-field">
          <span className="tf-field-label">View</span>
          <Segmented
            label="View"
            size="sm"
            defaultValue="grid"
            options={[
              {
                value: "grid",
                label: "Grid",
                icon: "grid",
              },
              {
                value: "list",
                label: "List",
                icon: "menu",
              },
            ]}
          />
        </div>
      </div>
    </div>
  );
}
export default App;
```

### Props

#### RadioGroup

| Prop | Type | Notes |
| --- | --- | --- |
| `label?` | `string` |  |
| `options` | `(string \| Option)[]` | Required |
| `value?` | `string` |  |
| `defaultValue?` | `string` |  |
| `onChange?` | `(v: string) => void` |  |
| `cards?` | `boolean` |  |
| `hint?` | `string` |  |
| `className?` | `string` | Extra class on the root element. |
| `style?` | `CSSProperties` | Inline style on the root element. |

#### Segmented

| Prop | Type | Notes |
| --- | --- | --- |
| `options` | `(string \| Option)[]` | Required |
| `value?` | `string` |  |
| `defaultValue?` | `string` |  |
| `onChange?` | `(v: string) => void` |  |
| `size?` | `"sm"` |  |
| `block?` | `boolean` |  |
| `label?` | `string` |  |
| `className?` | `string` | Extra class on the root element. |
| `style?` | `CSSProperties` | Inline style on the root element. |


## Range Slider

> Form pieces added for search filters and admin settings: RangeSlider (two thumbs), StatusSelect (a status pill that opens a list), TilePicker (pick one or many visual options) and ColorField (hex input with contrast check).

Component · Forms · Halo kit · [Live page](https://ui.twentyfirst.media/halo/components/RangeSlider/)

Form pieces added for search filters and admin settings: `RangeSlider` (two thumbs), `StatusSelect` (a status pill that opens a list), `TilePicker` (pick one or many visual options) and `ColorField` (hex input with contrast check).

RangeSlider: `label`, `min`, `max`, `step`, `value` / `defaultValue` ([low, high]) + `onChange`, `unit`, `inputs` (false shows values instead of fields), `openEnd` (adds "+" at max), `format`.
StatusSelect: `options` ({value, label, status}), `value` / `onChange`, `size` ("sm"), `label`.
TilePicker: `options` ({value, label, meta, image | icon | art, tint, color, disabled}), `value` / `onChange`, `multiple`, `min` (tile width), `label`.
ColorField: `label`, `value` / `onChange`, `against` (colour to check contrast with; false hides it), `hint`.

### Example

```tsx
import * as React from "react";
import { ColorField, RangeSlider, StatusSelect, TilePicker } from "@twentyfirstmedia/halo";

function App() {
  const r = React.useState<[number, number]>([300000, 650000]),
    t = React.useState<string | string[]>("scandi"),
    s = React.useState("read");
  return (
    <div
      className="tf-grid"
      style={
        {
          "--cols": "1fr 1fr",
          gap: 16,
          alignItems: "start",
        } as React.CSSProperties
      }
    >
      <div
        className="tf-panel"
        style={{
          gap: 20,
        }}
      >
        <RangeSlider
          label="Price"
          min={0}
          max={1500000}
          step={10000}
          value={r[0]}
          onChange={r[1]}
          unit="€"
        />
        <RangeSlider
          label="Living area"
          min={20}
          max={300}
          defaultValue={[60, 140]}
          inputs={false}
          openEnd
          format={(v) => v + " m²"}
        />
        <div className="tf-row">
          <StatusSelect
            value={s[0]}
            onChange={s[1]}
            label="Status"
            options={[
              {
                value: "unread",
                label: "Unread",
                status: "running",
              },
              {
                value: "read",
                label: "Read",
                status: "idle",
              },
              {
                value: "contacted",
                label: "Contacted",
                status: "ok",
              },
              {
                value: "rejected",
                label: "Not a fit",
                status: "danger",
              },
            ]}
          />
          <ColorField value="#2f6fe0" against="#ffffff" />
        </div>
      </div>
      <div
        className="tf-panel"
        style={{
          gap: 12,
        }}
      >
        <b>Room style</b>
        <TilePicker
          value={t[0]}
          onChange={(v) => t[1](v ?? "")}
          label="Room style"
          min={120}
          options={[
            {
              value: "scandi",
              label: "Scandinavian",
              tint: "sky",
              icon: "home",
            },
            {
              value: "modern",
              label: "Modern",
              tint: "mint",
              icon: "grid",
            },
            {
              value: "industrial",
              label: "Industrial",
              tint: "butter",
              icon: "layers",
            },
            {
              value: "classic",
              label: "Classic",
              tint: "blush",
              icon: "star",
              meta: "Pro",
            },
            {
              value: "japandi",
              label: "Japandi",
              tint: "lilac",
              icon: "sun",
            },
            {
              value: "boho",
              label: "Boho",
              disabled: true,
              icon: "sparkle",
              meta: "Soon",
            },
          ]}
        />
      </div>
    </div>
  );
}
export default App;
```

### Props

#### ColorField

| Prop | Type | Notes |
| --- | --- | --- |
| `label?` | `ReactNode` |  |
| `value?` | `string` |  |
| `defaultValue?` | `string` |  |
| `onChange?` | `(v: string) => void` |  |
| `against?` | `string \| false` |  |
| `hint?` | `ReactNode` |  |
| `className?` | `string` | Extra class on the root element. |
| `style?` | `CSSProperties` | Inline style on the root element. |

#### RangeSlider

| Prop | Type | Notes |
| --- | --- | --- |
| `label?` | `ReactNode` |  |
| `min?` | `number` |  |
| `max?` | `number` |  |
| `step?` | `number` |  |
| `value?` | `[number, number]` |  |
| `defaultValue?` | `[number, number]` |  |
| `onChange?` | `(v: [number, number]) => void` |  |
| `unit?` | `string` |  |
| `inputs?` | `boolean` |  |
| `openEnd?` | `boolean` |  |
| `format?` | `(v: number) => string` |  |
| `hint?` | `ReactNode` |  |
| `className?` | `string` | Extra class on the root element. |
| `style?` | `CSSProperties` | Inline style on the root element. |

#### StatusSelect

| Prop | Type | Notes |
| --- | --- | --- |
| `options` | `{ value: string; label: string; status?: Status }[]` | Required |
| `value?` | `string` |  |
| `defaultValue?` | `string` |  |
| `onChange?` | `(v: string) => void` |  |
| `size?` | `"sm"` |  |
| `label?` | `string` |  |
| `width?` | `number` |  |
| `className?` | `string` | Extra class on the root element. |
| `style?` | `CSSProperties` | Inline style on the root element. |

#### TilePicker

| Prop | Type | Notes |
| --- | --- | --- |
| `options` | `{ value: string; label: ReactNode; meta?: ReactNode; image?: string; icon?: IconName; art?: ReactNode; tint?: Tint; color?: string; disabled?: boolean; }[]` | Required |
| `value?` | `string \| string[]` |  |
| `defaultValue?` | `string \| string[]` |  |
| `onChange?` | `(v: string \| string[] \| null) => void` |  |
| `multiple?` | `boolean` |  |
| `min?` | `number` |  |
| `label?` | `string` |  |
| `layout?` | `"grid" \| "list"` | `list`: one compact row per option (small picture or icon beside the label), e.g. on phones. |
| `className?` | `string` | Extra class on the root element. |
| `style?` | `CSSProperties` | Inline style on the root element. |


## Review Card

> Moderating customer reviews before and after they go live.

Component · Commerce · Halo kit · [Live page](https://ui.twentyfirst.media/halo/components/ReviewCard/)

Moderating customer reviews before and after they go live.

Props: `author`, `verified`, `product`, `date`, `rating`, `title`, `text`, `state` ("pending" | "published" | "hidden" | "flagged"), `stateLabel`, `highlight` (words to mark, e.g. refund, scam), `reply`, `onPublish`, `onHide`, `onReply(text)`, `replyLabel`.

- Pending reviews carry the signal edge until someone decides.
- Hiding is reversible; deleting a review is not offered here.

### Example

```tsx
import * as React from "react";
import { ReviewCard } from "@twentyfirstmedia/halo";

export default function Preview() {
  return (
    <div
      className="tf-grid"
      style={
        {
          "--cols": "1fr 1fr",
          gap: 16,
          alignItems: "start",
        } as React.CSSProperties
      }
    >
      <ReviewCard
        author="Jonas P."
        verified
        product="1,000 followers"
        date="2 days ago"
        rating={2}
        state="pending"
        title="Slower than promised"
        text="Arrived after two days instead of one hour. Support answered quickly though, so two stars. Would be great to get a refund for the delay."
        highlight={["refund"]}
        onPublish={() => {}}
        onHide={() => {}}
        onReply={() => {}}
      />
      <ReviewCard
        author="Ida N."
        product="TikTok views"
        date="Apr 12"
        rating={5}
        state="published"
        text="Fast, simple, worked exactly as described."
        reply="Thanks Ida, glad it worked!"
        onHide={() => {}}
        onReply={() => {}}
      />
    </div>
  );
}
```

### Props

#### ReviewCard

| Prop | Type | Notes |
| --- | --- | --- |
| `author` | `string` | Required |
| `verified?` | `boolean` |  |
| `product?` | `string` |  |
| `date?` | `string` |  |
| `rating` | `number` | Required |
| `title?` | `string` |  |
| `text` | `string` | Required |
| `state?` | `"pending" \| "published" \| "hidden" \| "flagged"` |  |
| `stateLabel?` | `string` |  |
| `highlight?` | `string[]` |  |
| `reply?` | `string` |  |
| `replyLabel?` | `string` |  |
| `onPublish?` | `() => void` |  |
| `onHide?` | `() => void` |  |
| `onReply?` | `(text: string) => void` |  |
| `className?` | `string` | Extra class on the root element. |
| `style?` | `CSSProperties` | Inline style on the root element. |


## Rich Text Editor

> Formatted text for newsletters, product descriptions, legal pages and canned replies: toolbar, placeholder fields and a character count.

Component · Forms · Halo kit · [Live page](https://ui.twentyfirst.media/halo/components/RichTextEditor/)

Formatted text for newsletters, product descriptions, legal pages and canned replies: toolbar, placeholder fields and a character count.

Props: `label`, `defaultValue` (HTML), `onChange(html)`, `placeholder`, `variables` ({key, label}: inserted as `{key}`), `maxLength`, `minHeight`, `footer`, `hint`, `error`, `disabled`.

- The toolbar keeps to bold, italic, underline, heading, quote, lists, link, undo/redo. Anything richer belongs in a dedicated editor.
- Built on Selection/Range, no `execCommand`. Shortcuts: ⌘/Ctrl B, I, U, K (link), Z and ⇧Z (undo, redo).
- Links open a small field instead of a browser prompt; addresses without a scheme get https://.
- Pasting inserts plain text; `onChange` returns HTML limited to p, h3, blockquote, ul, ol, li, b, i, u, a and br.
- Still sanitize on the server before you send or store it.

### Example

```tsx
import { RichTextEditor } from "@twentyfirstmedia/halo";

export default function Preview() {
  return (
    <div className="tf-panel">
      <RichTextEditor
        label="Newsletter text"
        placeholder="Write something…"
        maxLength={2000}
        defaultValue="<h3>Your boost is live</h3><p>Hi {first_name}, your <b>1,000 followers</b> start arriving within the next hour.</p><ul><li>Delivery spreads over 24 h</li><li>Refill guarantee for 30 days</li></ul>"
        variables={[
          {
            key: "first_name",
            label: "First name",
          },
          {
            key: "order_id",
            label: "Order number",
          },
          {
            key: "coupon",
            label: "Coupon code",
          },
        ]}
        hint="Fields in braces are filled per recipient."
      />
    </div>
  );
}
```

### Props

#### RichTextEditor

| Prop | Type | Notes |
| --- | --- | --- |
| `label?` | `ReactNode` |  |
| `defaultValue?` | `string` |  |
| `value?` | `string` |  |
| `onChange?` | `(html: string) => void` |  |
| `placeholder?` | `string` |  |
| `variables?` | `{ key: string; label: string }[]` |  |
| `maxLength?` | `number` |  |
| `minHeight?` | `number` |  |
| `footer?` | `ReactNode` |  |
| `hint?` | `ReactNode` |  |
| `error?` | `ReactNode` |  |
| `disabled?` | `boolean` |  |
| `className?` | `string` | Extra class on the root element. |
| `style?` | `CSSProperties` | Inline style on the root element. |


## Run History

> Background work: RunHistory (scraping jobs, cron, imports) and WebhookEndpoint (an outgoing or incoming hook with its deliveries).

Component · Admin · Halo kit · [Live page](https://ui.twentyfirst.media/halo/components/RunHistory/)

Background work: `RunHistory` (scraping jobs, cron, imports) and `WebhookEndpoint` (an outgoing or incoming hook with its deliveries).

RunHistory: `items` ({id, name, status, started, duration, by, counts: {value, label, tone}, detail (node; makes the row expandable)}), `label`.
WebhookEndpoint: `url`, `events`, `status` + `statusLabel`, `successRate`, `enabled` + `onToggle`, `secret` (node, e.g. SecretField), `deliveries` ({id, code, event, time, ms}), `onRetry(delivery)`, `menu`, `defaultOpen`.

### Example

```tsx
import { LogView, RunHistory, WebhookEndpoint } from "@twentyfirstmedia/halo";

export default function Preview() {
  return (
    <div
      className="tf-col"
      style={{
        gap: 16,
      }}
    >
      <div className="tf-panel tf-panel-flush tf-panel-list">
        <RunHistory
          items={[
            {
              id: 1,
              name: "ImmoScout · Hamburg",
              status: "ok",
              started: "Today 06:00",
              duration: "4 m 12 s",
              counts: [
                {
                  value: 1284,
                  label: "checked",
                },
                {
                  value: 37,
                  label: "new",
                  tone: "success",
                },
              ],
            },
            {
              id: 2,
              name: "Kleinanzeigen · Hamburg",
              status: "warn",
              started: "Today 06:00",
              duration: "7 m 40 s",
              counts: [
                {
                  value: 922,
                  label: "checked",
                },
                {
                  value: 12,
                  label: "new",
                  tone: "success",
                },
                {
                  value: 18,
                  label: "failed",
                  tone: "danger",
                },
              ],
              detail: (
                <LogView
                  title="errors"
                  lines={[
                    {
                      time: "06:03:11",
                      text: "HTTP 429 on page 14, waited 30 s",
                      level: "warn",
                    },
                    {
                      time: "06:05:40",
                      text: "18 detail pages without price, skipped",
                      level: "warn",
                    },
                  ]}
                />
              ),
            },
            {
              id: 3,
              name: "Daily cleanup",
              status: "danger",
              started: "Yesterday 03:00",
              duration: "12 s",
              by: "cron",
              counts: [
                {
                  value: 1,
                  label: "error",
                  tone: "danger",
                },
              ],
              detail: "Database connection refused.",
            },
          ]}
        />
      </div>
      <WebhookEndpoint
        url="https://api.homefield.com/hooks/stripe"
        events={["checkout.session.completed", "invoice.paid", "customer.subscription.deleted"]}
        status="ok"
        statusLabel="Active"
        successRate={98.7}
        onToggle={() => {}}
        onRetry={() => {}}
        defaultOpen
        menu={[
          {
            label: "Send test event",
            icon: "send",
          },
          {
            label: "Rotate secret",
            icon: "key",
          },
          "-",
          {
            label: "Delete",
            icon: "trash",
            danger: true,
          },
        ]}
        deliveries={[
          {
            id: 1,
            code: 200,
            event: "invoice.paid",
            time: "09:41",
            ms: 182,
          },
          {
            id: 2,
            code: 500,
            event: "checkout.session.completed",
            time: "09:12",
            ms: 3012,
          },
          {
            id: 3,
            code: 200,
            event: "customer.subscription.deleted",
            time: "Yesterday",
            ms: 240,
          },
        ]}
      />
    </div>
  );
}
```

### Props

#### LogView

| Prop | Type | Notes |
| --- | --- | --- |
| `lines` | `LogLine[]` | Required |
| `title?` | `ReactNode` |  |
| `right?` | `ReactNode` |  |
| `numbers?` | `boolean` |  |
| `follow?` | `boolean` |  |
| `maxHeight?` | `number` |  |
| `className?` | `string` | Extra class on the root element. |
| `style?` | `CSSProperties` | Inline style on the root element. |

#### RunHistory

| Prop | Type | Notes |
| --- | --- | --- |
| `items` | `{ id: string \| number; name: string; status: Status; started?: string; duration?: string; by?: string; counts?: { value: number; label: string; tone?: Tone }[]; detail?: ReactNode; }[]` | Required |
| `label?` | `string` |  |
| `className?` | `string` | Extra class on the root element. |
| `style?` | `CSSProperties` | Inline style on the root element. |

#### WebhookEndpoint

| Prop | Type | Notes |
| --- | --- | --- |
| `url` | `string` | Required |
| `events?` | `string[]` |  |
| `status?` | `Status` |  |
| `statusLabel?` | `string` |  |
| `successRate?` | `number` |  |
| `enabled?` | `boolean` |  |
| `onToggle?` | `() => void` |  |
| `secret?` | `ReactNode` |  |
| `deliveries?` | `{ id: string \| number; code?: number; event: string; time?: string; ms?: number }[]` |  |
| `onRetry?` | `(d: NonNullable<WebhookEndpointProps["deliveries"]>[number]) => void` |  |
| `menu?` | `MenuProps["items"]` |  |
| `defaultOpen?` | `boolean` |  |
| `className?` | `string` | Extra class on the root element. |
| `style?` | `CSSProperties` | Inline style on the root element. |


## Run Trace

> Waterfall of one agent run: every model call, tool call, search and approval, with timing bars and expandable details.

Component · AI · Halo kit · [Live page](https://ui.twentyfirst.media/halo/components/RunTrace/)

Waterfall of one agent run: every model call, tool call, search and approval, with timing bars and expandable details.

Props: `steps` ({kind: "model" | "tool" | "search" | "memory" | "approval" | "message" | "error", label, meta, start (ms), ms, detail (string or node), status ("done" | "running" | "error")}), `defaultOpen` (index), `footer`.

- The bar shows when a step ran inside the whole run, so slow tools are obvious at a glance.
- Errors are blush; a running step pulses. Put model, tokens and cost in the footer.
- Use it in run history and when an approval asks "why does the agent want this?".

### Example

```tsx
import { RunTrace } from "@twentyfirstmedia/halo";
import type { TraceStep } from "@twentyfirstmedia/halo";

const steps: TraceStep[] = [
  {
    kind: "message",
    label: "Task received",
    meta: "Triage 12 new support emails",
    start: 0,
    ms: 30,
    detail: "Trigger: schedule · every hour",
  },
  {
    kind: "model",
    label: "Planned the work",
    meta: "Claude Sonnet 5.5 · 2,140 tokens",
    start: 70,
    ms: 1300,
    detail: "1. Read new mail\n2. Tag each thread\n3. Draft replies for billing questions",
  },
  {
    kind: "tool",
    label: "Mailbox",
    meta: "Fetched 12 messages",
    start: 1410,
    ms: 620,
  },
  {
    kind: "search",
    label: "Knowledge base",
    meta: "Looked up 4 articles",
    start: 2070,
    ms: 480,
  },
  {
    kind: "model",
    label: "Wrote 4 drafts",
    meta: "9,820 tokens",
    start: 2590,
    ms: 3100,
  },
  {
    kind: "approval",
    label: "Waiting for approval",
    meta: "Autonomy: Drafts only",
    start: 5730,
    ms: 0,
    status: "running",
  },
];
export default function Preview() {
  return (
    <div
      className="tf-panel tf-panel-flush"
      style={{
        padding: 16,
      }}
    >
      <RunTrace
        steps={steps}
        defaultOpen={1}
        footer={
          <>
            <span>
              {"Model "}
              <b>Claude Sonnet 5.5</b>
            </span>
            <span>
              {"Tokens "}
              <b>11,960</b>
            </span>
            <span>
              {"Cost "}
              <b>€0.036</b>
            </span>
          </>
        }
      />
    </div>
  );
}
```

### Props

#### RunTrace

| Prop | Type | Notes |
| --- | --- | --- |
| `steps` | `TraceStep[]` | Required |
| `defaultOpen?` | `number \| null` |  |
| `footer?` | `ReactNode` |  |
| `className?` | `string` | Extra class on the root element. |
| `style?` | `CSSProperties` | Inline style on the root element. |


## Search Ad Preview

> A text ad as it appears in search results, on phone and desktop, with the length limits checked live.

Component · Admin · Halo kit · [Live page](https://ui.twentyfirst.media/halo/components/SearchAdPreview/)

A text ad as it appears in search results, on phone and desktop, with the length limits checked live.

Props: `name`, `domain`, `paths` (up to 2), `headlines` (up to 3 shown), `descriptions` (up to 2), `sitelinks`, `device` / `onDevice`, `sponsoredLabel`.

- Limits: headline 30, description 90, path 15 characters; anything longer is listed as a warning under the preview.
- The preview imitates the result layout in neutral colours, not the search engine's brand.

### Example

```tsx
import * as React from "react";
import { SearchAdPreview, TextField } from "@twentyfirstmedia/halo";

function App() {
  const hl = React.useState([
      "Real Instagram Followers",
      "Delivery in 1 Hour",
      "Trusted by 50,000 Creators",
    ]),
    ds = React.useState([
      "Grow your account with real followers. Secure payment, 30-day refill guarantee, German support.",
      "Start from €2.90. No password needed.",
    ]);
  return (
    <div
      className="tf-grid"
      style={
        {
          "--cols": "1fr 1fr",
          gap: 16,
          alignItems: "start",
        } as React.CSSProperties
      }
    >
      <div
        className="tf-panel"
        style={{
          gap: 12,
        }}
      >
        {hl[0].map((v, i) => (
          <TextField
            key={i}
            label={"Headline " + (i + 1)}
            value={v}
            onChange={(e) => {
              const n = hl[0].slice();
              n[i] = e.target.value;
              hl[1](n);
            }}
            hint={v.length + " / 30"}
          />
        ))}
        {ds[0].map((v, i) => (
          <TextField
            key={"d" + i}
            label={"Description " + (i + 1)}
            value={v}
            onChange={(e) => {
              const n = ds[0].slice();
              n[i] = e.target.value;
              ds[1](n);
            }}
            hint={v.length + " / 90"}
          />
        ))}
      </div>
      <div className="tf-panel">
        <SearchAdPreview
          name="Northwind"
          domain="northwind.de"
          paths={["instagram", "followers"]}
          headlines={hl[0]}
          descriptions={ds[0]}
          sitelinks={["Buy likes", "Pricing", "Refill guarantee", "Support"]}
        />
      </div>
    </div>
  );
}
export default App;
```

### Props

#### SearchAdPreview

| Prop | Type | Notes |
| --- | --- | --- |
| `name?` | `string` |  |
| `domain` | `string` | Required |
| `paths?` | `string[]` |  |
| `headlines?` | `string[]` |  |
| `descriptions?` | `string[]` |  |
| `sitelinks?` | `string[]` |  |
| `device?` | `"mobile" \| "desktop"` |  |
| `onDevice?` | `(d: string) => void` |  |
| `sponsoredLabel?` | `string` |  |
| `className?` | `string` | Extra class on the root element. |
| `style?` | `CSSProperties` | Inline style on the root element. |

#### TextField

| Prop | Type | Notes |
| --- | --- | --- |
| `type?` | `string` | Input type (`"text"` by default): `"email"`, `"number"`, `"tel"`, `"url"`, `"password"` … |
| `icon?` | `IconName` |  |
| `suffix?` | `ReactNode` |  |
| `value?` | `string` |  |
| `defaultValue?` | `string` |  |
| `placeholder?` | `string` |  |
| `disabled?` | `boolean` |  |
| `readOnly?` | `boolean` |  |
| `autoComplete?` | `string` |  |
| `autoFocus?` | `boolean` |  |
| `min?` | `number \| string` | Smallest value for `type="number"`, `"date"` and the like (native `min`). |
| `max?` | `number \| string` | Largest value (native `max`). |
| `step?` | `number \| string` | Step between valid values (native `step`), e.g. `1` for whole numbers or `"any"`. |
| `minLength?` | `number` | Fewest characters (native `minlength`). |
| `maxLength?` | `number` | Most characters (native `maxlength`). |
| `pattern?` | `string` | Pattern the value must match (native `pattern`). |
| `inputMode?` | `"none" \| "text" \| "tel" \| "url" \| "email" \| "numeric" \| "decimal" \| "search"` | Virtual keyboard on touch devices (native `inputmode`), e.g. `"numeric"` or `"decimal"`. |
| `onChange?` | `(e: ChangeEvent<HTMLInputElement>) => void` |  |
| `onBlur?` | `(e: ChangeEvent<HTMLInputElement>) => void` |  |
| `onKeyDown?` | `(e: KeyboardEvent<HTMLInputElement>) => void` |  |
| `action?` | `ReactNode` | An interactive control at the end of the field (an `IconButton`: clear, copy, locate …). Unlike `suffix` it can be clicked, and it stays when the field shows an error or success mark. |
| `reveal?` | `boolean` | For `type="password"`: a button that shows and hides the password (default true). |
| `label?` | `string` |  |
| `hint?` | `string` |  |
| `error?` | `string` |  |


## Secret Field

> SecretField shows a stored credential without exposing it; MoneyInput takes amounts in the locale's format with a VAT rate.

Component · Forms · Halo kit · [Live page](https://ui.twentyfirst.media/halo/components/SecretField/)

`SecretField` shows a stored credential without exposing it; `MoneyInput` takes amounts in the locale's format with a VAT rate.

SecretField: `prefix`, `last4`, `value` (shown only after `onReveal` resolves truthy; ask for a passkey there), `meta`, `onCopy`, `onRotate`.
MoneyInput: `label`, `value` / `onChange(number)`, `currency`, `vat` + `onVat` + `vatOptions`, `showGross`, `hint`, `error`. Parses and formats with setLocale.

- Never render a full secret by default; reveal is a step-up action.
- Amounts are right-aligned tabular mono so columns line up.

### Example

```tsx
import * as React from "react";
import { MoneyInput, SecretField } from "@twentyfirstmedia/halo";

function App() {
  const vat = React.useState("19"),
    v = React.useState<number | null>(1240);
  return (
    <div
      className="tf-panel"
      style={{
        gap: 24,
      }}
    >
      <SecretField
        prefix="sk_live_"
        last4="4f2a"
        meta="Added Mar 12"
        onReveal={() => true}
        value="sk_live_51Hx…demo…4f2a"
        onCopy={() => {}}
        onRotate={() => {}}
      />
      <MoneyInput
        label="Amount"
        value={v[0]}
        onChange={v[1]}
        vat={vat[0]}
        onVat={vat[1]}
        vatOptions={[
          {
            value: "19",
            label: "19%",
          },
          {
            value: "7",
            label: "7%",
          },
          {
            value: "0",
            label: "0%",
          },
          {
            value: "rc",
            label: "Reverse charge",
          },
        ]}
        showGross
        hint="Net, as on the invoice"
      />
    </div>
  );
}
export default App;
```

### Props

#### MoneyInput

| Prop | Type | Notes |
| --- | --- | --- |
| `label?` | `string` |  |
| `value?` | `number \| null` |  |
| `onChange?` | `(v: number \| null) => void` |  |
| `currency?` | `string` |  |
| `vat?` | `string` |  |
| `onVat?` | `(v: string) => void` |  |
| `vatOptions?` | `{ value: string; label: string; rate?: number }[]` |  |
| `showGross?` | `boolean` |  |
| `hint?` | `ReactNode` |  |
| `error?` | `ReactNode` |  |
| `defaultValue?` | `number \| null` |  |
| `required?` | `boolean` |  |
| `className?` | `string` | Extra class on the root element. |
| `style?` | `CSSProperties` | Inline style on the root element. |

#### SecretField

| Prop | Type | Notes |
| --- | --- | --- |
| `prefix?` | `string` |  |
| `last4?` | `string` |  |
| `value?` | `string` |  |
| `meta?` | `ReactNode` |  |
| `onReveal?` | `() => boolean \| Promise<boolean>` |  |
| `onCopy?` | `() => void` |  |
| `onRotate?` | `() => void` |  |
| `className?` | `string` | Extra class on the root element. |
| `style?` | `CSSProperties` | Inline style on the root element. |


## Settings Layout

> Standard settings page: a label column with one sentence on what it does, controls on the right, one row per topic.

Component · Foundations · Halo kit · [Live page](https://ui.twentyfirst.media/halo/components/SettingsLayout/)

Standard settings page: a label column with one sentence on what it does, controls on the right, one row per topic.

Props: `sections` ({id, title, text, badge, children}), `footer`. Stacks on narrow screens.

### Example

```tsx
import { Button, SecretField, Segmented, SettingsLayout, Switch } from "@twentyfirstmedia/halo";

export default function Preview() {
  return (
    <div className="tf-panel">
      <SettingsLayout
        sections={[
          {
            title: "Appearance",
            text: "Theme and density for this browser.",
            children: <Segmented defaultValue="System" options={["System", "Light", "Dark"]} />,
          },
          {
            title: "Notifications",
            text: "What reaches your phone.",
            children: [
              <Switch key={1} spread defaultChecked>
                Approvals waiting on me
              </Switch>,
              <Switch key={2} spread>
                Weekly digest
              </Switch>,
            ],
          },
          {
            title: "API key",
            text: "Used by the CLI.",
            children: <SecretField prefix="hq_" last4="9c1e" onCopy={() => {}} />,
          },
        ]}
        footer={<Button icon="check">Save changes</Button>}
      />
    </div>
  );
}
```

### Props

#### Button

| Prop | Type | Notes |
| --- | --- | --- |
| `variant?` | `"primary" \| "secondary" \| "soft" \| "ghost" \| "danger" \| "danger-solid"` |  |
| `size?` | `"md" \| "sm"` |  |
| `icon?` | `IconName` |  |
| `iconRight?` | `IconName` |  |
| `disabled?` | `boolean` |  |
| `type?` | `"button" \| "submit" \| "reset"` |  |
| `onClick?` | `(e: MouseEvent<HTMLButtonElement>) => void` |  |
| `children?` | `ReactNode` |  |
| `asChild?` | `boolean` | Render the single child element (a link, a router Link) with the button's look instead of a <button>. |
| `id?` | `string` |  |
| `name?` | `string` | Form field name and value, sent with the form when this button submits it. |
| `value?` | `string` |  |
| `form?` | `string` | The id of the form this button belongs to, when it sits outside it. |
| `title?` | `string` |  |
| `tabIndex?` | `number` |  |
| `autoFocus?` | `boolean` |  |
| `aria-label?` | `string` |  |
| `aria-labelledby?` | `string` |  |
| `aria-describedby?` | `string` |  |
| `aria-expanded?` | `boolean \| "true" \| "false"` | For disclosure and menu triggers: whether what the button controls is open. |
| `aria-controls?` | `string` |  |
| `aria-haspopup?` | `boolean \| "true" \| "false" \| "menu" \| "listbox" \| "tree" \| "grid" \| "dialog"` |  |
| `aria-pressed?` | `boolean \| "true" \| "false" \| "mixed"` | For toggle buttons. |
| `aria-current?` | `boolean \| "true" \| "false" \| "page" \| "step" \| "location" \| "date" \| "time"` |  |
| `className?` | `string` | Extra class on the root element. |
| `style?` | `CSSProperties` | Inline style on the root element. |

#### SecretField

| Prop | Type | Notes |
| --- | --- | --- |
| `prefix?` | `string` |  |
| `last4?` | `string` |  |
| `value?` | `string` |  |
| `meta?` | `ReactNode` |  |
| `onReveal?` | `() => boolean \| Promise<boolean>` |  |
| `onCopy?` | `() => void` |  |
| `onRotate?` | `() => void` |  |
| `className?` | `string` | Extra class on the root element. |
| `style?` | `CSSProperties` | Inline style on the root element. |

#### Segmented

| Prop | Type | Notes |
| --- | --- | --- |
| `options` | `(string \| Option)[]` | Required |
| `value?` | `string` |  |
| `defaultValue?` | `string` |  |
| `onChange?` | `(v: string) => void` |  |
| `size?` | `"sm"` |  |
| `block?` | `boolean` |  |
| `label?` | `string` |  |
| `className?` | `string` | Extra class on the root element. |
| `style?` | `CSSProperties` | Inline style on the root element. |

#### SettingsLayout

| Prop | Type | Notes |
| --- | --- | --- |
| `sections` | `{ id?: string; title: ReactNode; text?: ReactNode; badge?: ReactNode; children?: ReactNode; }[]` | Required |
| `footer?` | `ReactNode` |  |
| `className?` | `string` | Extra class on the root element. |
| `style?` | `CSSProperties` | Inline style on the root element. |

#### Switch

| Prop | Type | Notes |
| --- | --- | --- |
| `name?` | `string` |  |
| `checked?` | `boolean` |  |
| `defaultChecked?` | `boolean` |  |
| `onChange?` | `(e: ChangeEvent<HTMLInputElement>) => void` |  |
| `children?` | `ReactNode` |  |
| `spread?` | `boolean` |  |
| `disabled?` | `boolean` |  |
| `label?` | `string` |  |
| `className?` | `string` | Extra class on the root element. |
| `style?` | `CSSProperties` | Inline style on the root element. |


## Shortcuts Overlay

> The "?" overlay listing every keyboard shortcut, grouped by area.

Component · Overlays · Halo kit · [Live page](https://ui.twentyfirst.media/halo/components/ShortcutsOverlay/)

The "?" overlay listing every keyboard shortcut, grouped by area.

Props: `open`, `onClose`, `title`, `groups` ({title, items: [label, keys[]]}). Esc closes.

### Example

```tsx
import * as React from "react";
import { Button, ShortcutsOverlay } from "@twentyfirstmedia/halo";

function App() {
  const o = React.useState(true);
  return (
    <div
      style={{
        position: "relative",
        height: 460,
      }}
    >
      <Button
        onClick={() => {
          o[1](true);
        }}
      >
        Show shortcuts (?)
      </Button>
      <ShortcutsOverlay
        open={o[0]}
        onClose={() => {
          o[1](false);
        }}
        groups={[
          {
            title: "Global",
            items: [
              ["Search", ["⌘", "K"]],
              ["Shortcuts", ["?"]],
            ],
          },
          {
            title: "Navigation",
            items: [
              ["Go to chats", ["G", "C"]],
              ["Go to approvals", ["G", "A"]],
            ],
          },
          {
            title: "Approvals",
            items: [
              ["Run as shown", ["A"]],
              ["With a change", ["B"]],
              ["Discard", ["C"]],
              ["Other instruction", ["D"]],
              ["Next / previous", ["J", "K"]],
            ],
          },
        ]}
      />
    </div>
  );
}
export default App;
```

### Props

#### Button

| Prop | Type | Notes |
| --- | --- | --- |
| `variant?` | `"primary" \| "secondary" \| "soft" \| "ghost" \| "danger" \| "danger-solid"` |  |
| `size?` | `"md" \| "sm"` |  |
| `icon?` | `IconName` |  |
| `iconRight?` | `IconName` |  |
| `disabled?` | `boolean` |  |
| `type?` | `"button" \| "submit" \| "reset"` |  |
| `onClick?` | `(e: MouseEvent<HTMLButtonElement>) => void` |  |
| `children?` | `ReactNode` |  |
| `asChild?` | `boolean` | Render the single child element (a link, a router Link) with the button's look instead of a <button>. |
| `id?` | `string` |  |
| `name?` | `string` | Form field name and value, sent with the form when this button submits it. |
| `value?` | `string` |  |
| `form?` | `string` | The id of the form this button belongs to, when it sits outside it. |
| `title?` | `string` |  |
| `tabIndex?` | `number` |  |
| `autoFocus?` | `boolean` |  |
| `aria-label?` | `string` |  |
| `aria-labelledby?` | `string` |  |
| `aria-describedby?` | `string` |  |
| `aria-expanded?` | `boolean \| "true" \| "false"` | For disclosure and menu triggers: whether what the button controls is open. |
| `aria-controls?` | `string` |  |
| `aria-haspopup?` | `boolean \| "true" \| "false" \| "menu" \| "listbox" \| "tree" \| "grid" \| "dialog"` |  |
| `aria-pressed?` | `boolean \| "true" \| "false" \| "mixed"` | For toggle buttons. |
| `aria-current?` | `boolean \| "true" \| "false" \| "page" \| "step" \| "location" \| "date" \| "time"` |  |
| `className?` | `string` | Extra class on the root element. |
| `style?` | `CSSProperties` | Inline style on the root element. |

#### ShortcutsOverlay

| Prop | Type | Notes |
| --- | --- | --- |
| `open` | `boolean` | Required |
| `onClose` | `() => void` | Required |
| `title?` | `string` |  |
| `groups` | `{ title: string; items: [string, string[]][] }[]` | Required |
| `className?` | `string` | Extra class on the root element. |
| `style?` | `CSSProperties` | Inline style on the root element. |


## Split Pane

> Resizable list–detail layout.

Component · Foundations · Halo kit · [Live page](https://ui.twentyfirst.media/halo/components/SplitPane/)

Resizable list–detail layout. The divider is the hairline itself with a wider invisible grab area.

Props: `left`, `right`, `defaultSize` (px), `min`, `max`, `storageKey` (remembers the width in this browser).

- Use for mail, approvals and anything with a list and a reading pane. On phones stack the panes instead.

### Example

```tsx
import { InboxList, SplitPane } from "@twentyfirstmedia/halo";

export default function Preview() {
  return (
    <div
      className="tf-panel tf-panel-flush"
      style={{
        height: 280,
        padding: 0,
        overflow: "hidden",
      }}
    >
      <SplitPane
        defaultSize={320}
        min={220}
        max={600}
        storageKey="demo"
        left={
          <div
            style={{
              padding: 16,
            }}
          >
            <InboxList
              selected={1}
              items={[
                {
                  id: 1,
                  from: "Ida Nolan",
                  time: "08:40",
                  subject: "Seat upgrade before renewal",
                  snippet: "We are growing faster than planned…",
                  unread: true,
                },
                {
                  id: 2,
                  from: "Jonas Petit",
                  time: "Yesterday",
                  subject: "Pricing review → Thursday?",
                  snippet: "Growth wants to join…",
                },
              ]}
            />
          </div>
        }
        right={
          <div
            style={{
              padding: 24,
            }}
          >
            <b>Drag the divider</b>
            <p className="tf-card-desc">
              Double-click resets. ← → move it when focused. The width is remembered per storageKey.
            </p>
          </div>
        }
      />
    </div>
  );
}
```

### Props

#### InboxList

| Prop | Type | Notes |
| --- | --- | --- |
| `items` | `{ id: string \| number; from: string; time?: string; subject: string; snippet?: string; unread?: boolean; to?: string; agent?: { label: string; tone?: Tone }; tags?: string[]; }[]` | Required |
| `selected?` | `string \| number` |  |
| `onOpen?` | `(m: NonNullable<InboxListProps["items"]>[number]) => void` |  |
| `className?` | `string` | Extra class on the root element. |
| `style?` | `CSSProperties` | Inline style on the root element. |

#### SplitPane

| Prop | Type | Notes |
| --- | --- | --- |
| `left` | `ReactNode` | Required |
| `right` | `ReactNode` | Required |
| `defaultSize?` | `number` |  |
| `min?` | `number` |  |
| `max?` | `number` |  |
| `storageKey?` | `string` |  |
| `className?` | `string` | Extra class on the root element. |
| `style?` | `CSSProperties` | Inline style on the root element. |


## Stacked Bar Chart

> Bars split into parts of a whole per period, with a hover tooltip and legend.

Component · Charts · Halo kit · [Live page](https://ui.twentyfirst.media/halo/components/StackedBarChart/)

Bars split into parts of a whole per period, with a hover tooltip and legend.

Props: `labels`, `series` ({name, tint, values}), `height`, `width`, `barWidth`, `format(v)`, `legend` (false hides), `label`.

- Three series at most, ordered bottom-up from the steadiest to the most volatile.
- Segments use the tints' `-ink` colors with a 2px gap, so neighbours differ in lightness, not hue alone.
- Hovering a period dims the others and shows totals per series, top series first.

### Example

```tsx
import { StackedBarChart } from "@twentyfirstmedia/halo";

export default function Preview() {
  return (
    <div className="tf-panel">
      <div>
        <h3 className="tf-panel-title">Revenue by plan</h3>
        <p className="tf-panel-sub">Hover a bar for the split</p>
      </div>
      <StackedBarChart
        height={180}
        labels={["Nov", "Dec", "Jan", "Feb", "Mar", "Apr"]}
        format={(v) => "€" + (v / 1000).toFixed(1) + "k"}
        series={[
          {
            name: "Starter",
            tint: "sky",
            values: [3100, 3400, 3300, 3900, 4200, 4500],
          },
          {
            name: "Team",
            tint: "mint",
            values: [9800, 10400, 11200, 11900, 12800, 13600],
          },
          {
            name: "Business",
            tint: "lilac",
            values: [5200, 5900, 6100, 6600, 7400, 8100],
          },
        ]}
      />
    </div>
  );
}
```

### Props

#### StackedBarChart

| Prop | Type | Notes |
| --- | --- | --- |
| `labels` | `string[]` | Required |
| `series` | `Series[]` | Required |
| `height?` | `number` |  |
| `width?` | `number` |  |
| `barWidth?` | `number` |  |
| `format?` | `(v: number) => string` |  |
| `legend?` | `boolean` |  |
| `label?` | `string` |  |
| `className?` | `string` | Extra class on the root element. |
| `style?` | `CSSProperties` | Inline style on the root element. |


## Stat Cell

> A KPI with its comparison: label, value, ▲/▼ delta that names what it compares to, optional sparkline.

Component · Data · Halo kit · [Live page](https://ui.twentyfirst.media/halo/components/StatCell/)

A KPI with its comparison: label, value, ▲/▼ delta that names what it compares to, optional sparkline.

Props: `label`, `value`, `delta` (percent, signed), `deltaText` (override), `compare` ("vs last Friday"), `invert` (down is good: refunds, failures, cost), `spark` (numbers), `icon` + `iconTint`, `tint`.

- Use 3–5 in a row, only when those numbers are the point of the screen.
- Always say what the delta compares to; good is mint, bad is blush, decided by `invert`.

### Example

```tsx
import * as React from "react";
import { StatCell } from "@twentyfirstmedia/halo";

export default function Preview() {
  return (
    <div
      className="tf-grid"
      style={
        {
          "--cols": "repeat(4, minmax(0, 1fr))",
          "--cols-sm": "repeat(2, minmax(0, 1fr))",
          "--cols-md": "repeat(2, minmax(0, 1fr))",
          gap: 16,
        } as React.CSSProperties
      }
    >
      <StatCell
        label="Revenue today"
        value="€4,812"
        delta={12.4}
        compare="vs last Friday"
        spark={[3, 4, 4, 6, 5, 7, 8]}
        icon="card"
        iconTint="butter"
      />
      <StatCell
        label="Orders"
        value="128"
        delta={4.1}
        compare="vs last Friday"
        spark={[5, 6, 5, 7, 6, 8, 8]}
      />
      <StatCell
        label="Refund rate"
        value="1.2%"
        delta={-0.4}
        compare="vs last week"
        invert
        spark={[4, 4, 3, 3, 2, 2, 2]}
      />
      <StatCell
        label="Failed orders"
        value="7"
        delta={40}
        compare="vs yesterday"
        invert
        spark={[1, 2, 1, 3, 2, 4, 5]}
        tint="blush"
      />
    </div>
  );
}
```

### Props

#### StatCell

| Prop | Type | Notes |
| --- | --- | --- |
| `label` | `ReactNode` | Required |
| `value` | `ReactNode` | Required |
| `delta?` | `number` |  |
| `deltaText?` | `string` |  |
| `compare?` | `string` |  |
| `invert?` | `boolean` |  |
| `spark?` | `number[]` |  |
| `icon?` | `IconName` |  |
| `iconTint?` | `Tint` |  |
| `tint?` | `Tint` |  |
| `className?` | `string` | Extra class on the root element. |
| `style?` | `CSSProperties` | Inline style on the root element. |


## Stat Tile

> Data in Twentyfirst UI.

Component · Data · Halo kit · [Live page](https://ui.twentyfirst.media/halo/components/StatTile/)

### Example

```tsx
import * as React from "react";
import { Stagger, StatTile } from "@twentyfirstmedia/halo";

export default function Preview() {
  return (
    <Stagger
      className="tf-grid"
      style={
        {
          "--cols": "repeat(4, 1fr)",
          "--cols-sm": "repeat(2, minmax(0, 1fr))",
          "--cols-md": "repeat(2, minmax(0, 1fr))",
        } as React.CSSProperties
      }
    >
      <StatTile tint="sky" value="128" label="Active members" />
      <StatTile tint="mint" value="24" label="Live projects" delta="+3 this week" />
      <StatTile tint="placeholder" value="9" label="Needs review" />
      <StatTile tint="butter" value="€48,210" label="Revenue (MTD)" />
    </Stagger>
  );
}
```

### Props

#### Stagger

| Prop | Type | Notes |
| --- | --- | --- |
| `as?` | `string` |  |
| `className?` | `string` |  |
| `style?` | `CSSProperties` |  |
| `delay?` | `number` | Extra delay before the first child, in ms. |
| `reveal?` | `boolean` | Below the fold, wait until the group scrolls into view (default true). |
| `children?` | `ReactNode` |  |

#### StatTile

| Prop | Type | Notes |
| --- | --- | --- |
| `value` | `ReactNode` | Required |
| `label` | `string` | Required |
| `tint?` | `Tint \| "surface" \| "placeholder"` |  |
| `delta?` | `string` |  |
| `delay?` | `number` |  |
| `className?` | `string` | Extra class on the root element. |
| `style?` | `CSSProperties` | Inline style on the root element. |


## Status Indicator

> State as shape and colour together, so it reads at a glance and without colour vision.

Component · Foundations · Halo kit · [Live page](https://ui.twentyfirst.media/halo/components/StatusIndicator/)

State as shape and colour together, so it reads at a glance and without colour vision.

Props: `status` ("ok" | "running" | "signal" | "warn" | "danger" | "idle"), `label`, `size` ("sm"). `StatusShape` is the bare shape.

| status | shape | token | typical words |
| --- | --- | --- | --- |
| ok | dot | `ok` | Done, Online, Valid, Booked |
| running | pulsing dot | `info` | Working, Syncing |
| signal | diamond | `signal` | Waiting for approval, Needs a human |
| warn | triangle | `warn` | Paused · budget, Expiring |
| danger | square | `danger` | Failed, Offline |
| idle | ring | `idle` | Ready, Inactive |

- Always shape plus a word; drop the word only in dense columns whose header already names the state.
- Only `signal` may draw attention unasked. Warnings and errors stay in their own area and never animate.
- Badges use the same shapes: success dot, info dot, highlight diamond, warning triangle, danger square, neutral ring. Badge tones also accept the status names (ok, running, signal, warn, idle).

### Example

```tsx
import * as React from "react";
import { Badge, StatusIndicator } from "@twentyfirstmedia/halo";
import type { Status, Tone } from "@twentyfirstmedia/halo";

const S: [Status, string][] = [
  ["ok", "Done"],
  ["running", "Working"],
  ["signal", "Waiting for approval"],
  ["warn", "Paused · budget"],
  ["danger", "Failed"],
  ["idle", "Ready"],
];
export default function Preview() {
  return (
    <div
      className="tf-panel"
      style={{
        gap: 24,
      }}
    >
      <div
        className="tf-grid"
        style={
          {
            "--cols": "repeat(3, minmax(0, 1fr))",
            gap: 16,
          } as React.CSSProperties
        }
      >
        {S.map((s) => (
          <StatusIndicator key={s[0]} status={s[0]} label={s[1]} />
        ))}
      </div>
      <div className="tf-row">
        {(
          [
            ["success", "Live"],
            ["info", "Pending"],
            ["highlight", "Needs review"],
            ["warning", "Expiring"],
            ["danger", "Overdue"],
            ["neutral", "Draft"],
          ] as [Tone, string][]
        ).map((b) => (
          <Badge key={b[0]} tone={b[0]}>
            {b[1]}
          </Badge>
        ))}
      </div>
    </div>
  );
}
```

### Props

#### Badge

| Prop | Type | Notes |
| --- | --- | --- |
| `tone?` | `Tone` |  |
| `dot?` | `boolean` |  |
| `live?` | `boolean` |  |
| `children?` | `ReactNode` |  |
| `className?` | `string` | Extra class on the root element. |
| `style?` | `CSSProperties` | Inline style on the root element. |

#### StatusIndicator

| Prop | Type | Notes |
| --- | --- | --- |
| `status` | `Status` | Required |
| `label?` | `ReactNode` |  |
| `size?` | `"sm"` |  |
| `className?` | `string` | Extra class on the root element. |
| `style?` | `CSSProperties` | Inline style on the root element. |


## Table

> Quiet data table: uppercase captions, hairline rows, right-aligned tabular numbers.

Component · Data · Halo kit · [Live page](https://ui.twentyfirst.media/halo/components/Table/)

Quiet data table: uppercase captions, hairline rows, right-aligned tabular numbers.

Props: `columns` ({key, label, align, render}), `rows`. Place inside a `surface` Panel; numbers right-aligned; status as Badges.

### Example

```tsx
import { Avatar, Badge, Table } from "@twentyfirstmedia/halo";

export default function Preview() {
  return (
    <div
      style={{
        background: "var(--surface)",
        borderRadius: "var(--radius-lg)",
        padding: 8,
      }}
    >
      <Table
        columns={[
          {
            key: "name",
            label: "Customer",
            render: (r) => (
              <span className="tf-row">
                <Avatar name={r.name} size={26} />
                {r.name}
              </span>
            ),
          },
          {
            key: "plan",
            label: "Plan",
          },
          {
            key: "status",
            label: "Status",
            render: (r) => <Badge tone={r.tone}>{r.status}</Badge>,
          },
          {
            key: "mrr",
            label: "MRR",
            align: "right",
          },
        ]}
        rows={[
          {
            name: "Northwind",
            plan: "Team",
            status: "Active",
            tone: "success",
            mrr: "€1,240",
          },
          {
            name: "Blue Fern",
            plan: "Starter",
            status: "Trial",
            tone: "info",
            mrr: "€0",
          },
          {
            name: "Copperline",
            plan: "Business",
            status: "Past due",
            tone: "warning",
            mrr: "€3,900",
          },
        ]}
      />
    </div>
  );
}
```

### Props

#### Avatar

| Prop | Type | Notes |
| --- | --- | --- |
| `name` | `string` | Required |
| `src?` | `string` |  |
| `size?` | `number` |  |
| `tint?` | `Tint \| "surface-sunken"` |  |
| `className?` | `string` | Extra class on the root element. |
| `style?` | `CSSProperties` | Inline style on the root element. |

#### Badge

| Prop | Type | Notes |
| --- | --- | --- |
| `tone?` | `Tone` |  |
| `dot?` | `boolean` |  |
| `live?` | `boolean` |  |
| `children?` | `ReactNode` |  |
| `className?` | `string` | Extra class on the root element. |
| `style?` | `CSSProperties` | Inline style on the root element. |

#### Table

| Prop | Type | Notes |
| --- | --- | --- |
| `columns` | `TableColumn[]` | Required |
| `rows` | `Record<string, any>[]` | Required |
| `animate?` | `boolean` |  |
| `stack?` | `boolean` | Cards instead of columns when the table's box is narrow (up to 600px): every row stacks its cells, each with its column label. Without it narrow tables scroll sideways. |
| `className?` | `string` | Extra class on the root element. |
| `style?` | `CSSProperties` | Inline style on the root element. |


## Text Field

> Text input with label, required or optional mark, hint, and inline validation (error or success).

Component · Forms · Halo kit · [Live page](https://ui.twentyfirst.media/halo/components/TextField/)

Text input with label, required or optional mark, hint, and inline validation (error or success).

Props: `label`, `required`, `optional`, `hint`, `error`, `success`, `icon` (leading IconName), `suffix` (unit text), `type`, `value`, `defaultValue`, `onChange`, `onBlur`, `disabled`, `readOnly`, `placeholder`, `autoComplete`, `autoFocus`, `id`, `name`.

Native constraints go straight to the input, so the browser checks them and `Form` reads them: `min`, `max` and `step` (for `type="number"`, dates and times), `minLength`, `maxLength`, `pattern`, and `inputMode` for the touch keyboard.

```tsx
<TextField label="Seats" name="seats" type="number" min={1} max={50} step={1} required />
```

- `name` is the value's key in `Form` and where its validation message shows; `required` marks the label and sets the native attribute.
- Validate on blur, not on every key: show the error once the person leaves the field, then clear it live as they fix it.
- Error text says what is wrong in plain words ("That doesn’t look like an email address"), never "Invalid input".
- Use `success` sparingly, for checks that took effort (a free username, a verified domain).
- Mark the minority: if most fields are required, mark the optional ones instead.
- `FormField` is the same shell without an input, for wrapping custom controls.

### Example

```tsx
import * as React from "react";
import { TextField } from "@twentyfirstmedia/halo";

function App() {
  const e = React.useState("mara@"),
    n = React.useState("Mara Ellis");
  const bad = !/^[^@\s]+@[^@\s]+\.[a-z]{2,}$/i.test(e[0]);
  return (
    <div
      className="tf-panel tf-grid"
      style={
        {
          "--cols": "1fr 1fr",
          gap: 16,
        } as React.CSSProperties
      }
    >
      <TextField
        label="Full name"
        required
        value={n[0]}
        onChange={(x) => {
          n[1](x.target.value);
        }}
        success={n[0].length > 1 ? "Looks good" : null}
      />
      <TextField
        label="Email"
        required
        icon="mail"
        value={e[0]}
        onChange={(x) => {
          e[1](x.target.value);
        }}
        error={bad ? "That doesn’t look like an email address" : null}
      />
      <TextField label="Company" optional placeholder="Acme GmbH" hint="Shown on invoices" />
      <TextField label="Monthly budget" suffix="EUR" defaultValue="1,200" />
      <TextField
        label="Workspace URL"
        defaultValue="halo.app/acme"
        disabled
        hint="Ask an owner to change it"
      />
    </div>
  );
}
export default App;
```

### Props

#### TextField

| Prop | Type | Notes |
| --- | --- | --- |
| `type?` | `string` | Input type (`"text"` by default): `"email"`, `"number"`, `"tel"`, `"url"`, `"password"` … |
| `icon?` | `IconName` |  |
| `suffix?` | `ReactNode` |  |
| `value?` | `string` |  |
| `defaultValue?` | `string` |  |
| `placeholder?` | `string` |  |
| `disabled?` | `boolean` |  |
| `readOnly?` | `boolean` |  |
| `autoComplete?` | `string` |  |
| `autoFocus?` | `boolean` |  |
| `min?` | `number \| string` | Smallest value for `type="number"`, `"date"` and the like (native `min`). |
| `max?` | `number \| string` | Largest value (native `max`). |
| `step?` | `number \| string` | Step between valid values (native `step`), e.g. `1` for whole numbers or `"any"`. |
| `minLength?` | `number` | Fewest characters (native `minlength`). |
| `maxLength?` | `number` | Most characters (native `maxlength`). |
| `pattern?` | `string` | Pattern the value must match (native `pattern`). |
| `inputMode?` | `"none" \| "text" \| "tel" \| "url" \| "email" \| "numeric" \| "decimal" \| "search"` | Virtual keyboard on touch devices (native `inputmode`), e.g. `"numeric"` or `"decimal"`. |
| `onChange?` | `(e: ChangeEvent<HTMLInputElement>) => void` |  |
| `onBlur?` | `(e: ChangeEvent<HTMLInputElement>) => void` |  |
| `onKeyDown?` | `(e: KeyboardEvent<HTMLInputElement>) => void` |  |
| `action?` | `ReactNode` | An interactive control at the end of the field (an `IconButton`: clear, copy, locate …). Unlike `suffix` it can be clicked, and it stays when the field shows an error or success mark. |
| `reveal?` | `boolean` | For `type="password"`: a button that shows and hides the password (default true). |
| `label?` | `string` |  |
| `hint?` | `string` |  |
| `error?` | `string` |  |


## Toaster

> Short confirmation that something happened, with optional Undo.

Component · Overlays · Halo kit · [Live page](https://ui.twentyfirst.media/halo/components/Toaster/)

Short confirmation that something happened, with optional Undo. Call `toast(...)` anywhere; render `<Toaster/>` once.

`toast(text)` or `toast({ text, tone, icon, undo, action: {label, onClick}, duration })` returns an id; `toast.dismiss(id)`.
Toaster props: `position` ("bottom" default, "top").

- Tone follows the status map: success for done, info for started, danger for removed or failed.
- Offer `undo` for every reversible destructive action instead of a confirm dialog; Undo toasts last 6 s, others 4 s.
- Hover pauses the timer; the thin line at the bottom shows time left.
- One sentence, past tense, names the thing: "Invoice #2097 sent", not "Success!".

### Example

```tsx
import * as React from "react";
import { Button, Toaster, toast } from "@twentyfirstmedia/halo";

function App() {
  React.useEffect(() => {
    toast({
      text: "Invoice #2097 sent to Northwind",
      tone: "success",
      duration: 600000,
    });
    toast({
      text: "2 people removed",
      tone: "danger",
      icon: "trash",
      undo: () => {
        toast({
          text: "Restored",
          tone: "info",
          duration: 600000,
        });
      },
      duration: 600000,
    });
  }, []);
  return (
    <div
      className="tf-panel"
      style={{
        gap: 12,
      }}
    >
      <div className="tf-row">
        <Button
          variant="soft"
          onClick={() => {
            toast("Profile saved");
          }}
        >
          Success
        </Button>
        <Button
          variant="soft"
          onClick={() => {
            toast({
              text: "Build started for halo-web",
              tone: "info",
            });
          }}
        >
          Info
        </Button>
        <Button
          variant="soft"
          onClick={() => {
            toast({
              text: "Project archived",
              undo: () => {
                toast("Restored");
              },
            });
          }}
        >
          With undo
        </Button>
      </div>
      <p
        className="tf-card-desc"
        style={{
          margin: 0,
        }}
      >
        Toasts stack bottom-center above the dock, three at most. Hover pauses the timer.
      </p>
      <Toaster />
    </div>
  );
}
export default App;
```

### Props

#### Button

| Prop | Type | Notes |
| --- | --- | --- |
| `variant?` | `"primary" \| "secondary" \| "soft" \| "ghost" \| "danger" \| "danger-solid"` |  |
| `size?` | `"md" \| "sm"` |  |
| `icon?` | `IconName` |  |
| `iconRight?` | `IconName` |  |
| `disabled?` | `boolean` |  |
| `type?` | `"button" \| "submit" \| "reset"` |  |
| `onClick?` | `(e: MouseEvent<HTMLButtonElement>) => void` |  |
| `children?` | `ReactNode` |  |
| `asChild?` | `boolean` | Render the single child element (a link, a router Link) with the button's look instead of a <button>. |
| `id?` | `string` |  |
| `name?` | `string` | Form field name and value, sent with the form when this button submits it. |
| `value?` | `string` |  |
| `form?` | `string` | The id of the form this button belongs to, when it sits outside it. |
| `title?` | `string` |  |
| `tabIndex?` | `number` |  |
| `autoFocus?` | `boolean` |  |
| `aria-label?` | `string` |  |
| `aria-labelledby?` | `string` |  |
| `aria-describedby?` | `string` |  |
| `aria-expanded?` | `boolean \| "true" \| "false"` | For disclosure and menu triggers: whether what the button controls is open. |
| `aria-controls?` | `string` |  |
| `aria-haspopup?` | `boolean \| "true" \| "false" \| "menu" \| "listbox" \| "tree" \| "grid" \| "dialog"` |  |
| `aria-pressed?` | `boolean \| "true" \| "false" \| "mixed"` | For toggle buttons. |
| `aria-current?` | `boolean \| "true" \| "false" \| "page" \| "step" \| "location" \| "date" \| "time"` |  |
| `className?` | `string` | Extra class on the root element. |
| `style?` | `CSSProperties` | Inline style on the root element. |

#### Toaster

| Prop | Type | Notes |
| --- | --- | --- |
| `position?` | `"bottom" \| "top"` |  |
| `className?` | `string` | Extra class on the root element. |
| `style?` | `CSSProperties` | Inline style on the root element. |


## Tool Call

> Shows what an agent did between your question and its answer.

Component · AI · Halo kit · [Live page](https://ui.twentyfirst.media/halo/components/ToolCall/)

Shows what an agent did between your question and its answer. `ToolCall` is one tool use; `Reasoning` is the agent's plan.

ToolCall props: `name`, `icon`, `status` ("running" | "done" | "error" | "waiting"), `summary` (one line, past tense when done), `duration`, `input`, `output` (string or object, shown as JSON), `defaultOpen`.
Reasoning props: `steps` (string[]) or `text`, `duration`, `streaming` (shimmering "Thinking…"), `defaultOpen`.

- Collapsed by default: the one-line summary is what people read; details are there when they doubt it.
- Status icon colors follow the status map: mint done, sky running, butter waiting, blush error.
- Put them in ChatMessage's `before` slot, reasoning first, tools in the order they ran.

### Example

```tsx
import { Reasoning, ToolCall } from "@twentyfirstmedia/halo";

export default function Preview() {
  return (
    <div
      className="tf-panel"
      style={{
        gap: 8,
      }}
    >
      <Reasoning
        steps={[
          "Find the latest thread from Northwind",
          "Check seat pricing and the renewal date",
          "Draft a short reply, ask before sending",
        ]}
        duration="1.4 s"
        defaultOpen
      />
      <ToolCall
        name="Mailbox"
        icon="mail"
        status="done"
        summary="Read 3 messages in “Seat upgrade”"
        duration="0.8 s"
        defaultOpen
        input={{
          query: "from:ida@northwind.io",
          limit: 3,
        }}
        output={{
          messages: 3,
          latest: "We need 40 more seats before May 1.",
        }}
      />
      <ToolCall
        name="Knowledge base"
        icon="book"
        status="running"
        summary="Searching “seat upgrade pricing”"
      />
      <ToolCall
        name="Run checks"
        icon="terminal"
        status="error"
        summary="146 passed · 1 type error"
        duration="4.2 s"
        output="Seats.tsx:42  Type 'string' is not assignable to type 'number'."
      />
      <ToolCall
        name="Deployments"
        icon="zap"
        status="waiting"
        summary="Needs approval to deploy to production"
      />
      <Reasoning streaming />
    </div>
  );
}
```

### Props

#### Reasoning

| Prop | Type | Notes |
| --- | --- | --- |
| `steps?` | `string[]` |  |
| `text?` | `ReactNode` |  |
| `duration?` | `string` |  |
| `streaming?` | `boolean` |  |
| `defaultOpen?` | `boolean` |  |
| `className?` | `string` | Extra class on the root element. |
| `style?` | `CSSProperties` | Inline style on the root element. |

#### ToolCall

| Prop | Type | Notes |
| --- | --- | --- |
| `name` | `string` | Required |
| `icon?` | `IconName` |  |
| `status?` | `"running" \| "done" \| "error" \| "waiting"` |  |
| `summary?` | `ReactNode` |  |
| `duration?` | `string` |  |
| `input?` | `unknown` |  |
| `output?` | `unknown` |  |
| `defaultOpen?` | `boolean` |  |
| `className?` | `string` | Extra class on the root element. |
| `style?` | `CSSProperties` | Inline style on the root element. |


## Tooltip

> Tooltip names an icon-only control on hover or focus; Popover holds a small interactive panel anchored to a trigger.

Component · Overlays · Halo kit · [Live page](https://ui.twentyfirst.media/halo/components/Tooltip/)

`Tooltip` names an icon-only control on hover or focus; `Popover` holds a small interactive panel anchored to a trigger.

Tooltip props: `label`, `shortcut`, `side` ("top" | "bottom" | "left" | "right"), one child element.
Popover props: `trigger` (element, or `({open, toggle}) => element`), `open`/`onOpenChange` (optional control), `align` ("start" | "end"), `side` ("top"), `width`, `flush` (no padding, for Menus), `block`, children or `({close}) => children`.

- Tooltips only add a name or a shortcut. Anything you must read or click goes in a Popover.
- Tooltips appear after 350 ms on hover, immediately on keyboard focus, and close on Esc.
- Popovers close on outside click and Esc. Use a Modal when the task needs more than a few fields.

### Example

```tsx
import { Button, Combobox, Icon, Popover, Tooltip } from "@twentyfirstmedia/halo";

function App() {
  return (
    <div
      className="tf-panel"
      style={{
        gap: 40,
        paddingTop: 56,
      }}
    >
      <div
        className="tf-row"
        style={{
          gap: 16,
        }}
      >
        <Tooltip label="Archive" shortcut="E">
          <button type="button" className="tf-iconbtn tf-iconbtn-soft" aria-label="Archive">
            <Icon name="inbox" />
          </button>
        </Tooltip>
        <Tooltip label="Star">
          <button type="button" className="tf-iconbtn tf-iconbtn-soft" aria-label="Star">
            <Icon name="star" />
          </button>
        </Tooltip>
        <Tooltip label="Opens in a new tab" side="bottom">
          <button type="button" className="tf-btn tf-btn-secondary">
            View invoice
          </button>
        </Tooltip>
        <Tooltip label="Copy share link" shortcut="⌘L" defaultOpen>
          <button type="button" className="tf-iconbtn tf-iconbtn-soft" aria-label="Share">
            <Icon name="share" />
          </button>
        </Tooltip>
      </div>
      <div
        className="tf-row"
        style={{
          gap: 16,
          alignItems: "flex-start",
          // room for the open popover, so the preview shows it whole
          minHeight: 260,
        }}
      >
        <Popover
          open
          width={280}
          trigger={
            <button type="button" className="tf-btn tf-btn-soft">
              <Icon name="users" size={15} />
              Assign
            </button>
          }
        >
          <div
            className="tf-col"
            style={{
              gap: 12,
            }}
          >
            <b>Assign to</b>
            <Combobox
              options={["Ava Vogel", "Ben Okafor", "Clara Haddad"]}
              placeholder="Search people"
            />
            <div
              className="tf-row"
              style={{
                justifyContent: "flex-end",
              }}
            >
              <Button size="sm">Assign</Button>
            </div>
          </div>
        </Popover>
      </div>
    </div>
  );
}
export default App;
```

### Props

#### Button

| Prop | Type | Notes |
| --- | --- | --- |
| `variant?` | `"primary" \| "secondary" \| "soft" \| "ghost" \| "danger" \| "danger-solid"` |  |
| `size?` | `"md" \| "sm"` |  |
| `icon?` | `IconName` |  |
| `iconRight?` | `IconName` |  |
| `disabled?` | `boolean` |  |
| `type?` | `"button" \| "submit" \| "reset"` |  |
| `onClick?` | `(e: MouseEvent<HTMLButtonElement>) => void` |  |
| `children?` | `ReactNode` |  |
| `asChild?` | `boolean` | Render the single child element (a link, a router Link) with the button's look instead of a <button>. |
| `id?` | `string` |  |
| `name?` | `string` | Form field name and value, sent with the form when this button submits it. |
| `value?` | `string` |  |
| `form?` | `string` | The id of the form this button belongs to, when it sits outside it. |
| `title?` | `string` |  |
| `tabIndex?` | `number` |  |
| `autoFocus?` | `boolean` |  |
| `aria-label?` | `string` |  |
| `aria-labelledby?` | `string` |  |
| `aria-describedby?` | `string` |  |
| `aria-expanded?` | `boolean \| "true" \| "false"` | For disclosure and menu triggers: whether what the button controls is open. |
| `aria-controls?` | `string` |  |
| `aria-haspopup?` | `boolean \| "true" \| "false" \| "menu" \| "listbox" \| "tree" \| "grid" \| "dialog"` |  |
| `aria-pressed?` | `boolean \| "true" \| "false" \| "mixed"` | For toggle buttons. |
| `aria-current?` | `boolean \| "true" \| "false" \| "page" \| "step" \| "location" \| "date" \| "time"` |  |
| `className?` | `string` | Extra class on the root element. |
| `style?` | `CSSProperties` | Inline style on the root element. |

#### Combobox

| Prop | Type | Notes |
| --- | --- | --- |
| `label?` | `string` |  |
| `options` | `(string \| Option)[]` | Required |
| `value?` | `string \| string[] \| null` |  |
| `defaultValue?` | `string \| string[]` |  |
| `onChange?` | `(v: string \| string[] \| null) => void` |  |
| `multiple?` | `boolean` |  |
| `creatable?` | `boolean` |  |
| `placeholder?` | `string` |  |
| `hint?` | `string` |  |
| `error?` | `string` |  |
| `required?` | `boolean` |  |
| `className?` | `string` | Extra class on the root element. |
| `style?` | `CSSProperties` | Inline style on the root element. |

#### Icon

| Prop | Type | Notes |
| --- | --- | --- |
| `name` | `IconName` | Required |
| `size?` | `number` |  |
| `label?` | `string` |  |
| `className?` | `string` |  |
| `style?` | `CSSProperties` | Inline style on the root element. |

#### Popover

| Prop | Type | Notes |
| --- | --- | --- |
| `trigger` | `ReactNode \| ((s: { open: boolean; toggle: () => void }) => ReactNode)` | Required |
| `open?` | `boolean` |  |
| `onOpenChange?` | `(o: boolean) => void` |  |
| `align?` | `"start" \| "end"` |  |
| `side?` | `"top" \| "bottom"` |  |
| `width?` | `number` |  |
| `flush?` | `boolean` |  |
| `block?` | `boolean` |  |
| `role?` | `string` |  |
| `children?` | `ReactNode \| ((s: { close: () => void }) => ReactNode)` |  |
| `className?` | `string` | Extra class on the root element. |
| `style?` | `CSSProperties` | Inline style on the root element. |

#### Tooltip

| Prop | Type | Notes |
| --- | --- | --- |
| `label` | `ReactNode` | Required |
| `shortcut?` | `string` |  |
| `side?` | `"top" \| "bottom" \| "left" \| "right"` |  |
| `defaultOpen?` | `boolean` | Starts open (for demos and onboarding hints); it still closes on blur and Escape. |
| `children` | `ReactNode` | Required |
| `className?` | `string` | Extra class on the root element. |
| `style?` | `CSSProperties` | Inline style on the root element. |


## Tree View

> Hierarchies, in-place editing and object menus: TreeView, InlineEdit, ContextMenu.

Component · Foundations · Halo kit · [Live page](https://ui.twentyfirst.media/halo/components/TreeView/)

Hierarchies, in-place editing and object menus: `TreeView`, `InlineEdit`, `ContextMenu`.

TreeView: `items` ({id, label, icon, meta, children}), `defaultOpen` (ids), `selected` + `onSelect`, `label`. Arrow keys open, close and move; meta sits right in mono.
InlineEdit: `value`, `onSave(v)`, `options` (select instead of text), `mono`, `type`, `display(v)`, `align`. Double-click or Enter edits, Enter saves, Esc cancels.
ContextMenu: `items` (Menu items), children (the target). Right-click or a long press opens it at the pointer; destructive actions last.

### Example

```tsx
import * as React from "react";
import { ContextMenu, InlineEdit, KeyValue, TreeView } from "@twentyfirstmedia/halo";

const tree = [
  {
    id: "fx",
    label: "FollowerX GmbH",
    meta: "€48,210",
    children: [
      {
        id: "fp",
        label: "Northwind",
        meta: "€31,400",
        children: [
          {
            id: "ads",
            label: "Ads",
            meta: "€9,800",
          },
          {
            id: "smm",
            label: "SMM providers",
            meta: "€14,100",
          },
        ],
      },
      {
        id: "ch",
        label: "Chatteo",
        meta: "€12,610",
      },
    ],
  },
  {
    id: "tv",
    label: "Trepte Ventures UG",
    meta: "€4,200",
  },
];
function App() {
  const s = React.useState("ads");
  return (
    <div
      className="tf-grid"
      style={
        {
          "--cols": "1fr 1fr",
          gap: 16,
        } as React.CSSProperties
      }
    >
      <div
        className="tf-panel"
        style={{
          padding: 12,
        }}
      >
        <TreeView
          items={tree}
          defaultOpen={["fx", "fp"]}
          selected={s[0]}
          onSelect={s[1]}
          label="Cost centres"
        />
      </div>
      <div
        className="tf-panel"
        style={{
          gap: 16,
        }}
      >
        <span className="tf-card-desc">Double-click or Enter to edit</span>
        <KeyValue
          items={[
            [
              "Category",
              <InlineEdit value="Software" options={["Software", "Hosting", "Marketing"]} />,
            ],
            ["Amount", <InlineEdit value="1,240.00" mono />],
          ]}
        />
        <ContextMenu
          items={[
            {
              label: "Open",
              icon: "eye",
            },
            {
              label: "Rename",
              icon: "edit",
              shortcut: "R",
            },
            "-",
            {
              label: "Delete",
              icon: "trash",
              danger: true,
            },
          ]}
        >
          <div
            style={{
              padding: 24,
              borderRadius: "var(--radius-md)",
              background: "var(--canvas)",
              textAlign: "center",
            }}
          >
            Right-click or long-press here
          </div>
        </ContextMenu>
      </div>
    </div>
  );
}
export default App;
```

### Props

#### ContextMenu

| Prop | Type | Notes |
| --- | --- | --- |
| `items` | `(MenuItem \| "-")[]` | Required |
| `children` | `ReactNode` | Required |
| `className?` | `string` | Extra class on the root element. |
| `style?` | `CSSProperties` | Inline style on the root element. |

#### InlineEdit

| Prop | Type | Notes |
| --- | --- | --- |
| `value` | `string` | Required |
| `onSave?` | `(v: string) => void` |  |
| `options?` | `string[]` |  |
| `mono?` | `boolean` |  |
| `type?` | `string` |  |
| `display?` | `(v: string) => ReactNode` |  |
| `align?` | `"left" \| "right"` |  |
| `label?` | `string` |  |
| `className?` | `string` | Extra class on the root element. |
| `style?` | `CSSProperties` | Inline style on the root element. |

#### KeyValue

| Prop | Type | Notes |
| --- | --- | --- |
| `items` | `KeyValueItem[]` | Required |
| `dense?` | `boolean` |  |
| `className?` | `string` | Extra class on the root element. |
| `style?` | `CSSProperties` | Inline style on the root element. |

#### TreeView

| Prop | Type | Notes |
| --- | --- | --- |
| `items` | `TreeItem[]` | Required |
| `defaultOpen?` | `string[]` |  |
| `selected?` | `string` |  |
| `onSelect?` | `(id: string) => void` |  |
| `label?` | `string` |  |
| `className?` | `string` | Extra class on the root element. |
| `style?` | `CSSProperties` | Inline style on the root element. |


## Trigger List

> What starts agents and when: TriggerList and the week view ScheduleCalendar.

Component · AI · Halo kit · [Live page](https://ui.twentyfirst.media/halo/components/TriggerList/)

What starts agents and when: `TriggerList` and the week view `ScheduleCalendar`.

TriggerList: `items` ({id, type: "schedule" | "event" | "webhook" | "mail", rule, agent, by, next, enabled}), `onToggle(item)`, `onRun(item)`.
ScheduleCalendar: `events` ({day 0–6, start, end (hours), label, sub, tint, self}), `from`, `to`, `days` (labels; defaults to the locale's weekdays), `onOpen(event)`. Events an agent created for itself get a signal outline.

### Example

```tsx
import { ScheduleCalendar, TriggerList } from "@twentyfirstmedia/halo";

export default function Preview() {
  return (
    <div
      className="tf-col"
      style={{
        gap: 16,
      }}
    >
      <div className="tf-panel tf-panel-flush tf-panel-list">
        <TriggerList
          onToggle={() => {}}
          onRun={() => {}}
          items={[
            {
              id: 1,
              type: "schedule",
              rule: "Mon–Fri 08:00",
              agent: "Main Brain",
              by: "Config",
              next: "Tomorrow 08:00",
            },
            {
              id: 2,
              type: "mail",
              rule: "New mail to support@",
              agent: "Atlas",
              by: "Mara Ellis",
              next: "On event",
            },
            {
              id: 3,
              type: "webhook",
              rule: "Stripe dispute opened",
              agent: "Ledger",
              by: "Config",
              next: "On event",
              enabled: false,
            },
          ]}
        />
      </div>
      <div className="tf-panel tf-scroll-x">
        <ScheduleCalendar
          from={7}
          to={19}
          days={["Mon", "Tue", "Wed", "Thu", "Fri", "Sat", "Sun"]}
          events={[
            {
              day: 0,
              start: 8,
              end: 9,
              label: "Briefing",
              tint: "lilac",
            },
            {
              day: 1,
              start: 8,
              end: 9,
              label: "Briefing",
              tint: "lilac",
            },
            {
              day: 2,
              start: 10,
              end: 12,
              label: "Weekly report",
              sub: "Ledger",
              tint: "butter",
            },
            {
              day: 4,
              start: 14,
              end: 15,
              label: "Follow-ups",
              tint: "sky",
              self: true,
            },
          ]}
        />
      </div>
    </div>
  );
}
```

### Props

#### ScheduleCalendar

| Prop | Type | Notes |
| --- | --- | --- |
| `events` | `{ day: number; start: number; end: number; label: string; sub?: string; tint?: Tint; self?: boolean; }[]` | Required |
| `from?` | `number` |  |
| `to?` | `number` |  |
| `days?` | `string[]` |  |
| `onOpen?` | `(e: NonNullable<ScheduleCalendarProps["events"]>[number]) => void` |  |
| `className?` | `string` | Extra class on the root element. |
| `style?` | `CSSProperties` | Inline style on the root element. |

#### TriggerList

| Prop | Type | Notes |
| --- | --- | --- |
| `items` | `{ id: string \| number; type: "schedule" \| "event" \| "webhook" \| "mail"; rule: ReactNode; agent?: string; by?: string; next?: string; enabled?: boolean; }[]` | Required |
| `onToggle?` | `(item: NonNullable<TriggerListProps["items"]>[number]) => void` |  |
| `onRun?` | `(item: NonNullable<TriggerListProps["items"]>[number]) => void` |  |
| `className?` | `string` | Extra class on the root element. |
| `style?` | `CSSProperties` | Inline style on the root element. |


## Two Factor Setup

> Turning on two-factor sign-in: scan, confirm with a code, save recovery codes.

Component · Forms · Halo kit · [Live page](https://ui.twentyfirst.media/halo/components/TwoFactorSetup/)

Turning on two-factor sign-in: scan, confirm with a code, save recovery codes.

Props: `qr` (node: render the otpauth URI with your QR library), `secret`, `onVerify(code)` (return or resolve true/false), `codes` (recovery codes), `onDownload`, `onDone`, `step`, `scanText`, `codesText`.

- The last step stays locked until the person confirms they saved the codes. (In this preview the code 123456 works.)

### Example

```tsx
import { TwoFactorSetup } from "@twentyfirstmedia/halo";
function qr() {
  const cells = [],
    n = 25;
  let seed = 7;
  for (let y = 0; y < n; y++)
    for (let x = 0; x < n; x++) {
      seed = (seed * 9301 + 49297) % 233280;
      const f = (x < 7 && y < 7) || (x > 17 && y < 7) || (x < 7 && y > 17);
      const on = f
        ? (x % 6 === 0 || y % 6 === 0 || (x % 6 > 1 && x % 6 < 5 && y % 6 > 1 && y % 6 < 5)) &&
          !(x === 7 || y === 7)
        : seed / 233280 > 0.5;
      if (on) cells.push(<rect key={x + "-" + y} x={x} y={y} width={1} height={1} />);
    }
  return (
    <svg
      viewBox="0 0 25 25"
      width={144}
      height={144}
      fill="currentColor"
      shapeRendering="crispEdges"
    >
      {cells}
    </svg>
  );
}
export default function Preview() {
  return (
    <div className="tf-panel">
      <TwoFactorSetup
        qr={qr()}
        secret="JBSWY3DPEHPK3PXP"
        codes={[
          "8f2a-91c4",
          "3b7e-0d55",
          "a1c9-6f20",
          "7d44-e8b1",
          "c0f3-2a97",
          "5e18-b3d6",
          "9b62-4c0e",
          "e7a5-1f83",
        ]}
        onVerify={(c) => c === "123456"}
        onDownload={() => {}}
        onDone={() => {}}
      />
    </div>
  );
}
```

### Props

#### TwoFactorSetup

| Prop | Type | Notes |
| --- | --- | --- |
| `qr?` | `ReactNode` |  |
| `qrValue?` | `string` | The otpauth:// link: the kit draws its QR code (instead of `qr`). |
| `trustDevice?` | `boolean \| string` | A "Trust this device" checkbox under the code field; a string replaces its label. |
| `onTrustChange?` | `(trusted: boolean) => void` | The trust checkbox changed. |
| `secret` | `string` | Required |
| `onVerify?` | `(code: string) => boolean \| Promise<boolean>` |  |
| `codes?` | `string[]` |  |
| `onDownload?` | `() => void` |  |
| `onDone?` | `() => void` |  |
| `step?` | `0 \| 1 \| 2` |  |
| `scanText?` | `string` |  |
| `codesText?` | `string` |  |
| `className?` | `string` | Extra class on the root element. |
| `style?` | `CSSProperties` | Inline style on the root element. |


## Uptime Bar

> Health at a glance: UptimeBar (a bar per day), Meter (usage against a limit), ServerCard, DeployPipeline.

Component · Data · Halo kit · [Live page](https://ui.twentyfirst.media/halo/components/UptimeBar/)

Health at a glance: `UptimeBar` (a bar per day), `Meter` (usage against a limit), `ServerCard`, `DeployPipeline`.

UptimeBar: `days` ("ok" | "warn" | "danger" | "none" or {status, label, note}), `uptime` (percent), `caption`. Hover shows the day.
Meter: `label`, `value`, `max`, `text`, `warn` (75), `danger` (90), `tone`.
ServerCard: `name`, `provider`, `address`, `logo`, `status`, `statusLabel`, `meters` ({label, value, max, text, unknown}; value null shows "Unknown"), `uptime` (UptimeBar props), `foot`.
DeployPipeline: `stages` ({name, status: "done" | "running" | "signal" | "danger" | "idle", duration, action}).

### Example

```tsx
import * as React from "react";
import { DeployPipeline, Meter, ServerCard, UptimeBar } from "@twentyfirstmedia/halo";
import type { UptimeDay } from "@twentyfirstmedia/halo";

const days: UptimeDay[] = [];
for (let i = 0; i < 90; i++)
  days.push(
    i === 61
      ? {
          status: "danger",
          note: "14 min down",
        }
      : i === 40 || i === 77
        ? {
            status: "warn",
            note: "slow responses",
          }
        : {
            status: i < 6 ? "none" : "ok",
          },
  );
export default function Preview() {
  return (
    <div
      className="tf-grid"
      style={
        {
          "--cols": "1fr 1fr",
          gap: 16,
        } as React.CSSProperties
      }
    >
      <ServerCard
        name="ax41-fsn1"
        provider="Hetzner"
        address="95.217.14.80"
        status="ok"
        statusLabel="Online"
        meters={[
          {
            label: "CPU",
            value: 34,
            text: "34%",
          },
          {
            label: "RAM",
            value: 81,
            text: "52 / 64 GB",
          },
          {
            label: "Disk",
            value: null,
          },
        ]}
        foot="Last deploy 2 h ago · #482"
      />
      <div
        className="tf-panel"
        style={{
          gap: 16,
        }}
      >
        <b>northwind.de</b>
        <UptimeBar days={days} uptime={99.96} />
        <Meter label="Budget" value={82} text="€820 / €1,000" />
        <DeployPipeline
          stages={[
            {
              name: "Pull",
              status: "done",
              duration: "4 s",
            },
            {
              name: "Build",
              status: "done",
              duration: "1 m 12 s",
            },
            {
              name: "Approve",
              status: "signal",
            },
            {
              name: "Release",
            },
          ]}
        />
      </div>
    </div>
  );
}
```

### Props

#### DeployPipeline

| Prop | Type | Notes |
| --- | --- | --- |
| `stages` | `{ name: string; status?: "done" \| "running" \| "signal" \| "danger" \| "idle"; duration?: string; action?: ReactNode; }[]` | Required |
| `className?` | `string` | Extra class on the root element. |
| `style?` | `CSSProperties` | Inline style on the root element. |

#### Meter

| Prop | Type | Notes |
| --- | --- | --- |
| `label?` | `ReactNode` |  |
| `value` | `number \| null` | Required |
| `max?` | `number` |  |
| `text?` | `ReactNode` |  |
| `warn?` | `number` |  |
| `danger?` | `number` |  |
| `tone?` | `Tint` |  |
| `className?` | `string` | Extra class on the root element. |
| `style?` | `CSSProperties` | Inline style on the root element. |

#### ServerCard

| Prop | Type | Notes |
| --- | --- | --- |
| `name` | `string` | Required |
| `provider?` | `string` |  |
| `address?` | `string` |  |
| `logo?` | `ReactNode` |  |
| `status?` | `Status` |  |
| `statusLabel?` | `string` |  |
| `meters?` | `{ label: string; value: number \| null; max?: number; text?: ReactNode; unknown?: string; }[]` |  |
| `uptime?` | `UptimeBarProps` |  |
| `foot?` | `ReactNode` |  |
| `className?` | `string` | Extra class on the root element. |
| `style?` | `CSSProperties` | Inline style on the root element. |

#### UptimeBar

| Prop | Type | Notes |
| --- | --- | --- |
| `days` | `UptimeDay[]` | Required |
| `uptime?` | `number` |  |
| `caption?` | `ReactNode` |  |
| `className?` | `string` | Extra class on the root element. |
| `style?` | `CSSProperties` | Inline style on the root element. |


## Valuation Card

> Real-estate figures: ValuationCard (estimate with range and asking price), SavedSearch (a search that runs on its own and reports new hits) and EnergyClass (the energy label scale).

Component · Real estate · Halo kit · [Live page](https://ui.twentyfirst.media/halo/components/ValuationCard/)

Real-estate figures: `ValuationCard` (estimate with range and asking price), `SavedSearch` (a search that runs on its own and reports new hits) and `EnergyClass` (the energy label scale).

ValuationCard: `value`, `low`, `high`, `asking`, `perSqm`, `compare`, `currency`, `confidence` (0–1) or `confidenceLabel`, `facts` (KeyValue items), `note`, `title`, `action`.
SavedSearch: `name`, `criteria` (strings), `lastRun`, `frequency`, `newCount`, `enabled` + `onToggle`, `onEdit`, `onOpen`, `openLabel`, `icon`, `tint`.
EnergyClass: `value`, `kwh`, `kind`, `scale` (default A+…H).

### Example

```tsx
import * as React from "react";
import { EnergyClass, SavedSearch, ValuationCard } from "@twentyfirstmedia/halo";

export default function Preview() {
  return (
    <div
      className="tf-grid"
      style={
        {
          "--cols": "1fr 1fr",
          gap: 16,
          alignItems: "start",
        } as React.CSSProperties
      }
    >
      <div className="tf-panel">
        <ValuationCard
          value={612000}
          low={571000}
          high={655000}
          asking={649000}
          perSqm={7286}
          compare="district average €6,940"
          confidence={0.78}
          facts={[
            ["Comparables", "42 sales, last 18 months"],
            ["Method", "Comparable sales"],
            ["As of", "Nov 8, 2026"],
          ]}
          note="An estimate, not an appraisal."
        />
      </div>
      <div
        className="tf-col"
        style={{
          gap: 16,
        }}
      >
        <SavedSearch
          name="Eppendorf 3 rooms"
          criteria={[
            "Buy",
            "Hamburg-Eppendorf",
            "€400k–700k",
            "70–110 m²",
            "3+ rooms",
            "Private sellers",
          ]}
          lastRun="06:00"
          frequency="Daily mail"
          newCount={4}
          onToggle={() => {}}
          onEdit={() => {}}
          onOpen={() => {}}
        />
        <div
          className="tf-panel"
          style={{
            gap: 12,
          }}
        >
          <b>Energy</b>
          <EnergyClass value="C" kwh={92} kind="Consumption · gas" />
        </div>
      </div>
    </div>
  );
}
```

### Props

#### EnergyClass

| Prop | Type | Notes |
| --- | --- | --- |
| `value` | `string` | Required |
| `kwh?` | `number` |  |
| `kind?` | `string` |  |
| `scale?` | `string[]` |  |
| `className?` | `string` | Extra class on the root element. |
| `style?` | `CSSProperties` | Inline style on the root element. |

#### SavedSearch

| Prop | Type | Notes |
| --- | --- | --- |
| `name` | `string` | Required |
| `criteria?` | `ReactNode[]` |  |
| `lastRun?` | `string` |  |
| `frequency?` | `string` |  |
| `newCount?` | `number` |  |
| `enabled?` | `boolean` |  |
| `onToggle?` | `() => void` |  |
| `onEdit?` | `() => void` |  |
| `onOpen?` | `() => void` |  |
| `openLabel?` | `string` |  |
| `icon?` | `IconName` |  |
| `tint?` | `Tint` |  |
| `className?` | `string` | Extra class on the root element. |
| `style?` | `CSSProperties` | Inline style on the root element. |

#### ValuationCard

| Prop | Type | Notes |
| --- | --- | --- |
| `value` | `number` | Required |
| `low` | `number` | Required |
| `high` | `number` | Required |
| `asking?` | `number` |  |
| `perSqm?` | `number` |  |
| `compare?` | `string` |  |
| `currency?` | `string` |  |
| `confidence?` | `number` |  |
| `confidenceLabel?` | `string` |  |
| `facts?` | `KeyValueItem[]` |  |
| `note?` | `ReactNode` |  |
| `title?` | `string` |  |
| `action?` | `ReactNode` |  |
| `className?` | `string` | Extra class on the root element. |
| `style?` | `CSSProperties` | Inline style on the root element. |


## Variant Picker

> Pick a product option: colour swatches or text pills (sizes, materials).

Component · Commerce · Halo kit · [Live page](https://ui.twentyfirst.media/halo/components/VariantPicker/)

Pick a product option: colour swatches or text pills (sizes, materials).

Props: `label`, `type` ("color" for swatches), `options` (strings or {value, label, color, disabled}), `value` / `defaultValue`, `onChange`.

- The legend repeats the current choice ("Colour Sky") so swatches don't need text.
- Sold-out options stay visible but struck through and disabled, so people know the size exists.

### Example

```tsx
import { VariantPicker } from "@twentyfirstmedia/halo";

export default function Preview() {
  return (
    <div
      className="tf-panel"
      style={{
        gap: 24,
      }}
    >
      <VariantPicker
        label="Colour"
        type="color"
        defaultValue="Sky"
        options={[
          {
            value: "Sky",
            label: "Sky",
            color: "#9fc3f0",
          },
          {
            value: "Ink",
            label: "Ink",
            color: "#1d1d1f",
          },
          {
            value: "Bone",
            label: "Bone",
            color: "#ece6d9",
          },
          {
            value: "Moss",
            label: "Moss",
            color: "#7d9a5e",
            disabled: true,
          },
        ]}
      />
      <VariantPicker
        label="Size"
        defaultValue="M"
        options={[
          {
            value: "XS",
            label: "XS",
            disabled: true,
          },
          "S",
          "M",
          "L",
          "XL",
        ]}
      />
    </div>
  );
}
```

### Props

#### VariantPicker

| Prop | Type | Notes |
| --- | --- | --- |
| `label` | `string` | Required |
| `type?` | `"color"` |  |
| `options` | `(string \| { value: string; label?: string; color?: string; disabled?: boolean })[]` | Required |
| `value?` | `string` |  |
| `defaultValue?` | `string` |  |
| `onChange?` | `(v: string) => void` |  |
| `className?` | `string` | Extra class on the root element. |
| `style?` | `CSSProperties` | Inline style on the root element. |


## Voice Mode

> Talking to an agent instead of typing: same agent, same tools, same approvals, same thread.

Component · AI · Halo kit · [Live page](https://ui.twentyfirst.media/halo/components/VoiceMode/)

Talking to an agent instead of typing: same agent, same tools, same approvals, same thread.

Props: `name`, `tint`, `state` ("listening" | "thinking" | "speaking" | "idle"), `stateLabel`, `transcript`, `muted`, `onMute`, `onEnd`.

- Approvals asked by voice still show the ApprovalCard; money needs the passkey on screen.

### Example

```tsx
import * as React from "react";
import { Segmented, VoiceMode } from "@twentyfirstmedia/halo";
import type { VoiceModeProps } from "@twentyfirstmedia/halo";

function App() {
  const s = React.useState<VoiceModeProps["state"]>("listening");
  return (
    <div
      className="tf-col"
      style={{
        gap: 16,
      }}
    >
      <Segmented
        value={s[0]}
        onChange={(v) => s[1](v as VoiceModeProps["state"])}
        options={[
          { value: "listening", label: "Listening" },
          { value: "thinking", label: "Thinking" },
          { value: "speaking", label: "Speaking" },
          { value: "idle", label: "Idle" },
        ]}
      />
      <VoiceMode
        name="Atlas"
        tint="sky"
        state={s[0]}
        transcript={s[0] === "speaking" ? "“I drafted the reply. Should I send it?”" : null}
        onMute={() => {}}
        onEnd={() => {}}
      />
    </div>
  );
}
export default App;
```

### Props

#### Segmented

| Prop | Type | Notes |
| --- | --- | --- |
| `options` | `(string \| Option)[]` | Required |
| `value?` | `string` |  |
| `defaultValue?` | `string` |  |
| `onChange?` | `(v: string) => void` |  |
| `size?` | `"sm"` |  |
| `block?` | `boolean` |  |
| `label?` | `string` |  |
| `className?` | `string` | Extra class on the root element. |
| `style?` | `CSSProperties` | Inline style on the root element. |

#### VoiceMode

| Prop | Type | Notes |
| --- | --- | --- |
| `name` | `string` | Required |
| `tint?` | `Tint` |  |
| `state` | `"listening" \| "thinking" \| "speaking" \| "idle"` | Required |
| `stateLabel?` | `string` |  |
| `transcript?` | `ReactNode` |  |
| `muted?` | `boolean` |  |
| `onMute?` | `() => void` |  |
| `onEnd?` | `() => void` |  |
| `className?` | `string` | Extra class on the root element. |
| `style?` | `CSSProperties` | Inline style on the root element. |


## Accordion

> Stacked sections that open and close.

Component · Foundations · Halo kit · [Live page](https://ui.twentyfirst.media/halo/components/Accordion/)

Stacked sections that open and close. One section at a time by default, or several with `multiple`.

- `cards` (default) shows each section as a card; `flush` uses hairlines, for use inside a panel.
- Keyboard: Tab reaches each header, ↑/↓ move between headers, Home/End jump, Enter or Space toggles.
- Headers are buttons with `aria-expanded`; panels are regions labelled by their header.

### Example

```tsx
import * as React from "react";
import { Accordion, Badge, Panel } from "@twentyfirstmedia/halo";

export default function Preview() {
  return (
    <div
      className="tf-grid"
      style={{ "--cols": "1fr 1fr", gap: 24, alignItems: "start" } as React.CSSProperties}
    >
      <Accordion
        defaultValue={["billing"]}
        items={[
          {
            id: "billing",
            title: "How does billing work?",
            content:
              "You pay per seat and month. Seats added mid-cycle are prorated to the next invoice.",
          },
          {
            id: "export",
            title: "Can I export my data?",
            content: "Yes. Every table exports to CSV, and the API returns the same fields.",
          },
          {
            id: "sso",
            title: "Do you support single sign-on?",
            meta: <Badge tone="info">Team plan</Badge>,
            content: "SAML and OIDC are included from the Team plan up.",
          },
          { id: "old", title: "Legacy importer", disabled: true, content: "" },
        ]}
      />
      <Panel title="Settings">
        <Accordion
          variant="flush"
          multiple
          defaultValue={["n", "p"]}
          items={[
            {
              id: "n",
              icon: "bell",
              title: "Notifications",
              content: "Approvals and overdue invoices reach you by mail and push.",
            },
            {
              id: "p",
              icon: "lock",
              title: "Privacy",
              content: "Workspace data stays in the EU region.",
            },
            {
              id: "a",
              icon: "code",
              title: "API access",
              content: "Two active keys. Rotate them from Developer settings.",
            },
          ]}
        />
      </Panel>
    </div>
  );
}
```

### Props

#### Accordion

| Prop | Type | Notes |
| --- | --- | --- |
| `items` | `AccordionItem[]` | Required |
| `multiple?` | `boolean` | Several sections open at once (default: one at a time). |
| `value?` | `string[]` | Open section ids (controlled). |
| `defaultValue?` | `string[]` |  |
| `onChange?` | `(open: string[]) => void` |  |
| `variant?` | `"cards" \| "flush"` | `cards`: each section is a card; `flush`: hairlines only (inside a panel). |
| `className?` | `string` | Extra class on the root element. |
| `style?` | `CSSProperties` | Inline style on the root element. |

#### Badge

| Prop | Type | Notes |
| --- | --- | --- |
| `tone?` | `Tone` |  |
| `dot?` | `boolean` |  |
| `live?` | `boolean` |  |
| `children?` | `ReactNode` |  |
| `className?` | `string` | Extra class on the root element. |
| `style?` | `CSSProperties` | Inline style on the root element. |

#### Panel

| Prop | Type | Notes |
| --- | --- | --- |
| `side?` | `boolean` |  |
| `title?` | `string` |  |
| `subtitle?` | `string` |  |
| `action?` | `ReactNode` |  |
| `children?` | `ReactNode` |  |
| `surface?` | `Surface` | `"glass"`: translucent glass over what is behind (maps, 3D, video, photos); `"solid"` opts out inside a glass `UIProvider`. |
| `className?` | `string` | Extra class on the root element. |
| `style?` | `CSSProperties` | Inline style on the root element. |


## Separator

> Small layout primitives.

Component · Foundations · Halo kit · [Live page](https://ui.twentyfirst.media/halo/components/Separator/)

Small layout primitives.

- **Separator**: a hairline between groups, horizontal or vertical, optionally with a label in the middle ("or").
- **Label**: the field label on its own, with a required mark or a muted hint ("optional").
- **AspectRatio**: a box that keeps its ratio (16 : 9 by default) for images, video and placeholders.

### Example

```tsx
import * as React from "react";
import { AspectRatio, Button, Input, Label, Separator } from "@twentyfirstmedia/halo";

export default function Preview() {
  return (
    <div
      className="tf-grid"
      style={{ "--cols": "1fr 1fr", gap: 24, alignItems: "start" } as React.CSSProperties}
    >
      <div className="tf-panel" style={{ gap: 16 }}>
        <div className="tf-col" style={{ gap: 8 }}>
          <Label htmlFor="sep-mail" required>
            Work email
          </Label>
          <Input id="sep-mail" placeholder="you@company.com" />
        </div>
        <div className="tf-col" style={{ gap: 8 }}>
          <Label htmlFor="sep-team" hint="optional">
            Team name
          </Label>
          <Input id="sep-team" placeholder="Design" />
        </div>
        <Separator label="or" />
        <Button variant="secondary" icon="globe">
          Continue with Google
        </Button>
        <div className="tf-row" style={{ gap: 12, alignItems: "center", flexWrap: "nowrap" }}>
          <span className="tf-card-desc">Docs</span>
          <Separator orientation="vertical" />
          <span className="tf-card-desc">Status</span>
          <Separator orientation="vertical" />
          <span className="tf-card-desc">Changelog</span>
        </div>
      </div>
      <div className="tf-panel" style={{ gap: 12 }}>
        <AspectRatio ratio={16 / 9}>
          <div
            className="tf-gallery-ph tf-t-sky"
            style={{ height: "100%", display: "grid", placeItems: "center" }}
          >
            16 : 9
          </div>
        </AspectRatio>
        <div
          className="tf-grid"
          style={{ "--cols": "1fr 1fr", "--cols-sm": "1fr 1fr", gap: 12 } as React.CSSProperties}
        >
          <AspectRatio ratio={1}>
            <div
              className="tf-gallery-ph tf-t-mint"
              style={{ height: "100%", display: "grid", placeItems: "center" }}
            >
              1 : 1
            </div>
          </AspectRatio>
          <AspectRatio ratio={4 / 5}>
            <div
              className="tf-gallery-ph tf-t-butter"
              style={{ height: "100%", display: "grid", placeItems: "center" }}
            >
              4 : 5
            </div>
          </AspectRatio>
        </div>
      </div>
    </div>
  );
}
```

### Props

#### Separator

| Prop | Type | Notes |
| --- | --- | --- |
| `orientation?` | `"horizontal" \| "vertical"` |  |
| `label?` | `string` | Text in the middle of the line ("or"). |
| `className?` | `string` | Extra class on the root element. |
| `style?` | `CSSProperties` | Inline style on the root element. |

#### Label

| Prop | Type | Notes |
| --- | --- | --- |
| `htmlFor?` | `string` |  |
| `required?` | `boolean` |  |
| `hint?` | `ReactNode` | Muted text after the label ("optional"). |
| `children?` | `ReactNode` |  |
| `className?` | `string` | Extra class on the root element. |
| `style?` | `CSSProperties` | Inline style on the root element. |

#### AspectRatio

| Prop | Type | Notes |
| --- | --- | --- |
| `ratio?` | `number` | Width divided by height (default 16 / 9). |
| `children?` | `ReactNode` |  |
| `className?` | `string` | Extra class on the root element. |
| `style?` | `CSSProperties` | Inline style on the root element. |

#### Input

| Prop | Type | Notes |
| --- | --- | --- |
| `type?` | `string` |  |
| `placeholder?` | `string` |  |
| `value?` | `string` |  |
| `defaultValue?` | `string` |  |
| `disabled?` | `boolean` |  |
| `onChange?` | `(e: ChangeEvent<HTMLInputElement>) => void` |  |
| `label?` | `string` |  |
| `hint?` | `string` |  |
| `error?` | `string` |  |
| `className?` | `string` | Extra class on the root element. |
| `style?` | `CSSProperties` | Inline style on the root element. |

#### Button

| Prop | Type | Notes |
| --- | --- | --- |
| `variant?` | `"primary" \| "secondary" \| "soft" \| "ghost" \| "danger" \| "danger-solid"` |  |
| `size?` | `"md" \| "sm"` |  |
| `icon?` | `IconName` |  |
| `iconRight?` | `IconName` |  |
| `disabled?` | `boolean` |  |
| `type?` | `"button" \| "submit" \| "reset"` |  |
| `onClick?` | `(e: MouseEvent<HTMLButtonElement>) => void` |  |
| `children?` | `ReactNode` |  |
| `asChild?` | `boolean` | Render the single child element (a link, a router Link) with the button's look instead of a <button>. |
| `id?` | `string` |  |
| `name?` | `string` | Form field name and value, sent with the form when this button submits it. |
| `value?` | `string` |  |
| `form?` | `string` | The id of the form this button belongs to, when it sits outside it. |
| `title?` | `string` |  |
| `tabIndex?` | `number` |  |
| `autoFocus?` | `boolean` |  |
| `aria-label?` | `string` |  |
| `aria-labelledby?` | `string` |  |
| `aria-describedby?` | `string` |  |
| `aria-expanded?` | `boolean \| "true" \| "false"` | For disclosure and menu triggers: whether what the button controls is open. |
| `aria-controls?` | `string` |  |
| `aria-haspopup?` | `boolean \| "true" \| "false" \| "menu" \| "listbox" \| "tree" \| "grid" \| "dialog"` |  |
| `aria-pressed?` | `boolean \| "true" \| "false" \| "mixed"` | For toggle buttons. |
| `aria-current?` | `boolean \| "true" \| "false" \| "page" \| "step" \| "location" \| "date" \| "time"` |  |
| `className?` | `string` | Extra class on the root element. |
| `style?` | `CSSProperties` | Inline style on the root element. |


## Button Group

> Attached buttons that act as one control: undo/redo, zoom, or a split button whose arrow opens a menu.

Component · Foundations · Halo kit · [Live page](https://ui.twentyfirst.media/halo/components/ButtonGroup/)

Attached buttons that act as one control: undo/redo, zoom, or a split button whose arrow opens a menu.

- Children are regular `Button`, `IconButton` or a `Popover` trigger; the group only joins their corners.
- `label` names the group for assistive tech; `orientation="vertical"` stacks them.

### Example

```tsx
import { Button, ButtonGroup, IconButton, Menu, Popover } from "@twentyfirstmedia/halo";

export default function Preview() {
  return (
    <div className="tf-panel" style={{ gap: 20, paddingBottom: 200 }}>
      <div className="tf-row" style={{ gap: 16 }}>
        <ButtonGroup label="History">
          <Button variant="secondary" icon="undo">
            Undo
          </Button>
          <Button variant="secondary" icon="redo">
            Redo
          </Button>
        </ButtonGroup>
        <ButtonGroup label="Zoom">
          <IconButton icon="minus" label="Zoom out" variant="outline" />
          <Button variant="secondary">100%</Button>
          <IconButton icon="plus" label="Zoom in" variant="outline" />
        </ButtonGroup>
      </div>
      <ButtonGroup label="Publish">
        <Button icon="send">Publish</Button>
        <Popover
          open
          flush
          align="end"
          trigger={<IconButton icon="chevronDown" label="More publish options" variant="solid" />}
        >
          <Menu
            items={[
              { label: "Schedule…", icon: "calendar" },
              { label: "Publish to staging", icon: "upload" },
              "-",
              { label: "Save as draft", icon: "file" },
            ]}
          />
        </Popover>
      </ButtonGroup>
    </div>
  );
}
```

### Props

#### ButtonGroup

| Prop | Type | Notes |
| --- | --- | --- |
| `label?` | `string` | Accessible name of the group. |
| `orientation?` | `"horizontal" \| "vertical"` |  |
| `children?` | `ReactNode` |  |
| `className?` | `string` | Extra class on the root element. |
| `style?` | `CSSProperties` | Inline style on the root element. |

#### Button

| Prop | Type | Notes |
| --- | --- | --- |
| `variant?` | `"primary" \| "secondary" \| "soft" \| "ghost" \| "danger" \| "danger-solid"` |  |
| `size?` | `"md" \| "sm"` |  |
| `icon?` | `IconName` |  |
| `iconRight?` | `IconName` |  |
| `disabled?` | `boolean` |  |
| `type?` | `"button" \| "submit" \| "reset"` |  |
| `onClick?` | `(e: MouseEvent<HTMLButtonElement>) => void` |  |
| `children?` | `ReactNode` |  |
| `asChild?` | `boolean` | Render the single child element (a link, a router Link) with the button's look instead of a <button>. |
| `id?` | `string` |  |
| `name?` | `string` | Form field name and value, sent with the form when this button submits it. |
| `value?` | `string` |  |
| `form?` | `string` | The id of the form this button belongs to, when it sits outside it. |
| `title?` | `string` |  |
| `tabIndex?` | `number` |  |
| `autoFocus?` | `boolean` |  |
| `aria-label?` | `string` |  |
| `aria-labelledby?` | `string` |  |
| `aria-describedby?` | `string` |  |
| `aria-expanded?` | `boolean \| "true" \| "false"` | For disclosure and menu triggers: whether what the button controls is open. |
| `aria-controls?` | `string` |  |
| `aria-haspopup?` | `boolean \| "true" \| "false" \| "menu" \| "listbox" \| "tree" \| "grid" \| "dialog"` |  |
| `aria-pressed?` | `boolean \| "true" \| "false" \| "mixed"` | For toggle buttons. |
| `aria-current?` | `boolean \| "true" \| "false" \| "page" \| "step" \| "location" \| "date" \| "time"` |  |
| `className?` | `string` | Extra class on the root element. |
| `style?` | `CSSProperties` | Inline style on the root element. |

#### IconButton

| Prop | Type | Notes |
| --- | --- | --- |
| `icon` | `IconName` | Required |
| `label` | `string` | Accessible name and tooltip (`aria-label` and `title`); `aria-label` or `title` override them. |
| `variant?` | `"soft" \| "solid" \| "outline" \| "ghost"` |  |
| `size?` | `"sm" \| "md" \| "lg"` |  |
| `type?` | `"button" \| "submit" \| "reset"` |  |
| `onClick?` | `(e: MouseEvent<HTMLButtonElement>) => void` |  |
| `disabled?` | `boolean` |  |
| `asChild?` | `boolean` | Render the single child element (a link) with the button's look; the icon is placed inside it. |
| `children?` | `ReactNode` |  |
| `id?` | `string` |  |
| `name?` | `string` | Form field name and value, sent with the form when this button submits it. |
| `value?` | `string` |  |
| `form?` | `string` | The id of the form this button belongs to, when it sits outside it. |
| `title?` | `string` |  |
| `tabIndex?` | `number` |  |
| `autoFocus?` | `boolean` |  |
| `aria-label?` | `string` |  |
| `aria-labelledby?` | `string` |  |
| `aria-describedby?` | `string` |  |
| `aria-expanded?` | `boolean \| "true" \| "false"` | For disclosure and menu triggers: whether what the button controls is open. |
| `aria-controls?` | `string` |  |
| `aria-haspopup?` | `boolean \| "true" \| "false" \| "menu" \| "listbox" \| "tree" \| "grid" \| "dialog"` |  |
| `aria-pressed?` | `boolean \| "true" \| "false" \| "mixed"` | For toggle buttons. |
| `aria-current?` | `boolean \| "true" \| "false" \| "page" \| "step" \| "location" \| "date" \| "time"` |  |
| `className?` | `string` | Extra class on the root element. |
| `style?` | `CSSProperties` | Inline style on the root element. |

#### Popover

| Prop | Type | Notes |
| --- | --- | --- |
| `trigger` | `ReactNode \| ((s: { open: boolean; toggle: () => void }) => ReactNode)` | Required |
| `open?` | `boolean` |  |
| `onOpenChange?` | `(o: boolean) => void` |  |
| `align?` | `"start" \| "end"` |  |
| `side?` | `"top" \| "bottom"` |  |
| `width?` | `number` |  |
| `flush?` | `boolean` |  |
| `block?` | `boolean` |  |
| `role?` | `string` |  |
| `children?` | `ReactNode \| ((s: { close: () => void }) => ReactNode)` |  |
| `className?` | `string` | Extra class on the root element. |
| `style?` | `CSSProperties` | Inline style on the root element. |

#### Menu

| Prop | Type | Notes |
| --- | --- | --- |
| `items` | `(MenuItem \| "-")[]` | Required |
| `label?` | `string` | Accessible name of the menu. |
| `autoFocus?` | `boolean` | Focus the first item on mount (menus opened from a button or the keyboard). |
| `onClose?` | `() => void` | Called after an item runs, and on Escape, so the owner can close the menu. |
| `className?` | `string` | Extra class on the root element. |
| `style?` | `CSSProperties` | Inline style on the root element. |


## Scroll Area

> A scrolling box with thin scrollbars in the kit's colours, vertical, horizontal or both.

Component · Foundations · Halo kit · [Live page](https://ui.twentyfirst.media/halo/components/ScrollArea/)

A scrolling box with thin scrollbars in the kit's colours, vertical, horizontal or both.

- The area is a focusable region with a name (`label`), so it scrolls with the arrow keys.
- Scrolling stays inside the box (no scroll chaining into the page).

### Example

```tsx
import * as React from "react";
import { Avatar, ScrollArea, Separator } from "@twentyfirstmedia/halo";

const PEOPLE = [
  "Mara Ellis",
  "Jonah Petit",
  "Sun Lee",
  "Rui Costa",
  "Ava Brandt",
  "Ida Nolan",
  "Theo Marsh",
  "Clara Haddad",
  "Ben Okafor",
  "Lena Vogt",
  "Omar Said",
  "Pia Lund",
];

export default function Preview() {
  return (
    <div
      className="tf-grid"
      style={{ "--cols": "320px 1fr", gap: 24, alignItems: "start" } as React.CSSProperties}
    >
      <div className="tf-panel" style={{ gap: 12, padding: 16 }}>
        <b>Team · {PEOPLE.length}</b>
        <ScrollArea label="Team members" height={240}>
          <div className="tf-col" style={{ gap: 4 }}>
            {PEOPLE.map((n) => (
              <div
                key={n}
                className="tf-row"
                style={{ gap: 12, padding: "6px 4px", flexWrap: "nowrap" }}
              >
                <Avatar name={n} size={28} />
                <span>{n}</span>
              </div>
            ))}
          </div>
        </ScrollArea>
      </div>
      <div className="tf-panel" style={{ gap: 12, padding: 16 }}>
        <b>Releases</b>
        <ScrollArea label="Releases" orientation="horizontal">
          <div className="tf-row" style={{ gap: 12, flexWrap: "nowrap", paddingBottom: 8 }}>
            {["v2.4", "v2.3", "v2.2", "v2.1", "v2.0", "v1.9", "v1.8"].map((v, i) => (
              <div key={v} className="tf-card" style={{ minWidth: 160, minHeight: 0, gap: 4 }}>
                <b>{v}</b>
                <span className="tf-card-desc">
                  {["Apr", "Mar", "Feb", "Jan", "Dec", "Nov", "Oct"][i]} release
                </span>
              </div>
            ))}
          </div>
        </ScrollArea>
        <Separator />
        <span className="tf-card-desc">
          Scroll sideways, or focus the area and use the arrow keys.
        </span>
      </div>
    </div>
  );
}
```

### Props

#### ScrollArea

| Prop | Type | Notes |
| --- | --- | --- |
| `height?` | `number \| string` | Fixed height of the scrolling box. |
| `maxHeight?` | `number \| string` |  |
| `orientation?` | `"vertical" \| "horizontal" \| "both"` |  |
| `label` | `string` | Accessible name; the box is a focusable region so it scrolls from the keyboard. |
| `children?` | `ReactNode` |  |
| `className?` | `string` | Extra class on the root element. |
| `style?` | `CSSProperties` | Inline style on the root element. |

#### Avatar

| Prop | Type | Notes |
| --- | --- | --- |
| `name` | `string` | Required |
| `src?` | `string` |  |
| `size?` | `number` |  |
| `tint?` | `Tint \| "surface-sunken"` |  |
| `className?` | `string` | Extra class on the root element. |
| `style?` | `CSSProperties` | Inline style on the root element. |

#### Separator

| Prop | Type | Notes |
| --- | --- | --- |
| `orientation?` | `"horizontal" \| "vertical"` |  |
| `label?` | `string` | Text in the middle of the line ("or"). |
| `className?` | `string` | Extra class on the root element. |
| `style?` | `CSSProperties` | Inline style on the root element. |


## Toggle Group

> On/off buttons.

Component · Forms · Halo kit · [Live page](https://ui.twentyfirst.media/halo/components/ToggleGroup/)

On/off buttons. A **Toggle** is a single pressed state (star, pin, follow). A **ToggleGroup** joins
several: `type="single"` allows at most one, `type="multiple"` any number (text styles, filters).

- Pressed state is `aria-pressed`; icon-only toggles take their name from `label` (or the option's `hint`).
- ←/→, Home and End move between the toggles of a group.
- For choosing exactly one of a few views, `Segmented` is the closer fit.

### Example

```tsx
import * as React from "react";
import { Toggle, ToggleGroup } from "@twentyfirstmedia/halo";

export default function Preview() {
  const [marks, setMarks] = React.useState(["bold"]);
  return (
    <div className="tf-panel" style={{ gap: 20 }}>
      <div className="tf-row" style={{ gap: 12 }}>
        <ToggleGroup
          label="Text style"
          type="multiple"
          value={marks}
          onChange={setMarks}
          items={[
            { value: "bold", label: "", icon: "bold", hint: "Bold" },
            { value: "list", label: "", icon: "list", hint: "List" },
            { value: "quote", label: "", icon: "quote", hint: "Quote" },
          ]}
        />
        <ToggleGroup
          label="View"
          defaultValue={["week"]}
          items={["Day", "Week", "Month"].map((x) => ({ value: x.toLowerCase(), label: x }))}
        />
      </div>
      <div className="tf-row" style={{ gap: 8 }}>
        <Toggle icon="star" label="Starred" defaultPressed />
        <Toggle icon="pin" label="Pinned" />
        <Toggle icon="bell">Follow thread</Toggle>
        <Toggle size="sm" icon="eye" disabled>
          Watching
        </Toggle>
      </div>
    </div>
  );
}
```

### Props

#### ToggleGroup

| Prop | Type | Notes |
| --- | --- | --- |
| `items` | `(string \| Option)[]` | Required |
| `type?` | `"single" \| "multiple"` | `single`: at most one pressed; `multiple`: any number. |
| `value?` | `string[]` |  |
| `defaultValue?` | `string[]` |  |
| `onChange?` | `(value: string[]) => void` |  |
| `label` | `string` | Accessible name of the group. |
| `size?` | `"sm" \| "md"` |  |
| `block?` | `boolean` | Fills the width and shares it evenly; labels end in an ellipsis when space runs short. |
| `className?` | `string` | Extra class on the root element. |
| `style?` | `CSSProperties` | Inline style on the root element. |

#### Toggle

| Prop | Type | Notes |
| --- | --- | --- |
| `pressed?` | `boolean` |  |
| `defaultPressed?` | `boolean` |  |
| `onChange?` | `(pressed: boolean) => void` |  |
| `icon?` | `IconName` |  |
| `label?` | `string` | Accessible name; required when the toggle shows only an icon. |
| `size?` | `"sm" \| "md"` |  |
| `disabled?` | `boolean` |  |
| `children?` | `ReactNode` |  |
| `className?` | `string` | Extra class on the root element. |
| `style?` | `CSSProperties` | Inline style on the root element. |


## Hover Card

> A preview card that opens when the pointer rests on a trigger (a name, a link) or when it gets keyboard focus, and closes when the pointer or focus leaves or on Escape.

Component · Overlays · Halo kit · [Live page](https://ui.twentyfirst.media/halo/components/HoverCard/)

A preview card that opens when the pointer rests on a trigger (a name, a link) or when it gets keyboard
focus, and closes when the pointer or focus leaves or on Escape.

- Use it for supplementary details only; the trigger must still lead somewhere on its own.
- `openDelay` and `closeDelay` tune the timing; the card stays inside the screen on narrow layouts.

### Example

```tsx
import { Avatar, Badge, HoverCard } from "@twentyfirstmedia/halo";

export default function Preview() {
  return (
    <div className="tf-panel" style={{ gap: 16, paddingBottom: 180 }}>
      <p style={{ margin: 0 }}>
        Assigned to{" "}
        <HoverCard trigger={<a href="#">@mara</a>} side="bottom" align="start">
          <div className="tf-row" style={{ gap: 12, flexWrap: "nowrap", alignItems: "flex-start" }}>
            <Avatar name="Mara Ellis" size={40} />
            <div className="tf-col" style={{ gap: 4 }}>
              <b>Mara Ellis</b>
              <span className="tf-card-desc">Owner · Leadership · joined Mar 2024</span>
              <div className="tf-row" style={{ gap: 6 }}>
                <Badge tone="success">Online</Badge>
                <Badge>Berlin</Badge>
              </div>
            </div>
          </div>
        </HoverCard>{" "}
        by the pricing workflow. Hover or focus the name to see the card.
      </p>
    </div>
  );
}
```

### Props

#### HoverCard

| Prop | Type | Notes |
| --- | --- | --- |
| `trigger` | `ReactNode` | The element that opens the card on hover and keyboard focus. |
| `children?` | `ReactNode` |  |
| `side?` | `"top" \| "bottom"` |  |
| `align?` | `"start" \| "center" \| "end"` |  |
| `openDelay?` | `number` |  |
| `closeDelay?` | `number` |  |
| `width?` | `number` |  |
| `className?` | `string` | Extra class on the root element. |
| `style?` | `CSSProperties` | Inline style on the root element. |

#### Avatar

| Prop | Type | Notes |
| --- | --- | --- |
| `name` | `string` | Required |
| `src?` | `string` |  |
| `size?` | `number` |  |
| `tint?` | `Tint \| "surface-sunken"` |  |
| `className?` | `string` | Extra class on the root element. |
| `style?` | `CSSProperties` | Inline style on the root element. |

#### Badge

| Prop | Type | Notes |
| --- | --- | --- |
| `tone?` | `Tone` |  |
| `dot?` | `boolean` |  |
| `live?` | `boolean` |  |
| `children?` | `ReactNode` |  |
| `className?` | `string` | Extra class on the root element. |
| `style?` | `CSSProperties` | Inline style on the root element. |


## Carousel

> A row of slides with previous/next buttons and dots.

Component · Media · Halo kit · [Live page](https://ui.twentyfirst.media/halo/components/Carousel/)

A row of slides with previous/next buttons and dots. Swipe or scroll on touch, ←/→ on the keyboard.

- `perView` shows several slides on wide screens; phones always show one (with a peek of the next).
- `loop` wraps around at the ends.
- The carousel is a labelled region; each slide is announced as "n of total".

### Example

```tsx
import { Carousel, ProductArt } from "@twentyfirstmedia/halo";

const ITEMS = [
  ["tee", "sky", "Halo Cotton Tee", "€32"],
  ["mug", "butter", "Studio Mug", "€18"],
  ["bottle", "mint", "Field Bottle", "€28"],
  ["tote", "lilac", "Canvas Tote", "€24"],
  ["cap", "blush", "Trail Cap", "€22"],
] as const;

export default function Preview() {
  return (
    <div className="tf-col" style={{ gap: 32 }}>
      <Carousel
        label="Featured products"
        perView={3}
        slides={ITEMS.map(([k, t, name, price]) => (
          <div key={k} className="tf-card" style={{ minHeight: 0, gap: 8 }}>
            <ProductArt kind={k} tint={t} />
            <b>{name}</b>
            <span className="tf-card-desc">{price}</span>
          </div>
        ))}
      />
      <Carousel
        label="Onboarding"
        loop
        slides={["Invite your team", "Connect your mailbox", "Approve your first draft"].map(
          (t, i) => (
            <div
              key={t}
              className="tf-panel"
              style={{
                minHeight: 160,
                justifyContent: "center",
                alignItems: "center",
                textAlign: "center",
              }}
            >
              <span className="tf-card-desc">Step {i + 1} of 3</span>
              <b style={{ fontSize: 20 }}>{t}</b>
            </div>
          ),
        )}
      />
    </div>
  );
}
```

### Props

#### Carousel

| Prop | Type | Notes |
| --- | --- | --- |
| `slides` | `ReactNode[]` | Required |
| `label` | `string` | Accessible name of the carousel. |
| `perView?` | `number` | Slides visible at once on wide screens (1 on phones). |
| `loop?` | `boolean` | Next on the last slide goes back to the first. |
| `dots?` | `boolean` | Dots under the slides. |
| `index?` | `number` |  |
| `defaultIndex?` | `number` |  |
| `onChange?` | `(index: number) => void` |  |
| `className?` | `string` | Extra class on the root element. |
| `style?` | `CSSProperties` | Inline style on the root element. |

#### ProductArt

| Prop | Type | Notes |
| --- | --- | --- |
| `kind` | `ArtKind` | Required |
| `tint?` | `Tint \| "plain"` |  |
| `size?` | `number` |  |
| `label?` | `string` |  |
| `className?` | `string` | Extra class on the root element. |
| `style?` | `CSSProperties` | Inline style on the root element. |


## Ambient

> A calm, living background for glass UI: soft colour fields from the kit (pastels in Halo, a faint aurora in Pro) that drift slowly, a photo or video under a scrim, or your own layer.

Component · Navigation · Halo kit · [Live page](https://ui.twentyfirst.media/halo/components/Ambient/)

A calm, living background for glass UI: soft colour fields from the kit (pastels in Halo, a faint aurora in Pro) that drift slowly, a photo or video under a scrim, or your own layer.

- Put it first inside a container: it fills the container (or the window with `fixed`) and sits behind the content.
- With `<UIProvider surface="glass">` around it, panels, cards, tiles, the app shell and floating layers turn into glass over it; text keeps 4.5:1 over any backdrop.
- The fields drift only with `transform`, stop with motion off or reduced motion and pause off screen. `animate={false}` keeps them still.
- `colors` takes any CSS colours (brand colours, `var(--chart-1)`); by default the kit's `--ambient-1…4`, themable like every token.
- `src` shows a photo, `src` with `video` a muted looping video; children replace both with your own layer (canvas, WebGL, a map).

### Example

```tsx
import * as React from "react";
import { Ambient, Badge, Button, Panel, StatTile, UIProvider } from "@twentyfirstmedia/halo";

export default function Preview() {
  return (
    <UIProvider scope="subtree" surface="glass">
      <div
        style={{
          display: "grid",
          gridTemplateColumns: "repeat(auto-fit, minmax(min(100%, 240px), 1fr))",
          gap: 16,
          padding: 24,
          borderRadius: "var(--radius-xl)",
          overflow: "hidden",
        }}
      >
        <Ambient />
        <StatTile value="7h 42m" label="Sleep" tint="sky" delta="+18 min" />
        <StatTile value="12 days" label="Streak" tint="butter" />
        <Panel
          title="Breathe"
          subtitle="Four minutes, box breathing"
          action={<Badge tone="success">New</Badge>}
        >
          <Button variant="primary" icon="play">
            Start
          </Button>
        </Panel>
      </div>
    </UIProvider>
  );
}
```

### Props

#### Ambient

| Prop | Type | Notes |
| --- | --- | --- |
| `colors?` | `string[]` | Colours of the soft fields (any CSS colour); default the kit's `--ambient-1…4`. |
| `src?` | `string` | A photo (or, with `video`, a video) instead of the fields, under a scrim that keeps it calm. |
| `video?` | `boolean` | Treat `src` as a video (muted, looping, still with motion off). |
| `animate?` | `boolean` | Let the fields drift slowly (default true). Still with motion off; paused off screen. |
| `fixed?` | `boolean` | Cover the window behind the page instead of the nearest container. |
| `children?` | `ReactNode` | Your own layer (a canvas, WebGL, a map) instead of fields or media. |
| `className?` | `string` | Extra class on the root element. |
| `style?` | `CSSProperties` | Inline style on the root element. |

#### Badge

| Prop | Type | Notes |
| --- | --- | --- |
| `tone?` | `Tone` |  |
| `dot?` | `boolean` |  |
| `live?` | `boolean` |  |
| `children?` | `ReactNode` |  |
| `className?` | `string` | Extra class on the root element. |
| `style?` | `CSSProperties` | Inline style on the root element. |

#### Button

| Prop | Type | Notes |
| --- | --- | --- |
| `variant?` | `"primary" \| "secondary" \| "soft" \| "ghost" \| "danger" \| "danger-solid"` |  |
| `size?` | `"md" \| "sm"` |  |
| `icon?` | `IconName` |  |
| `iconRight?` | `IconName` |  |
| `disabled?` | `boolean` |  |
| `type?` | `"button" \| "submit" \| "reset"` |  |
| `onClick?` | `(e: MouseEvent<HTMLButtonElement>) => void` |  |
| `children?` | `ReactNode` |  |
| `asChild?` | `boolean` | Render the single child element (a link, a router Link) with the button's look instead of a <button>. |
| `id?` | `string` |  |
| `name?` | `string` | Form field name and value, sent with the form when this button submits it. |
| `value?` | `string` |  |
| `form?` | `string` | The id of the form this button belongs to, when it sits outside it. |
| `title?` | `string` |  |
| `tabIndex?` | `number` |  |
| `autoFocus?` | `boolean` |  |
| `aria-label?` | `string` |  |
| `aria-labelledby?` | `string` |  |
| `aria-describedby?` | `string` |  |
| `aria-expanded?` | `boolean \| "true" \| "false"` | For disclosure and menu triggers: whether what the button controls is open. |
| `aria-controls?` | `string` |  |
| `aria-haspopup?` | `boolean \| "true" \| "false" \| "menu" \| "listbox" \| "tree" \| "grid" \| "dialog"` |  |
| `aria-pressed?` | `boolean \| "true" \| "false" \| "mixed"` | For toggle buttons. |
| `aria-current?` | `boolean \| "true" \| "false" \| "page" \| "step" \| "location" \| "date" \| "time"` |  |
| `className?` | `string` | Extra class on the root element. |
| `style?` | `CSSProperties` | Inline style on the root element. |

#### Panel

| Prop | Type | Notes |
| --- | --- | --- |
| `side?` | `boolean` |  |
| `title?` | `string` |  |
| `subtitle?` | `string` |  |
| `action?` | `ReactNode` |  |
| `children?` | `ReactNode` |  |
| `surface?` | `Surface` | `"glass"`: translucent glass over what is behind (maps, 3D, video, photos); `"solid"` opts out inside a glass `UIProvider`. |
| `className?` | `string` | Extra class on the root element. |
| `style?` | `CSSProperties` | Inline style on the root element. |

#### StatTile

| Prop | Type | Notes |
| --- | --- | --- |
| `value` | `ReactNode` | Required |
| `label` | `string` | Required |
| `tint?` | `Tint \| "surface" \| "placeholder"` |  |
| `delta?` | `string` |  |
| `delay?` | `number` |  |
| `className?` | `string` | Extra class on the root element. |
| `style?` | `CSSProperties` | Inline style on the root element. |


## Menubar

> A desktop-style row of menus (File, Edit, View).

Component · Navigation · Halo kit · [Live page](https://ui.twentyfirst.media/halo/components/Menubar/)

A desktop-style row of menus (File, Edit, View). Each menu is a regular `Menu`, so items can have
icons, shortcuts, checkbox and radio states and submenus.

- Keyboard: ←/→ move between menus (and switch the open one), ↓/Enter/Space open, ↑/↓ move inside,
  → and ← open and close submenus, Escape closes and returns to the bar.
- Moving the pointer across the bar switches menus once one is open.

### Example

```tsx
import { Menubar } from "@twentyfirstmedia/halo";

export default function Preview() {
  return (
    <div style={{ minHeight: 260 }}>
      <Menubar
        label="Editor"
        menus={[
          {
            label: "File",
            items: [
              { label: "New page", icon: "file", shortcut: "⌘N" },
              { label: "Open…", icon: "folder", shortcut: "⌘O" },
              {
                label: "Export",
                icon: "download",
                items: [{ label: "PDF" }, { label: "Markdown" }, { label: "HTML" }],
              },
              "-",
              { label: "Close", shortcut: "⌘W" },
            ],
          },
          {
            label: "Edit",
            items: [
              { label: "Undo", icon: "undo", shortcut: "⌘Z" },
              { label: "Redo", icon: "redo", shortcut: "⇧⌘Z" },
              "-",
              { label: "Find…", icon: "search", shortcut: "⌘F" },
            ],
          },
          {
            label: "View",
            items: [
              { label: "Show sidebar", type: "checkbox", checked: true },
              { label: "Show comments", type: "checkbox" },
              "-",
              { label: "Zoom in", shortcut: "⌘+" },
              { label: "Zoom out", shortcut: "⌘−" },
            ],
          },
          {
            label: "Help",
            items: [{ label: "Keyboard shortcuts", shortcut: "?" }, { label: "What's new" }],
          },
        ]}
      />
    </div>
  );
}
```

### Props

#### Menubar

| Prop | Type | Notes |
| --- | --- | --- |
| `menus` | `MenubarMenu[]` | Required |
| `label?` | `string` | Accessible name of the bar. |
| `className?` | `string` | Extra class on the root element. |
| `style?` | `CSSProperties` | Inline style on the root element. |

#### Menu

| Prop | Type | Notes |
| --- | --- | --- |
| `items` | `(MenuItem \| "-")[]` | Required |
| `label?` | `string` | Accessible name of the menu. |
| `autoFocus?` | `boolean` | Focus the first item on mount (menus opened from a button or the keyboard). |
| `onClose?` | `() => void` | Called after an item runs, and on Escape, so the owner can close the menu. |
| `className?` | `string` | Extra class on the root element. |
| `style?` | `CSSProperties` | Inline style on the root element. |


## Navigation Menu

> Site navigation for marketing pages: plain links and items that open a panel of links with icons and descriptions, optionally with a highlighted card.

Component · Navigation · Halo kit · [Live page](https://ui.twentyfirst.media/halo/components/NavigationMenu/)

Site navigation for marketing pages: plain links and items that open a panel of links with icons
and descriptions, optionally with a highlighted card.

- Panels open on hover and on click; Escape closes the panel and returns focus to its trigger.
- Use `TopBar` for app navigation inside the product and this for public pages.

### Example

```tsx
import { Button, NavigationMenu } from "@twentyfirstmedia/halo";

export default function Preview() {
  return (
    <div className="tf-panel" style={{ gap: 16, minHeight: 320 }}>
      <div className="tf-row" style={{ justifyContent: "space-between", gap: 16 }}>
        <NavigationMenu
          label="Site"
          items={[
            {
              label: "Product",
              feature: (
                <>
                  <b>Halo Workspace</b>
                  <span className="tf-card-desc">
                    One place for approvals, billing and the team.
                  </span>
                </>
              ),
              links: [
                { label: "Approvals", icon: "check", description: "Agents ask, people decide." },
                { label: "Billing", icon: "card", description: "Invoices, plans and payouts." },
                { label: "Analytics", icon: "chart", description: "Growth week over week." },
              ],
            },
            {
              label: "Resources",
              links: [
                { label: "Docs", icon: "book", description: "Guides and API reference." },
                { label: "Changelog", icon: "file", description: "What shipped this month." },
              ],
            },
            { label: "Pricing", href: "#" },
          ]}
        />
        <Button asChild size="sm">
          <a href="#">Get started</a>
        </Button>
      </div>
    </div>
  );
}
```

### Props

#### NavigationMenu

| Prop | Type | Notes |
| --- | --- | --- |
| `items` | `NavigationMenuItem[]` | Required |
| `label?` | `string` | Accessible name of the navigation. |
| `className?` | `string` | Extra class on the root element. |
| `style?` | `CSSProperties` | Inline style on the root element. |

#### Button

| Prop | Type | Notes |
| --- | --- | --- |
| `variant?` | `"primary" \| "secondary" \| "soft" \| "ghost" \| "danger" \| "danger-solid"` |  |
| `size?` | `"md" \| "sm"` |  |
| `icon?` | `IconName` |  |
| `iconRight?` | `IconName` |  |
| `disabled?` | `boolean` |  |
| `type?` | `"button" \| "submit" \| "reset"` |  |
| `onClick?` | `(e: MouseEvent<HTMLButtonElement>) => void` |  |
| `children?` | `ReactNode` |  |
| `asChild?` | `boolean` | Render the single child element (a link, a router Link) with the button's look instead of a <button>. |
| `id?` | `string` |  |
| `name?` | `string` | Form field name and value, sent with the form when this button submits it. |
| `value?` | `string` |  |
| `form?` | `string` | The id of the form this button belongs to, when it sits outside it. |
| `title?` | `string` |  |
| `tabIndex?` | `number` |  |
| `autoFocus?` | `boolean` |  |
| `aria-label?` | `string` |  |
| `aria-labelledby?` | `string` |  |
| `aria-describedby?` | `string` |  |
| `aria-expanded?` | `boolean \| "true" \| "false"` | For disclosure and menu triggers: whether what the button controls is open. |
| `aria-controls?` | `string` |  |
| `aria-haspopup?` | `boolean \| "true" \| "false" \| "menu" \| "listbox" \| "tree" \| "grid" \| "dialog"` |  |
| `aria-pressed?` | `boolean \| "true" \| "false" \| "mixed"` | For toggle buttons. |
| `aria-current?` | `boolean \| "true" \| "false" \| "page" \| "step" \| "location" \| "date" \| "time"` |  |
| `className?` | `string` | Extra class on the root element. |
| `style?` | `CSSProperties` | Inline style on the root element. |


## Tabs

> A tab bar that switches views.

Component · Navigation · Halo kit · [Live page](https://ui.twentyfirst.media/halo/components/Tabs/)

A tab bar that switches views. With `panels` it renders the panels too, wired with the tab,
tablist and tabpanel roles; without, it is a bar you connect to your own content.

- Keyboard: ←/→ move between tabs and select them, Home/End jump; only the selected tab is in the
  tab order.
- `block` stretches the tabs to the full width.

### Example

```tsx
import { KeyValue, Panel, Tabs } from "@twentyfirstmedia/halo";

export default function Preview() {
  return (
    <Panel title="Northwind">
      <Tabs
        label="Customer"
        items={["Overview", "Invoices", "Notes"]}
        panels={{
          Overview: (
            <KeyValue
              items={[
                { k: "Plan", v: "Team · 24 seats" },
                { k: "MRR", v: "€1,240" },
                { k: "Renews", v: "May 1, 2026" },
              ]}
            />
          ),
          Invoices: <p className="tf-card-desc">Three invoices this year, all paid.</p>,
          Notes: <p className="tf-card-desc">Wants 40 more seats before the renewal.</p>,
        }}
      />
    </Panel>
  );
}
```

### Props

#### Tabs

| Prop | Type | Notes |
| --- | --- | --- |
| `items` | `string[]` | Required |
| `value?` | `string` |  |
| `defaultValue?` | `string` |  |
| `onChange?` | `(v: string) => void` |  |
| `block?` | `boolean` |  |
| `panels?` | `Record<string, ReactNode>` | Content per tab; renders the tab panels under the bar, wired with tab/tabpanel roles. |
| `label?` | `string` | Accessible name of the tab list. |
| `className?` | `string` | Extra class on the root element. |
| `style?` | `CSSProperties` | Inline style on the root element. |

#### Panel

| Prop | Type | Notes |
| --- | --- | --- |
| `side?` | `boolean` |  |
| `title?` | `string` |  |
| `subtitle?` | `string` |  |
| `action?` | `ReactNode` |  |
| `children?` | `ReactNode` |  |
| `surface?` | `Surface` | `"glass"`: translucent glass over what is behind (maps, 3D, video, photos); `"solid"` opts out inside a glass `UIProvider`. |
| `className?` | `string` | Extra class on the root element. |
| `style?` | `CSSProperties` | Inline style on the root element. |

#### KeyValue

| Prop | Type | Notes |
| --- | --- | --- |
| `items` | `KeyValueItem[]` | Required |
| `dense?` | `boolean` |  |
| `className?` | `string` | Extra class on the root element. |
| `style?` | `CSSProperties` | Inline style on the root element. |


## Sidebar

> App navigation down the side: groups with headings, counts and badges, one level of nested pages, links, item menus and a collapsed mode with icons only.

Component · Navigation · Halo kit · [Live page](https://ui.twentyfirst.media/halo/components/Sidebar/)

App navigation down the side: groups with headings, counts and badges, one level of nested pages,
links, item menus and a collapsed mode with icons only.

- Three looks: `variant="floating"` (default, a card with a gap to the edge), `"attached"` (flush
  with the left edge, full height, a hairline to the content) and `"shell"` (on the dark frame;
  `AppShell navigation="sidebar"` uses it).
- Items with `href` render as links; pass your router's link as `linkAs` (Next.js `Link`, React
  Router `Link`). `external` opens in a new tab and says so to screen readers.
- Extras per item: `count`, `badge` (`"dot"` for new activity or a short word like `"New"`),
  `disabled`, `actions` (a "…" menu on hover and focus) and `items` for nested pages. Groups take
  `collapsible`, `defaultOpen` and an `action` such as "New project".
- Collapsed, every label is a tooltip; a parent opens a flyout with its pages on hover, click or
  →. Pass `storageKey` to remember the state and `shortcut` for ⌘B / Ctrl+B.
- `header` and `footer` take nodes or a function of `{ collapsed }`, e.g. a `WorkspaceSwitcher`
  and a `UserMenu` that turn compact.
- On phones (≤ 760px) the sidebar becomes an off-canvas drawer behind a menu button: Escape and the
  scrim close it, focus stays inside and returns to the button. Control it with `mobileOpen` and
  `onMobileOpenChange`.
- For filters, use `as="aside"`: items with `checked` become checkbox (or, with the group's
  `select: "single"`, radio) options with counts, and a group's `content` holds sliders or date
  fields. See the Filter Sidebar pattern.

### Example

```tsx
import * as React from "react";
import { Sidebar, UserMenu, WorkspaceSwitcher } from "@twentyfirstmedia/halo";
import type { MenuItem, SidebarGroup } from "@twentyfirstmedia/halo";

const itemMenu: (MenuItem | "-")[] = [
  { label: "Rename", icon: "edit" },
  { label: "Share", icon: "share" },
  "-",
  { label: "Archive", icon: "archive", danger: true },
];

const groups: SidebarGroup[] = [
  {
    items: [
      { id: "home", label: "Home", icon: "home" },
      { id: "inbox", label: "Inbox", icon: "mail", count: 4 },
      { id: "activity", label: "Activity", icon: "bell", badge: "dot" },
    ],
  },
  {
    label: "Projects",
    action: { label: "New project", icon: "plus" },
    items: [
      { id: "launch", label: "Spring launch", icon: "sparkle", actions: itemMenu },
      { id: "pricing", label: "Pricing page", icon: "tag", badge: "New", actions: itemMenu },
    ],
  },
  {
    label: "Finance",
    collapsible: true,
    items: [
      {
        id: "billing",
        label: "Billing",
        icon: "card",
        items: [
          { id: "invoices", label: "Invoices", icon: "file" },
          { id: "payouts", label: "Payouts", icon: "download" },
        ],
      },
      { id: "reports", label: "Reports", icon: "chart" },
    ],
  },
  {
    label: "Help",
    collapsible: true,
    items: [
      { id: "docs", label: "Docs", icon: "book", href: "#docs", external: true },
      { id: "api", label: "API access", icon: "code", disabled: true },
    ],
  },
];

const workspaces = [
  { id: "halo", name: "Halo Studio", sub: "Pro plan", tint: "lilac" as const },
  { id: "north", name: "Northwind", sub: "Team plan", tint: "mint" as const },
];

const account: (MenuItem | "-")[] = [
  { label: "Profile", icon: "user" },
  { label: "Settings", icon: "settings" },
  "-",
  { label: "Sign out", icon: "logout" },
];

export default function Preview() {
  const [page, setPage] = React.useState("launch");
  const [ws, setWs] = React.useState("halo");
  const parts = {
    groups,
    current: page,
    onPick: setPage,
    header: ({ collapsed }: { collapsed: boolean }) => (
      <WorkspaceSwitcher items={workspaces} value={ws} onChange={setWs} compact={collapsed} />
    ),
    footer: ({ collapsed }: { collapsed: boolean }) => (
      <UserMenu name="Mara Ellis" email="mara@halo.app" items={account} compact={collapsed} />
    ),
  };
  return (
    <div className="tf-row" style={{ gap: 24, alignItems: "stretch", flexWrap: "wrap" }}>
      <div style={{ height: 600, display: "flex" }}>
        <Sidebar label="Workspace" shortcut {...parts} />
      </div>
      <div style={{ height: 600, display: "flex" }}>
        <Sidebar label="Workspace (collapsed)" defaultCollapsed {...parts} />
      </div>
    </div>
  );
}
```

### Props

#### Sidebar

| Prop | Type | Notes |
| --- | --- | --- |
| `groups` | `SidebarGroup[]` | Required |
| `current?` | `string` | Id (or label) of the current page. |
| `onPick?` | `(id: string) => void` |  |
| `variant?` | `"floating" \| "attached" \| "shell"` | `floating` (default): a card with rounded corners and a shadow. `attached`: full height, flush with the edge of the screen, divided by a line. `shell`: on the dark frame of `AppShell`. |
| `collapsed?` | `boolean` | Icons only. |
| `defaultCollapsed?` | `boolean` |  |
| `onCollapsedChange?` | `(collapsed: boolean) => void` |  |
| `storageKey?` | `string` | Remember the collapsed state in the browser under this key. |
| `shortcut?` | `boolean` | ⌘B (Ctrl+B) collapses and expands the sidebar, except while typing in a field. |
| `linkAs?` | `ElementType` | The element items with an `href` render as (default `a`), e.g. Next.js `Link`. |
| `mobileOpen?` | `boolean` | On phones (up to 760px wide): whether the drawer is open (controlled). |
| `onMobileOpenChange?` | `(open: boolean) => void` |  |
| `header?` | `ReactNode \| ((state: { collapsed: boolean }) => ReactNode)` | Top of the sidebar (brand, `WorkspaceSwitcher`); a function gets the collapsed state. |
| `footer?` | `ReactNode \| ((state: { collapsed: boolean }) => ReactNode)` | Bottom of the sidebar (`UserMenu`, settings); a function gets the collapsed state. |
| `as?` | `"nav" \| "aside"` | `nav` (default) for app navigation. `aside` for filters, settings or other tools beside the content: a complementary region instead of a navigation landmark. |
| `collapsible?` | `boolean` | Offers the collapse button and the icons-only mode (default true; filters usually set false). |
| `label?` | `string` | Accessible name of the navigation (or the aside). |
| `className?` | `string` | Extra class on the root element. |
| `style?` | `CSSProperties` | Inline style on the root element. |

#### UserMenu

| Prop | Type | Notes |
| --- | --- | --- |
| `name` | `string` | Required |
| `email?` | `string` |  |
| `avatar?` | `string` | Picture URL; initials otherwise. |
| `items?` | `(MenuItem \| "-")[]` | The menu: profile, settings, sign out … |
| `compact?` | `boolean` | Only the avatar (a collapsed sidebar). |
| `side?` | `"top" \| "bottom"` | Where the menu opens (default `top`, for the foot of a sidebar). |
| `className?` | `string` | Extra class on the root element. |
| `style?` | `CSSProperties` | Inline style on the root element. |

#### WorkspaceSwitcher

| Prop | Type | Notes |
| --- | --- | --- |
| `items` | `{ id: string; name: string; sub?: string; tint?: Tint; logo?: ReactNode }[]` | Required |
| `value?` | `string` |  |
| `onChange?` | `(id: string) => void` |  |
| `label?` | `string` |  |
| `footer?` | `ReactNode` |  |
| `variant?` | `"frame"` |  |
| `width?` | `number` |  |
| `compact?` | `boolean` | Only the workspace's mark, its name as the accessible name (a collapsed sidebar). |
| `className?` | `string` | Extra class on the root element. |
| `style?` | `CSSProperties` | Inline style on the root element. |

#### Menu

| Prop | Type | Notes |
| --- | --- | --- |
| `items` | `(MenuItem \| "-")[]` | Required |
| `label?` | `string` | Accessible name of the menu. |
| `autoFocus?` | `boolean` | Focus the first item on mount (menus opened from a button or the keyboard). |
| `onClose?` | `() => void` | Called after an item runs, and on Escape, so the owner can close the menu. |
| `className?` | `string` | Extra class on the root element. |
| `style?` | `CSSProperties` | Inline style on the root element. |


## User Menu

> The signed-in account at the foot of a sidebar: avatar, name and email, opening a menu with profile, settings and sign-out.

Component · Navigation · Halo kit · [Live page](https://ui.twentyfirst.media/halo/components/UserMenu/)

The signed-in account at the foot of a sidebar: avatar, name and email, opening a menu with
profile, settings and sign-out.

- `items` are `Menu` items (icons, shortcuts, `"-"` separators, `danger`).
- `compact` shows only the avatar, with the name as its accessible label; use it in a collapsed
  sidebar (`footer={({ collapsed }) => <UserMenu compact={collapsed} … />}`).
- The menu opens above the trigger by default (`side="top"`); use `side="bottom"` at the top of a
  page.

### Example

```tsx
import { Card, UserMenu } from "@twentyfirstmedia/halo";

export default function Preview() {
  return (
    <div className="tf-row" style={{ gap: 24, alignItems: "flex-start", flexWrap: "wrap" }}>
      <Card style={{ width: 280, minHeight: 0 }}>
        <UserMenu
          name="Mara Ellis"
          email="mara@halo.app"
          side="bottom"
          items={[
            { label: "Profile", icon: "user" },
            { label: "Settings", icon: "settings" },
            { label: "Keyboard shortcuts", icon: "terminal", shortcut: "?" },
            "-",
            { label: "Sign out", icon: "logout" },
          ]}
        />
      </Card>
      <Card style={{ minHeight: 0 }}>
        <UserMenu
          name="Jonah Petit"
          compact
          side="bottom"
          items={[{ label: "Profile", icon: "user" }, "-", { label: "Sign out", icon: "logout" }]}
        />
      </Card>
    </div>
  );
}
```

### Props

#### UserMenu

| Prop | Type | Notes |
| --- | --- | --- |
| `name` | `string` | Required |
| `email?` | `string` |  |
| `avatar?` | `string` | Picture URL; initials otherwise. |
| `items?` | `(MenuItem \| "-")[]` | The menu: profile, settings, sign out … |
| `compact?` | `boolean` | Only the avatar (a collapsed sidebar). |
| `side?` | `"top" \| "bottom"` | Where the menu opens (default `top`, for the foot of a sidebar). |
| `className?` | `string` | Extra class on the root element. |
| `style?` | `CSSProperties` | Inline style on the root element. |

#### Card

| Prop | Type | Notes |
| --- | --- | --- |
| `title?` | `string` |  |
| `description?` | `string` |  |
| `meta?` | `string[]` |  |
| `corner?` | `ReactNode` |  |
| `status?` | `ReactNode` |  |
| `actions?` | `ReactNode[]` |  |
| `tint?` | `Tint \| "surface"` |  |
| `onClick?` | `() => void` |  |
| `children?` | `ReactNode` |  |
| `eyebrow?` | `ReactNode` |  |
| `surface?` | `Surface` | `"glass"`: translucent glass over what is behind (maps, 3D, video, photos); `"solid"` opts out inside a glass `UIProvider`. |
| `className?` | `string` | Extra class on the root element. |
| `style?` | `CSSProperties` | Inline style on the root element. |

#### Menu

| Prop | Type | Notes |
| --- | --- | --- |
| `items` | `(MenuItem \| "-")[]` | Required |
| `label?` | `string` | Accessible name of the menu. |
| `autoFocus?` | `boolean` | Focus the first item on mount (menus opened from a button or the keyboard). |
| `onClose?` | `() => void` | Called after an item runs, and on Escape, so the owner can close the menu. |
| `className?` | `string` | Extra class on the root element. |
| `style?` | `CSSProperties` | Inline style on the root element. |

#### Avatar

| Prop | Type | Notes |
| --- | --- | --- |
| `name` | `string` | Required |
| `src?` | `string` |  |
| `size?` | `number` |  |
| `tint?` | `Tint \| "surface-sunken"` |  |
| `className?` | `string` | Extra class on the root element. |
| `style?` | `CSSProperties` | Inline style on the root element. |


## Floating Layout

> UI floating over a full-bleed background: a map, a 3D scene, a video or a photo.

Component · Navigation · Halo kit · [Live page](https://ui.twentyfirst.media/halo/components/FloatingLayout/)

UI floating over a full-bleed background: a map, a 3D scene, a video or a photo. Four slots sit along the edges (`top`, `start`, `end`, `bottom`) and everything in them is glass by default, translucent and blurred over what is behind.

- The background stays interactive wherever no slot sits on it: drag the map, click a pin.
- `controls` (zoom, compass, locate) and `attribution` (the map's source notes) sit in the free corner above the bottom bar, clear of the panels and the dock.
- `startWidth` and `endWidth` size the side columns (320px and 340px by default).
- The layout publishes `--floating-safe-top`, `-start`, `-end` and `-bottom` (px): how far its slots reach in. Use them to keep a map library's own controls clear, e.g. `.maplibregl-ctrl-bottom-right { right: var(--floating-safe-end); bottom: var(--floating-safe-bottom) }`.
- Below 720px of width the slots stack (top, start, the background, bottom) and the layout grows with them; the `end` slot becomes a bottom sheet over the background whose handle expands and collapses it (`endSheet={false}` stacks it instead).
- `surface="solid"` turns the glass off; `surface="solid"` on a single Panel or Card opts just that one out.
- Panels, cards, the dock, map legends and controls, and loose controls (search field, chips, icon buttons, segmented controls) turn into glass inside it; menus, popovers and dialogs take the stronger glass fill.
- Text on glass keeps 4.5:1 over any backdrop. Reduced transparency, more contrast and forced colours fall back to solid surfaces.

### Example

```tsx
import * as React from "react";
import {
  Badge,
  FloatingLayout,
  IconButton,
  KeyValue,
  MapView,
  Panel,
  SearchField,
  Segmented,
} from "@twentyfirstmedia/halo";
import type { MapPoint } from "@twentyfirstmedia/halo";

const hubs: MapPoint[] = [
  { id: "ham", label: "Hamburg", lat: 53.5, lng: 10, value: 840, sub: "840 parcels today" },
  { id: "rot", label: "Rotterdam", lat: 51.9, lng: 4.5, value: 610, tint: "mint" },
  { id: "nyc", label: "New York", lat: 40.7, lng: -74, value: 380, tint: "butter" },
  { id: "dxb", label: "Dubai", lat: 25.2, lng: 55.3, value: 290, tint: "lilac", pulse: true },
  { id: "sgp", label: "Singapore", lat: 1.3, lng: 103.8, value: 450, tint: "blush" },
];

export default function Preview() {
  const [view, setView] = React.useState("Today");
  return (
    <FloatingLayout
      label="Shipments"
      height={520}
      background={<MapView label="Shipments by hub" bubbles points={hubs} height="100%" />}
      controls={
        <div className="tf-col" style={{ gap: 8 }}>
          <IconButton icon="plus" label="Zoom in" variant="outline" />
          <IconButton icon="minus" label="Zoom out" variant="outline" />
        </div>
      }
      attribution="© OpenStreetMap contributors"
      top={
        <>
          <SearchField placeholder="Search hubs" style={{ flex: "1 1 220px", maxWidth: 360 }} />
          <IconButton icon="filter" label="Filters" variant="outline" />
        </>
      }
      end={
        <Panel
          title="Hamburg"
          subtitle="Hub"
          action={
            <Badge tone="success" dot>
              On time
            </Badge>
          }
        >
          <KeyValue
            items={[
              ["Parcels", "840"],
              ["Delayed", "12"],
              ["Next truck", "14:20"],
            ]}
          />
        </Panel>
      }
      bottom={
        <Segmented
          label="Period"
          options={["Today", "Week", "Month"]}
          value={view}
          onChange={setView}
        />
      }
    />
  );
}
```

### Props

#### Badge

| Prop | Type | Notes |
| --- | --- | --- |
| `tone?` | `Tone` |  |
| `dot?` | `boolean` |  |
| `live?` | `boolean` |  |
| `children?` | `ReactNode` |  |
| `className?` | `string` | Extra class on the root element. |
| `style?` | `CSSProperties` | Inline style on the root element. |

#### FloatingLayout

| Prop | Type | Notes |
| --- | --- | --- |
| `background?` | `ReactNode` | What the UI floats over, filling the layout: a map, a 3D canvas, a video, a photo. |
| `top?` | `ReactNode` | Bar along the top edge (search, filters, title). |
| `start?` | `ReactNode` | Column on the start side (layers, lists, settings). |
| `end?` | `ReactNode` | Column on the end side (details of the selected thing). |
| `bottom?` | `ReactNode` | Bar along the bottom edge (dock, playback, a summary). |
| `controls?` | `ReactNode` | Controls of the background (zoom, compass, locate) in the free corner above the bottom bar. |
| `attribution?` | `ReactNode` | Source notes of the background (map attribution), under `controls`, clear of every slot. |
| `startWidth?` | `number \| string` | Width of the start column (default 320px) and of the end column (default 340px). |
| `endWidth?` | `number \| string` |  |
| `endSheet?` | `boolean` | Below 720px of width the end slot becomes a bottom sheet over the background, with a handle that expands and collapses it (default true). `false` stacks it with the others. |
| `height?` | `number \| string` | Height of the layout (default 640). Below 720px of width the slots stack: top, start, end, bottom. The layout sets `--floating-safe-top/-start/-end/-bottom` (px) to the space its slots take, so map libraries can keep their own controls clear of them. |
| `surface?` | `Surface` | Glass for every surface in the slots (default) or solid surfaces. |
| `label?` | `string` | Accessible name of the region. |
| `children?` | `ReactNode` |  |
| `className?` | `string` | Extra class on the root element. |
| `style?` | `CSSProperties` | Inline style on the root element. |

#### IconButton

| Prop | Type | Notes |
| --- | --- | --- |
| `icon` | `IconName` | Required |
| `label` | `string` | Accessible name and tooltip (`aria-label` and `title`); `aria-label` or `title` override them. |
| `variant?` | `"soft" \| "solid" \| "outline" \| "ghost"` |  |
| `size?` | `"sm" \| "md" \| "lg"` |  |
| `type?` | `"button" \| "submit" \| "reset"` |  |
| `onClick?` | `(e: MouseEvent<HTMLButtonElement>) => void` |  |
| `disabled?` | `boolean` |  |
| `asChild?` | `boolean` | Render the single child element (a link) with the button's look; the icon is placed inside it. |
| `children?` | `ReactNode` |  |
| `id?` | `string` |  |
| `name?` | `string` | Form field name and value, sent with the form when this button submits it. |
| `value?` | `string` |  |
| `form?` | `string` | The id of the form this button belongs to, when it sits outside it. |
| `title?` | `string` |  |
| `tabIndex?` | `number` |  |
| `autoFocus?` | `boolean` |  |
| `aria-label?` | `string` |  |
| `aria-labelledby?` | `string` |  |
| `aria-describedby?` | `string` |  |
| `aria-expanded?` | `boolean \| "true" \| "false"` | For disclosure and menu triggers: whether what the button controls is open. |
| `aria-controls?` | `string` |  |
| `aria-haspopup?` | `boolean \| "true" \| "false" \| "menu" \| "listbox" \| "tree" \| "grid" \| "dialog"` |  |
| `aria-pressed?` | `boolean \| "true" \| "false" \| "mixed"` | For toggle buttons. |
| `aria-current?` | `boolean \| "true" \| "false" \| "page" \| "step" \| "location" \| "date" \| "time"` |  |
| `className?` | `string` | Extra class on the root element. |
| `style?` | `CSSProperties` | Inline style on the root element. |

#### KeyValue

| Prop | Type | Notes |
| --- | --- | --- |
| `items` | `KeyValueItem[]` | Required |
| `dense?` | `boolean` |  |
| `className?` | `string` | Extra class on the root element. |
| `style?` | `CSSProperties` | Inline style on the root element. |

#### MapView

| Prop | Type | Notes |
| --- | --- | --- |
| `points?` | `MapPoint[]` |  |
| `bounds?` | `{ n: number; s: number; w: number; e: number }` |  |
| `background?` | `ReactNode` |  |
| `bubbles?` | `boolean` |  |
| `selected?` | `MapPoint["id"] \| null` |  |
| `onSelect?` | `(id: MapPoint["id"] \| null) => void` |  |
| `renderPopup?` | `(p: MapPoint) => ReactNode` |  |
| `legend?` | `ReactNode` |  |
| `controls?` | `ReactNode` |  |
| `height?` | `number \| string` | Height in px (default 320) or any CSS length, e.g. "100%" to fill a FloatingLayout. |
| `label?` | `string` |  |
| `surface?` | `Surface` | `"glass"`: the legend, controls and popup float as glass over the map (for a live map in `background`). |
| `className?` | `string` |  |
| `style?` | `CSSProperties` | Inline style on the root element. |

#### Panel

| Prop | Type | Notes |
| --- | --- | --- |
| `side?` | `boolean` |  |
| `title?` | `string` |  |
| `subtitle?` | `string` |  |
| `action?` | `ReactNode` |  |
| `children?` | `ReactNode` |  |
| `surface?` | `Surface` | `"glass"`: translucent glass over what is behind (maps, 3D, video, photos); `"solid"` opts out inside a glass `UIProvider`. |
| `className?` | `string` | Extra class on the root element. |
| `style?` | `CSSProperties` | Inline style on the root element. |

#### SearchField

| Prop | Type | Notes |
| --- | --- | --- |
| `placeholder?` | `string` |  |
| `label?` | `string` | Accessible name (default: the placeholder, or "Search"). |
| `shortcut?` | `string` | The key hint, e.g. "⌘K" (hidden on touch screens). |
| `bindShortcut?` | `boolean` | ⌘/Ctrl + the hint's last key (K for "⌘K") focuses the field, except while typing elsewhere. |
| `value?` | `string` |  |
| `defaultValue?` | `string` |  |
| `onChange?` | `(e: ChangeEvent<HTMLInputElement>) => void` |  |
| `onKeyDown?` | `(e: KeyboardEvent<HTMLInputElement>) => void` |  |
| `onFocus?` | `(e: FocusEvent<HTMLInputElement>) => void` |  |
| `onBlur?` | `(e: FocusEvent<HTMLInputElement>) => void` |  |
| `id?` | `string` |  |
| `name?` | `string` |  |
| `autoFocus?` | `boolean` |  |
| `inputProps?` | `InputHTMLAttributes<HTMLInputElement>` | For a search with suggestions (combobox): role, aria-controls, aria-activedescendant … |
| `className?` | `string` | Extra class on the root element. |
| `style?` | `CSSProperties` | Inline style on the root element. |

#### Segmented

| Prop | Type | Notes |
| --- | --- | --- |
| `options` | `(string \| Option)[]` | Required |
| `value?` | `string` |  |
| `defaultValue?` | `string` |  |
| `onChange?` | `(v: string) => void` |  |
| `size?` | `"sm"` |  |
| `block?` | `boolean` |  |
| `label?` | `string` |  |
| `className?` | `string` | Extra class on the root element. |
| `style?` | `CSSProperties` | Inline style on the root element. |


## Select Menu

> A styled select: the button shows the choice, the list opens below it with groups, icons, hints and disabled options.

Component · Forms · Halo kit · [Live page](https://ui.twentyfirst.media/halo/components/SelectMenu/)

A styled select: the button shows the choice, the list opens below it with groups, icons, hints
and disabled options. Use the native `Select` when the system picker is preferred (long lists on
phones).

- Keyboard: ↑/↓/Enter/Space open, arrows move, Home/End jump, typing jumps to a match, Enter picks,
  Escape closes.
- Inside a `Form` it submits its value under `name` and shows its validation message.

### Example

```tsx
import * as React from "react";
import { SelectMenu } from "@twentyfirstmedia/halo";

export default function Preview() {
  return (
    <div
      className="tf-panel tf-grid"
      style={{ "--cols": "1fr 1fr", gap: 20, paddingBottom: 260 } as React.CSSProperties}
    >
      <SelectMenu
        label="Assignee"
        placeholder="Choose a person"
        options={[
          { value: "mara", label: "Mara Ellis", hint: "Owner", group: "Leadership" },
          { value: "jonah", label: "Jonah Petit", hint: "Design", group: "Team" },
          { value: "sun", label: "Sun Lee", hint: "Growth", group: "Team" },
          { value: "rui", label: "Rui Costa", hint: "Finance", group: "Team" },
          { value: "ava", label: "Ava Brandt", hint: "Invited", group: "Team", disabled: true },
        ]}
      />
      <SelectMenu
        label="Region"
        defaultValue="eu"
        hint="Where workspace data is stored"
        options={[
          { value: "eu", label: "Europe (Frankfurt)", icon: "globe" },
          { value: "us", label: "United States (Ohio)", icon: "globe" },
          { value: "ap", label: "Asia Pacific (Sydney)", icon: "globe" },
        ]}
      />
    </div>
  );
}
```

### Props

#### SelectMenu

| Prop | Type | Notes |
| --- | --- | --- |
| `options` | `(string \| SelectMenuOption)[]` | Required |
| `value?` | `string` |  |
| `defaultValue?` | `string` |  |
| `onChange?` | `(value: string) => void` |  |
| `placeholder?` | `string` |  |
| `disabled?` | `boolean` |  |
| `size?` | `"sm" \| "md"` | `sm`: a compact trigger, e.g. a sort menu next to a heading. |
| `label?` | `string` |  |
| `hint?` | `string` |  |
| `error?` | `string` |  |
| `className?` | `string` | Extra class on the root element. |
| `style?` | `CSSProperties` | Inline style on the root element. |


## Form

> Validation for native forms.

Component · Forms · Halo kit · [Live page](https://ui.twentyfirst.media/halo/components/Form/)

Validation for native forms. Give `rules` by field `name`; on submit the form checks them, shows
each message under its field, marks the field `aria-invalid` and focuses the first one. After the
first submit, fields re-check as they change.

- Rules: `required`, `email`, `minLength`/`maxLength`, `min`/`max`, `pattern`, and `validate` for
  anything else. Messages can be set per rule.
- `onSubmit` receives the values by name; `errors` shows messages from the server.
- Works with `TextField`, `Input`, `Select`, `Textarea`, `SelectMenu`, `Checkbox` and `Switch`.

### Example

```tsx
import * as React from "react";
import {
  Button,
  Checkbox,
  Form,
  SelectMenu,
  TextField,
  Textarea,
  toast,
} from "@twentyfirstmedia/halo";

export default function Preview() {
  return (
    <div className="tf-panel" style={{ maxWidth: 520 }}>
      <Form
        rules={{
          name: { required: "Tell us your name" },
          email: { required: true, email: true },
          team: { required: "Pick a team" },
          message: { minLength: 20, message: "Write at least 20 characters" },
          terms: { required: "Accept the terms to continue" },
        }}
        onSubmit={(v) => toast({ text: `Thanks, ${v.name}` })}
      >
        <TextField name="name" label="Name" placeholder="Mara Ellis" required />
        <TextField
          name="email"
          label="Work email"
          type="email"
          placeholder="you@company.com"
          required
        />
        <SelectMenu
          name="team"
          label="Team"
          placeholder="Choose a team"
          required
          options={["Design", "Engineering", "Growth", "Finance"]}
        />
        <Textarea name="message" label="Message" placeholder="What do you need?" rows={3} />
        <Checkbox name="terms" value="yes">
          I accept the terms
        </Checkbox>
        <div className="tf-row" style={{ justifyContent: "flex-end" }}>
          <Button type="submit">Send</Button>
        </div>
      </Form>
    </div>
  );
}
```

### Props

#### Form

| Prop | Type | Notes |
| --- | --- | --- |
| `rules?` | `Record<string, FormRule>` | Rules by field `name`. Fields show their message under the input. |
| `onSubmit?` | `(values: FormValues) => void` | Called with the values (by `name`) when every rule passes. |
| `onInvalid?` | `(errors: Record<string, string>) => void` | Called with the messages when the form is submitted with errors. |
| `errors?` | `Record<string, string>` | Messages from the server, by field name (for example after a failed save). |
| `children?` | `ReactNode` |  |
| `className?` | `string` | Extra class on the root element. |
| `style?` | `CSSProperties` | Inline style on the root element. |

#### TextField

| Prop | Type | Notes |
| --- | --- | --- |
| `type?` | `string` | Input type (`"text"` by default): `"email"`, `"number"`, `"tel"`, `"url"`, `"password"` … |
| `icon?` | `IconName` |  |
| `suffix?` | `ReactNode` |  |
| `value?` | `string` |  |
| `defaultValue?` | `string` |  |
| `placeholder?` | `string` |  |
| `disabled?` | `boolean` |  |
| `readOnly?` | `boolean` |  |
| `autoComplete?` | `string` |  |
| `autoFocus?` | `boolean` |  |
| `min?` | `number \| string` | Smallest value for `type="number"`, `"date"` and the like (native `min`). |
| `max?` | `number \| string` | Largest value (native `max`). |
| `step?` | `number \| string` | Step between valid values (native `step`), e.g. `1` for whole numbers or `"any"`. |
| `minLength?` | `number` | Fewest characters (native `minlength`). |
| `maxLength?` | `number` | Most characters (native `maxlength`). |
| `pattern?` | `string` | Pattern the value must match (native `pattern`). |
| `inputMode?` | `"none" \| "text" \| "tel" \| "url" \| "email" \| "numeric" \| "decimal" \| "search"` | Virtual keyboard on touch devices (native `inputmode`), e.g. `"numeric"` or `"decimal"`. |
| `onChange?` | `(e: ChangeEvent<HTMLInputElement>) => void` |  |
| `onBlur?` | `(e: ChangeEvent<HTMLInputElement>) => void` |  |
| `onKeyDown?` | `(e: KeyboardEvent<HTMLInputElement>) => void` |  |
| `action?` | `ReactNode` | An interactive control at the end of the field (an `IconButton`: clear, copy, locate …). Unlike `suffix` it can be clicked, and it stays when the field shows an error or success mark. |
| `reveal?` | `boolean` | For `type="password"`: a button that shows and hides the password (default true). |
| `label?` | `string` |  |
| `hint?` | `string` |  |
| `error?` | `string` |  |

#### SelectMenu

| Prop | Type | Notes |
| --- | --- | --- |
| `options` | `(string \| SelectMenuOption)[]` | Required |
| `value?` | `string` |  |
| `defaultValue?` | `string` |  |
| `onChange?` | `(value: string) => void` |  |
| `placeholder?` | `string` |  |
| `disabled?` | `boolean` |  |
| `size?` | `"sm" \| "md"` | `sm`: a compact trigger, e.g. a sort menu next to a heading. |
| `label?` | `string` |  |
| `hint?` | `string` |  |
| `error?` | `string` |  |
| `className?` | `string` | Extra class on the root element. |
| `style?` | `CSSProperties` | Inline style on the root element. |

#### Textarea

| Prop | Type | Notes |
| --- | --- | --- |
| `placeholder?` | `string` |  |
| `value?` | `string` |  |
| `defaultValue?` | `string` |  |
| `rows?` | `number` |  |
| `disabled?` | `boolean` |  |
| `onChange?` | `(e: ChangeEvent<HTMLTextAreaElement>) => void` |  |
| `label?` | `string` |  |
| `hint?` | `string` |  |
| `error?` | `string` |  |
| `className?` | `string` | Extra class on the root element. |
| `style?` | `CSSProperties` | Inline style on the root element. |

#### Checkbox

| Prop | Type | Notes |
| --- | --- | --- |
| `name?` | `string` |  |
| `value?` | `string` |  |
| `required?` | `boolean` |  |
| `checked?` | `boolean` |  |
| `defaultChecked?` | `boolean` |  |
| `onChange?` | `(e: ChangeEvent<HTMLInputElement>) => void` |  |
| `children?` | `ReactNode` |  |
| `disabled?` | `boolean` |  |
| `label?` | `string` |  |
| `className?` | `string` | Extra class on the root element. |
| `style?` | `CSSProperties` | Inline style on the root element. |

#### Button

| Prop | Type | Notes |
| --- | --- | --- |
| `variant?` | `"primary" \| "secondary" \| "soft" \| "ghost" \| "danger" \| "danger-solid"` |  |
| `size?` | `"md" \| "sm"` |  |
| `icon?` | `IconName` |  |
| `iconRight?` | `IconName` |  |
| `disabled?` | `boolean` |  |
| `type?` | `"button" \| "submit" \| "reset"` |  |
| `onClick?` | `(e: MouseEvent<HTMLButtonElement>) => void` |  |
| `children?` | `ReactNode` |  |
| `asChild?` | `boolean` | Render the single child element (a link, a router Link) with the button's look instead of a <button>. |
| `id?` | `string` |  |
| `name?` | `string` | Form field name and value, sent with the form when this button submits it. |
| `value?` | `string` |  |
| `form?` | `string` | The id of the form this button belongs to, when it sits outside it. |
| `title?` | `string` |  |
| `tabIndex?` | `number` |  |
| `autoFocus?` | `boolean` |  |
| `aria-label?` | `string` |  |
| `aria-labelledby?` | `string` |  |
| `aria-describedby?` | `string` |  |
| `aria-expanded?` | `boolean \| "true" \| "false"` | For disclosure and menu triggers: whether what the button controls is open. |
| `aria-controls?` | `string` |  |
| `aria-haspopup?` | `boolean \| "true" \| "false" \| "menu" \| "listbox" \| "tree" \| "grid" \| "dialog"` |  |
| `aria-pressed?` | `boolean \| "true" \| "false" \| "mixed"` | For toggle buttons. |
| `aria-current?` | `boolean \| "true" \| "false" \| "page" \| "step" \| "location" \| "date" \| "time"` |  |
| `className?` | `string` | Extra class on the root element. |
| `style?` | `CSSProperties` | Inline style on the root element. |


## Sheet

> A Drawer that slides in from any edge: side="right" (default), "left", "top" or "bottom".

Component · Overlays · Halo kit · [Live page](https://ui.twentyfirst.media/halo/components/Sheet/)

A `Drawer` that slides in from any edge: `side="right"` (default), `"left"`, `"top"` or
`"bottom"`. Bottom sheets suit filters and quick actions on phones; left sheets hold navigation.

- Focus moves into the sheet and stays there until it closes; Escape and a click outside close it.

### Example

```tsx
import * as React from "react";
import { Button, Drawer, SelectMenu } from "@twentyfirstmedia/halo";

export default function Preview() {
  return (
    <div
      style={{
        position: "relative",
        height: 420,
        borderRadius: "var(--radius-lg)",
        overflow: "hidden",
        background: "var(--canvas)",
      }}
    >
      <Drawer
        inline
        side="bottom"
        title="Filters"
        subtitle="12 of 48 listings match"
        onClose={() => {}}
      >
        <div className="tf-grid" style={{ "--cols": "1fr 1fr", gap: 16 } as React.CSSProperties}>
          <SelectMenu label="Rooms" defaultValue="3" options={["1", "2", "3", "4+"]} />
          <SelectMenu label="Sort by" defaultValue="Newest" options={["Newest", "Price", "Size"]} />
        </div>
        <div className="tf-row" style={{ justifyContent: "flex-end" }}>
          <Button variant="ghost">Reset</Button>
          <Button>Show 12 listings</Button>
        </div>
      </Drawer>
    </div>
  );
}
```

### Props

#### Drawer

| Prop | Type | Notes |
| --- | --- | --- |
| `title` | `string` | Required |
| `subtitle?` | `ReactNode` |  |
| `avatar?` | `string` |  |
| `onClose?` | `() => void` |  |
| `width?` | `number \| string` |  |
| `inline?` | `boolean` |  |
| `children?` | `ReactNode` |  |
| `open?` | `boolean` | Optional: with `open` the component stays mounted while it animates out; without it, render it only while open. |
| `className?` | `string` | Extra class on the root element. |
| `style?` | `CSSProperties` | Inline style on the root element. |

#### SelectMenu

| Prop | Type | Notes |
| --- | --- | --- |
| `options` | `(string \| SelectMenuOption)[]` | Required |
| `value?` | `string` |  |
| `defaultValue?` | `string` |  |
| `onChange?` | `(value: string) => void` |  |
| `placeholder?` | `string` |  |
| `disabled?` | `boolean` |  |
| `size?` | `"sm" \| "md"` | `sm`: a compact trigger, e.g. a sort menu next to a heading. |
| `label?` | `string` |  |
| `hint?` | `string` |  |
| `error?` | `string` |  |
| `className?` | `string` | Extra class on the root element. |
| `style?` | `CSSProperties` | Inline style on the root element. |

#### Button

| Prop | Type | Notes |
| --- | --- | --- |
| `variant?` | `"primary" \| "secondary" \| "soft" \| "ghost" \| "danger" \| "danger-solid"` |  |
| `size?` | `"md" \| "sm"` |  |
| `icon?` | `IconName` |  |
| `iconRight?` | `IconName` |  |
| `disabled?` | `boolean` |  |
| `type?` | `"button" \| "submit" \| "reset"` |  |
| `onClick?` | `(e: MouseEvent<HTMLButtonElement>) => void` |  |
| `children?` | `ReactNode` |  |
| `asChild?` | `boolean` | Render the single child element (a link, a router Link) with the button's look instead of a <button>. |
| `id?` | `string` |  |
| `name?` | `string` | Form field name and value, sent with the form when this button submits it. |
| `value?` | `string` |  |
| `form?` | `string` | The id of the form this button belongs to, when it sits outside it. |
| `title?` | `string` |  |
| `tabIndex?` | `number` |  |
| `autoFocus?` | `boolean` |  |
| `aria-label?` | `string` |  |
| `aria-labelledby?` | `string` |  |
| `aria-describedby?` | `string` |  |
| `aria-expanded?` | `boolean \| "true" \| "false"` | For disclosure and menu triggers: whether what the button controls is open. |
| `aria-controls?` | `string` |  |
| `aria-haspopup?` | `boolean \| "true" \| "false" \| "menu" \| "listbox" \| "tree" \| "grid" \| "dialog"` |  |
| `aria-pressed?` | `boolean \| "true" \| "false" \| "mixed"` | For toggle buttons. |
| `aria-current?` | `boolean \| "true" \| "false" \| "page" \| "step" \| "location" \| "date" \| "time"` |  |
| `className?` | `string` | Extra class on the root element. |
| `style?` | `CSSProperties` | Inline style on the root element. |


## Resizable Panels

> Two or more panes with drag handles between them, side by side or stacked; panels can nest.

Component · Foundations · Halo kit · [Live page](https://ui.twentyfirst.media/halo/components/ResizablePanels/)

Two or more panes with drag handles between them, side by side or stacked; panels can nest.

- Handles are separators with a value: ←/→ (↑/↓ when stacked) resize by 2%, Home/End jump to the
  limits, double-click resets to equal sizes.
- `min` keeps every pane above a share of the whole; `storageKey` remembers the sizes.

### Example

```tsx
import { ResizablePanels } from "@twentyfirstmedia/halo";

const pane = (title: string, text: string) => (
  <div className="tf-col" style={{ gap: 6, padding: 16 }}>
    <b>{title}</b>
    <span className="tf-card-desc">{text}</span>
  </div>
);

export default function Preview() {
  return (
    <div className="tf-panel" style={{ padding: 0, height: 320, overflow: "hidden" }}>
      <ResizablePanels
        labels={["Folders", "Messages"]}
        defaultSizes={[22, 38, 40]}
        panels={[
          pane("Folders", "Inbox, Sent, Archive"),
          pane("Messages", "Drag a handle, or focus it and use the arrow keys."),
          <ResizablePanels
            key="r"
            orientation="vertical"
            labels={["Thread"]}
            defaultSizes={[60, 40]}
            panels={[pane("Thread", "Northwind · Seat upgrade"), pane("Reply", "Write a reply…")]}
          />,
        ]}
      />
    </div>
  );
}
```

### Props

#### ResizablePanels

| Prop | Type | Notes |
| --- | --- | --- |
| `panels` | `ReactNode[]` | Required |
| `defaultSizes?` | `number[]` | Start sizes in percent (default: equal). |
| `min?` | `number` | Smallest size of a panel in percent (default 10). |
| `orientation?` | `"horizontal" \| "vertical"` |  |
| `storageKey?` | `string` | Remembers the sizes in localStorage under this key. |
| `labels?` | `string[]` | Accessible names of the panels, used for the resize handles. |
| `className?` | `string` | Extra class on the root element. |
| `style?` | `CSSProperties` | Inline style on the root element. |


## Qr Code

> A QR code drawn as SVG and encoded on the device, so the text (a sign-in secret, an invite link) never goes to a service.

Component · Admin · Halo kit · [Live page](https://ui.twentyfirst.media/halo/components/QrCode/)

A QR code drawn as SVG and encoded on the device, so the text (a sign-in secret, an invite link)
never goes to a service.

- `value` is the text; `level` sets the error correction (L, M by default, Q, H).
- It fills its container's width, or `size`; the light quiet zone (`quiet`, default 4 modules) is
  part of the drawing.
- Dark modules on the paper colour in every theme, because scanners expect dark on light.
- `TwoFactorSetup` draws one from `qrValue` (the otpauth:// link).

### Example

```tsx
import { Card, QrCode } from "@twentyfirstmedia/halo";

export default function Preview() {
  return (
    <div className="tf-row" style={{ gap: 24, alignItems: "flex-start", flexWrap: "wrap" }}>
      <Card style={{ width: 200, minHeight: 0 }}>
        <QrCode
          value="otpauth://totp/Halo:mara%40halo.app?secret=JBSWY3DPEHPK3PXP&issuer=Halo"
          label="Authenticator setup code"
        />
        <small className="tf-muted">Scan with an authenticator app</small>
      </Card>
      <Card style={{ width: 160, minHeight: 0 }}>
        <QrCode value="https://halo.app/invite/7F3K" level="Q" label="Invite link" />
        <small className="tf-muted">Join on your phone</small>
      </Card>
    </div>
  );
}
```

### Props

#### QrCode

| Prop | Type | Notes |
| --- | --- | --- |
| `value` | `string` | The text to encode: an otpauth:// link, a URL … |
| `level?` | `"L" \| "M" \| "Q" \| "H"` | Error correction: L, M (default), Q or H. |
| `size?` | `number \| string` | Width and height (default: the width of its container). |
| `quiet?` | `number` | Light modules around the code (default 4, the standard quiet zone). |
| `label?` | `string` | Accessible name (default "QR code"). |
| `className?` | `string` | Extra class on the root element. |
| `style?` | `CSSProperties` | Inline style on the root element. |

#### Card

| Prop | Type | Notes |
| --- | --- | --- |
| `title?` | `string` |  |
| `description?` | `string` |  |
| `meta?` | `string[]` |  |
| `corner?` | `ReactNode` |  |
| `status?` | `ReactNode` |  |
| `actions?` | `ReactNode[]` |  |
| `tint?` | `Tint \| "surface"` |  |
| `onClick?` | `() => void` |  |
| `children?` | `ReactNode` |  |
| `eyebrow?` | `ReactNode` |  |
| `surface?` | `Surface` | `"glass"`: translucent glass over what is behind (maps, 3D, video, photos); `"solid"` opts out inside a glass `UIProvider`. |
| `className?` | `string` | Extra class on the root element. |
| `style?` | `CSSProperties` | Inline style on the root element. |


## Habit Tracker

> Habits with their last days as a row of marks: done, missed or no entry, today's mark a toggle.

Component · Life · Halo kit · [Live page](https://ui.twentyfirst.media/halo/components/HabitTracker/)

Habits with their last days as a row of marks: done, missed or no entry, today's mark a toggle.

- `days` is one entry per day, oldest first and today last: `true`, `false` or `null`.
- `streak` shows "12-day streak"; `goal` a short target ("8 glasses").
- `onToggle(id, done)` makes today's mark a button; the other days are read-only and named for
  screen readers ("Mon Done").
- Day labels default to weekday initials ending today; pass `dayLabels` to set them yourself.

### Example

```tsx
import * as React from "react";
import { HabitTracker, Panel, registerIcons } from "@twentyfirstmedia/halo";
import { droplet } from "@twentyfirstmedia/ui-core/icons";

// library icons are registered once by the app
registerIcons({ droplet });
import type { Habit } from "@twentyfirstmedia/halo";

const DAYS = ["M", "T", "W", "T", "F", "S", "S"];

export default function Preview() {
  const [habits, setHabits] = React.useState<Habit[]>([
    {
      id: "walk",
      label: "Morning walk",
      icon: "sun",
      tint: "butter",
      days: [true, true, false, true, true, true, false],
      streak: 3,
      goal: "20 min",
    },
    {
      id: "water",
      label: "Drink water",
      icon: "droplet",
      tint: "sky",
      days: [true, true, true, true, true, true, true],
      streak: 12,
      goal: "8 glasses",
    },
    {
      id: "read",
      label: "Read",
      icon: "book",
      tint: "lilac",
      days: [false, true, null, true, false, true, false],
      goal: "3× a week",
    },
    {
      id: "screens",
      label: "No screens after 10 pm",
      icon: "moon",
      tint: "mint",
      days: [true, false, false, true, true, null, false],
    },
  ]);
  return (
    <Panel title="Habits" subtitle="This week" style={{ maxWidth: 560 }}>
      <HabitTracker
        habits={habits}
        dayLabels={DAYS}
        onToggle={(id, done) =>
          setHabits((list) =>
            list.map((h) =>
              h.id === id
                ? {
                    ...h,
                    days: [...h.days.slice(0, -1), done],
                    streak: done ? (h.streak || 0) + 1 : Math.max(0, (h.streak || 1) - 1),
                  }
                : h,
            ),
          )
        }
      />
    </Panel>
  );
}
```

### Props

#### HabitTracker

| Prop | Type | Notes |
| --- | --- | --- |
| `habits` | `Habit[]` | Required |
| `dayLabels?` | `string[]` | Labels of the day columns, oldest first (default: weekday initials ending today). |
| `onToggle?` | `(id: string, done: boolean) => void` | Today's box of a habit was toggled. |
| `label?` | `string` | Accessible name of the list (default "Habits"). |
| `className?` | `string` | Extra class on the root element. |
| `style?` | `CSSProperties` | Inline style on the root element. |

#### Panel

| Prop | Type | Notes |
| --- | --- | --- |
| `side?` | `boolean` |  |
| `title?` | `string` |  |
| `subtitle?` | `string` |  |
| `action?` | `ReactNode` |  |
| `children?` | `ReactNode` |  |
| `surface?` | `Surface` | `"glass"`: translucent glass over what is behind (maps, 3D, video, photos); `"solid"` opts out inside a glass `UIProvider`. |
| `className?` | `string` | Extra class on the root element. |
| `style?` | `CSSProperties` | Inline style on the root element. |


## Mood Picker

> A five-step mood scale with faces and words, as a radio group.

Component · Life · Halo kit · [Live page](https://ui.twentyfirst.media/halo/components/MoodPicker/)

A five-step mood scale with faces and words, as a radio group.

- `value` / `onChange` with levels 1 (lowest) to 5; `levels` replaces the five words.
- `compact` shows only the faces; the words stay as accessible names.
- The picked level takes its tint and a ring, so it never depends on colour alone.

### Example

```tsx
import * as React from "react";
import { Card, MoodPicker } from "@twentyfirstmedia/halo";
import type { MoodLevel } from "@twentyfirstmedia/halo";

export default function Preview() {
  const [mood, setMood] = React.useState<MoodLevel | null>(4);
  return (
    <div className="tf-row" style={{ gap: 24, flexWrap: "wrap", alignItems: "flex-start" }}>
      <Card style={{ width: 420, minHeight: 0 }}>
        <MoodPicker value={mood} onChange={setMood} />
      </Card>
      <Card style={{ width: 280, minHeight: 0 }}>
        <MoodPicker label="Energy today" compact defaultValue={3} />
      </Card>
    </div>
  );
}
```

### Props

#### MoodPicker

| Prop | Type | Notes |
| --- | --- | --- |
| `value?` | `MoodLevel \| null` |  |
| `defaultValue?` | `MoodLevel \| null` |  |
| `onChange?` | `(mood: MoodLevel) => void` |  |
| `label?` | `ReactNode` | The question (default "How are you feeling?"). |
| `levels?` | `[string, string, string, string, string]` | Words for the five levels, lowest first (default Awful, Low, Okay, Good, Great). |
| `compact?` | `boolean` | Only the faces; the words stay as accessible names. |
| `className?` | `string` | Extra class on the root element. |
| `style?` | `CSSProperties` | Inline style on the root element. |

#### Card

| Prop | Type | Notes |
| --- | --- | --- |
| `title?` | `string` |  |
| `description?` | `string` |  |
| `meta?` | `string[]` |  |
| `corner?` | `ReactNode` |  |
| `status?` | `ReactNode` |  |
| `actions?` | `ReactNode[]` |  |
| `tint?` | `Tint \| "surface"` |  |
| `onClick?` | `() => void` |  |
| `children?` | `ReactNode` |  |
| `eyebrow?` | `ReactNode` |  |
| `surface?` | `Surface` | `"glass"`: translucent glass over what is behind (maps, 3D, video, photos); `"solid"` opts out inside a glass `UIProvider`. |
| `className?` | `string` | Extra class on the root element. |
| `style?` | `CSSProperties` | Inline style on the root element. |


## Vital Tile

> One health value with its healthy range: the value, a band with the normal zone and a marker, a status in words (in range, below, above) and an optional trend.

Component · Life · Halo kit · [Live page](https://ui.twentyfirst.media/halo/components/VitalTile/)

One health value with its healthy range: the value, a band with the normal zone and a marker, a
status in words (in range, below, above) and an optional trend.

- `normal` is the healthy range; `scale` the whole band (default: the range with room around it).
- `digits` for decimals, `unit`, `caption` for the source and time of the reading.
- The status is text in a badge, never colour alone.

### Example

```tsx
import type * as React from "react";
import { VitalTile } from "@twentyfirstmedia/halo";

export default function Preview() {
  return (
    <div
      className="tf-grid"
      style={
        {
          "--cols": "repeat(3, minmax(0, 1fr))",
          "--cols-sm": "1fr",
          gap: 16,
        } as React.CSSProperties
      }
    >
      <VitalTile
        label="Resting heart rate"
        value={58}
        unit="bpm"
        normal={[50, 80]}
        trend={[61, 60, 62, 59, 58, 58, 57, 58]}
        caption="Watch · this morning"
      />
      <VitalTile
        label="Blood pressure (systolic)"
        icon="zap"
        value={138}
        unit="mmHg"
        normal={[90, 129]}
        trend={[128, 131, 130, 134, 136, 135, 138]}
        caption="Cuff · yesterday 21:10"
      />
      <VitalTile
        label="Weight"
        icon="trend"
        value={74.2}
        digits={1}
        unit="kg"
        trend={[75.8, 75.4, 75.1, 74.9, 74.6, 74.4, 74.2]}
        caption="Scale · today"
      />
    </div>
  );
}
```

### Props

#### VitalTile

| Prop | Type | Notes |
| --- | --- | --- |
| `surface?` | `Surface` | `"glass"`: translucent glass over a backdrop (`Ambient`, a photo, a map); `"solid"` opts out inside a glass `UIProvider`. |
| `label` | `string` | Required |
| `value` | `number` | Required |
| `unit?` | `string` |  |
| `icon?` | `IconName` |  |
| `normal?` | `[number, number]` | The healthy range [low, high]; the tile says whether the value is below, in or above it. |
| `scale?` | `[number, number]` | The whole scale of the band [min, max] (default: the normal range with room on both sides). |
| `trend?` | `number[]` | Recent values, oldest first, drawn as a sparkline. |
| `caption?` | `ReactNode` | Under the value: when it was measured, the source … |
| `digits?` | `number` | Digits after the decimal point (default 0). |
| `className?` | `string` | Extra class on the root element. |
| `style?` | `CSSProperties` | Inline style on the root element. |


## Activity Rings

> Concentric progress rings for daily goals (move, exercise, stand, steps, water) with a legend.

Component · Life · Halo kit · [Live page](https://ui.twentyfirst.media/halo/components/ActivityRings/)

Concentric progress rings for daily goals (move, exercise, stand, steps, water) with a legend.

- `rings` lists outer ring first: `label`, `value`, `goal`, `unit`, `tint`.
- The rings carry one accessible description with every value and goal; `legend={false}` hides the
  visible legend.

### Example

```tsx
import { ActivityRings, Card } from "@twentyfirstmedia/halo";

export default function Preview() {
  return (
    <div className="tf-row" style={{ gap: 24, flexWrap: "wrap", alignItems: "flex-start" }}>
      <Card style={{ minHeight: 0 }}>
        <ActivityRings
          rings={[
            { label: "Move", value: 420, goal: 600, unit: "kcal", tint: "blush" },
            { label: "Exercise", value: 24, goal: 30, unit: "min", tint: "mint" },
            { label: "Stand", value: 9, goal: 12, unit: "h", tint: "sky" },
          ]}
        />
      </Card>
      <Card style={{ minHeight: 0 }}>
        <ActivityRings
          size={88}
          legend={false}
          label="Steps and water"
          rings={[
            { label: "Steps", value: 8400, goal: 8000, tint: "lilac" },
            { label: "Water", value: 5, goal: 8, unit: "glasses", tint: "sky" },
          ]}
        />
      </Card>
    </div>
  );
}
```

### Props

#### ActivityRings

| Prop | Type | Notes |
| --- | --- | --- |
| `rings` | `ActivityRing[]` | Outer ring first. |
| `size?` | `number` | Diameter of the rings (default 132). |
| `legend?` | `boolean` | Hide the legend beside the rings. |
| `label?` | `string` | Accessible name (default "Activity"). |
| `className?` | `string` | Extra class on the root element. |
| `style?` | `CSSProperties` | Inline style on the root element. |

#### Card

| Prop | Type | Notes |
| --- | --- | --- |
| `title?` | `string` |  |
| `description?` | `string` |  |
| `meta?` | `string[]` |  |
| `corner?` | `ReactNode` |  |
| `status?` | `ReactNode` |  |
| `actions?` | `ReactNode[]` |  |
| `tint?` | `Tint \| "surface"` |  |
| `onClick?` | `() => void` |  |
| `children?` | `ReactNode` |  |
| `eyebrow?` | `ReactNode` |  |
| `surface?` | `Surface` | `"glass"`: translucent glass over what is behind (maps, 3D, video, photos); `"solid"` opts out inside a glass `UIProvider`. |
| `className?` | `string` | Extra class on the root element. |
| `style?` | `CSSProperties` | Inline style on the root element. |


## Sleep Chart

> A night as sleep stages over time, one lane per stage (awake, REM, light, deep), with the time asleep and the time per stage.

Component · Life · Halo kit · [Live page](https://ui.twentyfirst.media/halo/components/SleepChart/)

A night as sleep stages over time, one lane per stage (awake, REM, light, deep), with the time
asleep and the time per stage.

- `segments` are `{ stage, start, end }` in order; times as `Date`, ISO string or timestamp.
- The chart has one accessible description with every total; `summary={false}` hides the totals.

### Example

```tsx
import { Panel, SleepChart } from "@twentyfirstmedia/halo";
import type { SleepSegment } from "@twentyfirstmedia/halo";

// one night, as a watch reports it (fixed times, so the example stays the same)
const at = (h: number, m: number) => new Date(2026, 10, h < 12 ? 13 : 12, h, m).getTime();
const night: SleepSegment[] = [
  ["awake", 23, 5, 23, 20],
  ["light", 23, 20, 23, 50],
  ["deep", 23, 50, 0, 55],
  ["light", 0, 55, 1, 40],
  ["rem", 1, 40, 2, 10],
  ["light", 2, 10, 2, 50],
  ["deep", 2, 50, 3, 30],
  ["awake", 3, 30, 3, 38],
  ["light", 3, 38, 4, 40],
  ["rem", 4, 40, 5, 25],
  ["light", 5, 25, 6, 20],
  ["rem", 6, 20, 6, 50],
  ["awake", 6, 50, 7, 0],
].map(([stage, h1, m1, h2, m2]) => ({
  stage: stage as SleepSegment["stage"],
  start: at(h1 as number, m1 as number),
  end: at(h2 as number, m2 as number),
}));

export default function Preview() {
  return (
    <Panel title="Last night" subtitle="Thu 12 → Fri 13 Nov" style={{ maxWidth: 640 }}>
      <SleepChart segments={night} />
    </Panel>
  );
}
```

### Props

#### SleepChart

| Prop | Type | Notes |
| --- | --- | --- |
| `segments` | `SleepSegment[]` | The night in order, from falling asleep to getting up. |
| `label?` | `string` | Accessible name (default "Sleep stages"). |
| `summary?` | `boolean` | Hide the totals per stage under the chart. |
| `className?` | `string` | Extra class on the root element. |
| `style?` | `CSSProperties` | Inline style on the root element. |

#### Panel

| Prop | Type | Notes |
| --- | --- | --- |
| `side?` | `boolean` |  |
| `title?` | `string` |  |
| `subtitle?` | `string` |  |
| `action?` | `ReactNode` |  |
| `children?` | `ReactNode` |  |
| `surface?` | `Surface` | `"glass"`: translucent glass over what is behind (maps, 3D, video, photos); `"solid"` opts out inside a glass `UIProvider`. |
| `className?` | `string` | Extra class on the root element. |
| `style?` | `CSSProperties` | Inline style on the root element. |


## Medication List

> Today's doses in order, each with its time, name, dose, a status in words and a "taken" button.

Component · Life · Halo kit · [Live page](https://ui.twentyfirst.media/halo/components/MedicationList/)

Today's doses in order, each with its time, name, dose, a status in words and a "taken" button.

- `status` is set by the app, which knows the clock: `taken`, `due`, `missed` or `upcoming`.
- `onTake(id)` adds a button named "Mark Ramipril as taken" to doses that are due or missed.

### Example

```tsx
import * as React from "react";
import { MedicationList, Panel } from "@twentyfirstmedia/halo";
import type { MedicationItem } from "@twentyfirstmedia/halo";

export default function Preview() {
  const [items, setItems] = React.useState<MedicationItem[]>([
    { id: "d", name: "Vitamin D", dose: "1,000 IU", time: "07:30", status: "taken" },
    {
      id: "m",
      name: "Metformin",
      dose: "500 mg",
      note: "With breakfast",
      time: "08:00",
      status: "missed",
    },
    { id: "r", name: "Ramipril", dose: "5 mg", time: "13:00", status: "due" },
    {
      id: "s",
      name: "Magnesium",
      dose: "300 mg",
      note: "Before bed",
      time: "22:00",
      status: "upcoming",
    },
  ]);
  return (
    <Panel title="Today" subtitle="4 doses · 1 taken" style={{ maxWidth: 560 }}>
      <MedicationList
        items={items}
        onTake={(id) =>
          setItems((list) => list.map((m) => (m.id === id ? { ...m, status: "taken" } : m)))
        }
      />
    </Panel>
  );
}
```

### Props

#### MedicationList

| Prop | Type | Notes |
| --- | --- | --- |
| `items` | `MedicationItem[]` | Required |
| `onTake?` | `(id: string) => void` | "Mark as taken" was pressed. |
| `label?` | `string` | Accessible name (default "Medication"). |
| `className?` | `string` | Extra class on the root element. |
| `style?` | `CSSProperties` | Inline style on the root element. |

#### Panel

| Prop | Type | Notes |
| --- | --- | --- |
| `side?` | `boolean` |  |
| `title?` | `string` |  |
| `subtitle?` | `string` |  |
| `action?` | `ReactNode` |  |
| `children?` | `ReactNode` |  |
| `surface?` | `Surface` | `"glass"`: translucent glass over what is behind (maps, 3D, video, photos); `"solid"` opts out inside a glass `UIProvider`. |
| `className?` | `string` | Extra class on the root element. |
| `style?` | `CSSProperties` | Inline style on the root element. |


## Journal Entry

> A journal or diary entry: the date, the mood of the day, a title, the text and tags, with room for actions such as edit or share.

Component · Life · Halo kit · [Live page](https://ui.twentyfirst.media/halo/components/JournalEntry/)

A journal or diary entry: the date, the mood of the day, a title, the text and tags, with room for
actions such as edit or share.

### Example

```tsx
import { IconButton, JournalEntry } from "@twentyfirstmedia/halo";

export default function Preview() {
  return (
    <div className="tf-col" style={{ gap: 16, maxWidth: 560 }}>
      <JournalEntry
        date={new Date(2026, 10, 12)}
        mood={4}
        title="Slow morning, good walk"
        tags={["Walk", "Family"]}
        actions={<IconButton icon="edit" label="Edit entry" size="sm" variant="ghost" />}
      >
        <p>
          Slept through for once. Walked to the harbour with Lena before work and the day felt
          lighter after that. Need to book the dentist.
        </p>
      </JournalEntry>
      <JournalEntry date={new Date(2026, 10, 10)} mood={2} tags={["Work"]}>
        <p>Long day, too many calls. Skipped lunch again.</p>
      </JournalEntry>
    </div>
  );
}
```

### Props

#### JournalEntry

| Prop | Type | Notes |
| --- | --- | --- |
| `surface?` | `Surface` | `"glass"`: translucent glass over a backdrop (`Ambient`, a photo, a map); `"solid"` opts out inside a glass `UIProvider`. |
| `date` | `Date \| string \| number` | Required |
| `title?` | `string` |  |
| `mood?` | `MoodLevel` |  |
| `tags?` | `string[]` |  |
| `children?` | `ReactNode` |  |
| `actions?` | `ReactNode` | Buttons at the end (edit, share …). |
| `className?` | `string` | Extra class on the root element. |
| `style?` | `CSSProperties` | Inline style on the root element. |

#### IconButton

| Prop | Type | Notes |
| --- | --- | --- |
| `icon` | `IconName` | Required |
| `label` | `string` | Accessible name and tooltip (`aria-label` and `title`); `aria-label` or `title` override them. |
| `variant?` | `"soft" \| "solid" \| "outline" \| "ghost"` |  |
| `size?` | `"sm" \| "md" \| "lg"` |  |
| `type?` | `"button" \| "submit" \| "reset"` |  |
| `onClick?` | `(e: MouseEvent<HTMLButtonElement>) => void` |  |
| `disabled?` | `boolean` |  |
| `asChild?` | `boolean` | Render the single child element (a link) with the button's look; the icon is placed inside it. |
| `children?` | `ReactNode` |  |
| `id?` | `string` |  |
| `name?` | `string` | Form field name and value, sent with the form when this button submits it. |
| `value?` | `string` |  |
| `form?` | `string` | The id of the form this button belongs to, when it sits outside it. |
| `title?` | `string` |  |
| `tabIndex?` | `number` |  |
| `autoFocus?` | `boolean` |  |
| `aria-label?` | `string` |  |
| `aria-labelledby?` | `string` |  |
| `aria-describedby?` | `string` |  |
| `aria-expanded?` | `boolean \| "true" \| "false"` | For disclosure and menu triggers: whether what the button controls is open. |
| `aria-controls?` | `string` |  |
| `aria-haspopup?` | `boolean \| "true" \| "false" \| "menu" \| "listbox" \| "tree" \| "grid" \| "dialog"` |  |
| `aria-pressed?` | `boolean \| "true" \| "false" \| "mixed"` | For toggle buttons. |
| `aria-current?` | `boolean \| "true" \| "false" \| "page" \| "step" \| "location" \| "date" \| "time"` |  |
| `className?` | `string` | Extra class on the root element. |
| `style?` | `CSSProperties` | Inline style on the root element. |


## Goal Card

> A goal with its progress toward a target, a due date, milestones and a note.

Component · Life · Halo kit · [Live page](https://ui.twentyfirst.media/halo/components/GoalCard/)

A goal with its progress toward a target, a due date, milestones and a note.

- `format` shows value and target as a number (with `unit`), money or a percentage.
- The bar is a progressbar with the value in words ("€3,100 of €5,000").

### Example

```tsx
import type * as React from "react";
import { GoalCard } from "@twentyfirstmedia/halo";

export default function Preview() {
  return (
    <div
      className="tf-grid"
      style={
        {
          "--cols": "repeat(2, minmax(0, 1fr))",
          "--cols-sm": "1fr",
          gap: 16,
        } as React.CSSProperties
      }
    >
      <GoalCard
        title="Emergency fund"
        icon="wallet"
        tint="mint"
        value={3100}
        target={5000}
        format="money"
        due={new Date(2027, 5, 1)}
        note="€275 a month keeps you on track."
      />
      <GoalCard
        title="Run a half marathon"
        icon="trend"
        tint="blush"
        value={14}
        target={21}
        unit="km"
        due={new Date(2027, 3, 26)}
        milestones={[
          { label: "5 km without a break", done: true },
          { label: "10 km under an hour", done: true },
          { label: "15 km long run" },
          { label: "Race day" },
        ]}
      />
    </div>
  );
}
```

### Props

#### GoalCard

| Prop | Type | Notes |
| --- | --- | --- |
| `surface?` | `Surface` | `"glass"`: translucent glass over a backdrop (`Ambient`, a photo, a map); `"solid"` opts out inside a glass `UIProvider`. |
| `title` | `string` | Required |
| `value` | `number` | Required |
| `target` | `number` | Required |
| `format?` | `"number" \| "money" \| "percent"` | How to show value and target (default number). |
| `unit?` | `string` | Unit after numbers ("km", "books"). |
| `currency?` | `string` |  |
| `due?` | `Date \| string \| number` |  |
| `icon?` | `IconName` |  |
| `tint?` | `Tint` |  |
| `milestones?` | `{ label: string; done?: boolean }[]` |  |
| `note?` | `ReactNode` | A note under the progress ("€250 a month keeps you on track"). |
| `className?` | `string` | Extra class on the root element. |
| `style?` | `CSSProperties` | Inline style on the root element. |


## Insight Card

> Something the assistant noticed: what, where it comes from, why it is shown and what to do.

Component · Life · Halo kit · [Live page](https://ui.twentyfirst.media/halo/components/InsightCard/)

Something the assistant noticed: what, where it comes from, why it is shown and what to do.

- `sources` are chips like the ones under chat answers; `why` folds away behind "Why am I seeing
  this?".
- `onAccept` (with `acceptLabel`), `onSnooze` and `onDismiss` add the actions.
- `tone` sets the accent: info, success, warning or highlight.

### Example

```tsx
import { InsightCard } from "@twentyfirstmedia/halo";

export default function Preview() {
  return (
    <div className="tf-col" style={{ gap: 16, maxWidth: 560 }}>
      <InsightCard
        tone="warning"
        icon="zap"
        meta="Money · 2 h ago"
        title="Your electricity bill went up 18 %"
        sources={[
          { title: "Bank account · Nov debit", icon: "card" },
          { title: "Tariff letter (PDF)", icon: "file" },
        ]}
        why="Your monthly debit rose from €84 to €99 in November. The new tariff letter from your supplier names a price change from 1 November."
        acceptLabel="Compare tariffs"
        onAccept={() => {}}
        onSnooze={() => {}}
        onDismiss={() => {}}
      >
        At your usage, switching to a fixed tariff would save about €140 a year.
      </InsightCard>
      <InsightCard
        tone="success"
        icon="moon"
        meta="Sleep · this week"
        title="You slept 40 minutes longer on walk days"
        sources={[
          { title: "Watch · sleep", icon: "moon" },
          { title: "Habits", icon: "check" },
        ]}
        onDismiss={() => {}}
      >
        On the five days with a morning walk you fell asleep earlier and woke up less often.
      </InsightCard>
    </div>
  );
}
```

### Props

#### InsightCard

| Prop | Type | Notes |
| --- | --- | --- |
| `surface?` | `Surface` | `"glass"`: translucent glass over a backdrop (`Ambient`, a photo, a map); `"solid"` opts out inside a glass `UIProvider`. |
| `title` | `string` | Required |
| `children?` | `ReactNode` |  |
| `icon?` | `IconName` |  |
| `tone?` | `"info" \| "success" \| "warning" \| "highlight"` |  |
| `meta?` | `ReactNode` | Above the title: area and time ("Money · 2 h ago"). |
| `sources?` | `Source[]` | Where the insight comes from, as chips (like chat sources). |
| `why?` | `ReactNode` | Why the assistant shows it; folded away behind "Why am I seeing this?". |
| `onAccept?` | `() => void` |  |
| `acceptLabel?` | `string` |  |
| `onSnooze?` | `() => void` |  |
| `onDismiss?` | `() => void` |  |
| `className?` | `string` | Extra class on the root element. |
| `style?` | `CSSProperties` | Inline style on the root element. |


## Consent List

> What each connected source lets the assistant read or do: one card per source with its purpose, last use and a switch per scope, plus "Revoke access".

Component · Life · Halo kit · [Live page](https://ui.twentyfirst.media/halo/components/ConsentList/)

What each connected source lets the assistant read or do: one card per source with its purpose,
last use and a switch per scope, plus "Revoke access".

- Scopes marked `required` are shown but cannot be switched off.
- Switches are named "Bank account: Transactions" for screen readers.

### Example

```tsx
import * as React from "react";
import { ConsentList } from "@twentyfirstmedia/halo";
import type { ConsentConnector } from "@twentyfirstmedia/halo";

export default function Preview() {
  const [list, setList] = React.useState<ConsentConnector[]>([
    {
      id: "bank",
      name: "Bank account",
      icon: "card",
      purpose: "Finds bills, subscriptions and price changes; never moves money.",
      lastUsed: new Date(2026, 10, 12),
      scopes: [
        { id: "balance", label: "Balances", granted: true, required: true },
        { id: "tx", label: "Transactions", description: "The last 12 months", granted: true },
        {
          id: "pay",
          label: "Prepare transfers",
          description: "You approve each one",
          granted: false,
        },
      ],
    },
    {
      id: "health",
      name: "Health data",
      icon: "heartPulse",
      purpose: "Sleep, activity and vitals for your daily summary. Stays on this device.",
      lastUsed: new Date(2026, 10, 13),
      scopes: [
        { id: "sleep", label: "Sleep", granted: true },
        { id: "activity", label: "Activity", granted: true },
        { id: "vitals", label: "Heart rate and blood pressure", granted: false },
      ],
    },
  ]);
  return (
    <div style={{ maxWidth: 560 }}>
      <ConsentList
        connectors={list}
        onScopeChange={(c, s, granted) =>
          setList((all) =>
            all.map((x) =>
              x.id === c
                ? { ...x, scopes: x.scopes.map((y) => (y.id === s ? { ...y, granted } : y)) }
                : x,
            ),
          )
        }
        onRevoke={(c) => setList((all) => all.filter((x) => x.id !== c))}
      />
    </div>
  );
}
```

### Props

#### ConsentList

| Prop | Type | Notes |
| --- | --- | --- |
| `surface?` | `Surface` | `"glass"`: translucent glass over a backdrop (`Ambient`, a photo, a map); `"solid"` opts out inside a glass `UIProvider`. |
| `connectors` | `ConsentConnector[]` | Required |
| `onScopeChange?` | `(connectorId: string, scopeId: string, granted: boolean) => void` |  |
| `onRevoke?` | `(connectorId: string) => void` |  |
| `label?` | `string` | Accessible name (default "Data access"). |
| `className?` | `string` | Extra class on the root element. |
| `style?` | `CSSProperties` | Inline style on the root element. |


## Budget List

> Spending per category against its limit: spent and limit, a bar, and what is left or over in words.

Component · Life · Halo kit · [Live page](https://ui.twentyfirst.media/halo/components/BudgetList/)

Spending per category against its limit: spent and limit, a bar, and what is left or over in words.

- The bar turns butter from 85 % and blush when over; "€42 over" says it in words too.
- `onSelect(id)` makes each category a button (to show its transactions).

### Example

```tsx
import { BudgetList, Panel } from "@twentyfirstmedia/halo";

export default function Preview() {
  return (
    <Panel title="November budgets" subtitle="17 days left" style={{ maxWidth: 560 }}>
      <BudgetList
        onSelect={() => {}}
        categories={[
          { id: "food", label: "Groceries", icon: "cart", tint: "mint", spent: 312, limit: 450 },
          { id: "eat", label: "Eating out", icon: "star", tint: "butter", spent: 168, limit: 180 },
          { id: "move", label: "Transport", icon: "map", tint: "sky", spent: 96, limit: 120 },
          {
            id: "fun",
            label: "Fun & hobbies",
            icon: "sparkle",
            tint: "lilac",
            spent: 142,
            limit: 100,
          },
        ]}
      />
    </Panel>
  );
}
```

### Props

#### BudgetList

| Prop | Type | Notes |
| --- | --- | --- |
| `categories` | `BudgetCategory[]` | Required |
| `currency?` | `string` |  |
| `onSelect?` | `(id: string) => void` | A category was picked (to show its transactions). |
| `label?` | `string` | Accessible name (default "Budgets"). |
| `className?` | `string` | Extra class on the root element. |
| `style?` | `CSSProperties` | Inline style on the root element. |

#### Panel

| Prop | Type | Notes |
| --- | --- | --- |
| `side?` | `boolean` |  |
| `title?` | `string` |  |
| `subtitle?` | `string` |  |
| `action?` | `ReactNode` |  |
| `children?` | `ReactNode` |  |
| `surface?` | `Surface` | `"glass"`: translucent glass over what is behind (maps, 3D, video, photos); `"solid"` opts out inside a glass `UIProvider`. |
| `className?` | `string` | Extra class on the root element. |
| `style?` | `CSSProperties` | Inline style on the root element. |


## Subscription List

> Recurring payments with their next charge, trial and cancelled states, and what they cost together a month and a year.

Component · Life · Halo kit · [Live page](https://ui.twentyfirst.media/halo/components/SubscriptionList/)

Recurring payments with their next charge, trial and cancelled states, and what they cost together
a month and a year.

- `period` is `week`, `month` or `year`; the totals convert every active item.
- `onManage(id)` adds a "Manage {name}" button (cancel, change plan …).

### Example

```tsx
import { Panel, SubscriptionList } from "@twentyfirstmedia/halo";

export default function Preview() {
  return (
    <Panel title="Subscriptions" subtitle="6 active" style={{ maxWidth: 560 }}>
      <SubscriptionList
        onManage={() => {}}
        items={[
          {
            id: "stream",
            name: "Streaming",
            icon: "play",
            amount: 13.99,
            period: "month",
            next: new Date(2026, 10, 18),
            category: "Entertainment",
          },
          {
            id: "music",
            name: "Music",
            icon: "monitor",
            amount: 10.99,
            period: "month",
            next: new Date(2026, 10, 21),
            category: "Entertainment",
          },
          {
            id: "cloud",
            name: "Cloud storage",
            icon: "folder",
            amount: 99,
            period: "year",
            next: new Date(2027, 2, 4),
            category: "Work",
          },
          {
            id: "gym",
            name: "Gym",
            icon: "zap",
            amount: 34.9,
            period: "month",
            next: new Date(2026, 11, 1),
            category: "Health",
          },
          {
            id: "news",
            name: "News",
            icon: "book",
            amount: 2.5,
            period: "week",
            status: "trial",
            next: new Date(2026, 10, 20),
          },
          {
            id: "maps",
            name: "Maps pro",
            icon: "map",
            amount: 4.99,
            period: "month",
            status: "cancelled",
          },
        ]}
      />
    </Panel>
  );
}
```

### Props

#### SubscriptionList

| Prop | Type | Notes |
| --- | --- | --- |
| `items` | `Subscription[]` | Required |
| `currency?` | `string` |  |
| `onManage?` | `(id: string) => void` | "Manage" on a subscription (cancel, change plan …). |
| `totals?` | `boolean` | Hide the monthly and yearly totals. |
| `label?` | `string` | Accessible name (default "Subscriptions"). |
| `className?` | `string` | Extra class on the root element. |
| `style?` | `CSSProperties` | Inline style on the root element. |

#### Panel

| Prop | Type | Notes |
| --- | --- | --- |
| `side?` | `boolean` |  |
| `title?` | `string` |  |
| `subtitle?` | `string` |  |
| `action?` | `ReactNode` |  |
| `children?` | `ReactNode` |  |
| `surface?` | `Surface` | `"glass"`: translucent glass over what is behind (maps, 3D, video, photos); `"solid"` opts out inside a glass `UIProvider`. |
| `className?` | `string` | Extra class on the root element. |
| `style?` | `CSSProperties` | Inline style on the root element. |


## Net Worth Card

> What you own minus what you owe: the total, its change and trend, and the assets and liabilities behind it.

Component · Life · Halo kit · [Live page](https://ui.twentyfirst.media/halo/components/NetWorthCard/)

What you own minus what you owe: the total, its change and trend, and the assets and liabilities
behind it.

### Example

```tsx
import { NetWorthCard } from "@twentyfirstmedia/halo";

export default function Preview() {
  return (
    <NetWorthCard
      style={{ maxWidth: 620 }}
      change={1240}
      changeLabel="since October"
      history={[38200, 38900, 39400, 39100, 40300, 41000, 41800, 42900]}
      assets={[
        { label: "Current account", value: 4820, icon: "card" },
        { label: "Savings", value: 12600, icon: "wallet" },
        { label: "ETF portfolio", value: 31450, icon: "chart" },
        { label: "Pension fund", value: 9800, icon: "shield" },
      ]}
      liabilities={[
        { label: "Car loan", value: 11200, icon: "key" },
        { label: "Credit card", value: 670, icon: "card" },
      ]}
    />
  );
}
```

### Props

#### NetWorthCard

| Prop | Type | Notes |
| --- | --- | --- |
| `surface?` | `Surface` | `"glass"`: translucent glass over a backdrop (`Ambient`, a photo, a map); `"solid"` opts out inside a glass `UIProvider`. |
| `assets` | `{ label: string; value: number; icon?: IconName }[]` | Required |
| `liabilities?` | `{ label: string; value: number; icon?: IconName }[]` |  |
| `history?` | `number[]` | Net worth over time, oldest first. |
| `change?` | `number` | Change over `changeLabel` (e.g. +1,240 "since October"). |
| `changeLabel?` | `string` |  |
| `currency?` | `string` |  |
| `title?` | `string` |  |
| `className?` | `string` | Extra class on the root element. |
| `style?` | `CSSProperties` | Inline style on the root element. |


## Deadline List

> Bills, renewals, notice periods and expiring documents in date order, each with "Today", "In 12 days" or "Overdue by 3 days" in words.

Component · Life · Halo kit · [Live page](https://ui.twentyfirst.media/halo/components/DeadlineList/)

Bills, renewals, notice periods and expiring documents in date order, each with "Today",
"In 12 days" or "Overdue by 3 days" in words.

- Set `today` for server rendering and stable output; `soon` (default 14 days) marks what is near.
- `onDone(id)` adds "Mark … done"; done items stay, struck through.

### Example

```tsx
import * as React from "react";
import { DeadlineList, Panel } from "@twentyfirstmedia/halo";
import type { DeadlineItem } from "@twentyfirstmedia/halo";

const today = new Date(2026, 10, 13);

export default function Preview() {
  const [items, setItems] = React.useState<DeadlineItem[]>([
    {
      id: "tax",
      title: "Income tax return",
      kind: "Tax",
      date: new Date(2026, 10, 10),
      note: "Extension possible",
    },
    { id: "car", title: "Car inspection", kind: "Car", date: new Date(2026, 10, 13) },
    { id: "gym", title: "Gym: last day to cancel", kind: "Contract", date: new Date(2026, 10, 20) },
    { id: "rent", title: "Rent", kind: "Bill", date: new Date(2026, 11, 1), amount: 1150 },
    {
      id: "id",
      title: "Passport renewal",
      kind: "Document",
      date: new Date(2027, 1, 14),
      note: "Lena",
    },
    {
      id: "elec",
      title: "Electricity",
      kind: "Bill",
      date: new Date(2026, 10, 2),
      amount: 99,
      done: true,
    },
  ]);
  return (
    <Panel title="Deadlines" subtitle="Next 90 days" style={{ maxWidth: 620 }}>
      <DeadlineList
        today={today}
        items={items}
        onDone={(id) => setItems((all) => all.map((d) => (d.id === id ? { ...d, done: true } : d)))}
      />
    </Panel>
  );
}
```

### Props

#### DeadlineList

| Prop | Type | Notes |
| --- | --- | --- |
| `items` | `DeadlineItem[]` | Required |
| `today?` | `Date \| string \| number` | The day to count from (default: now). Set it for server rendering and stable output. |
| `soon?` | `number` | Days ahead that count as soon (default 14). |
| `currency?` | `string` |  |
| `onDone?` | `(id: string) => void` |  |
| `label?` | `string` | Accessible name (default "Deadlines"). |
| `className?` | `string` | Extra class on the root element. |
| `style?` | `CSSProperties` | Inline style on the root element. |

#### Panel

| Prop | Type | Notes |
| --- | --- | --- |
| `side?` | `boolean` |  |
| `title?` | `string` |  |
| `subtitle?` | `string` |  |
| `action?` | `ReactNode` |  |
| `children?` | `ReactNode` |  |
| `surface?` | `Surface` | `"glass"`: translucent glass over what is behind (maps, 3D, video, photos); `"solid"` opts out inside a glass `UIProvider`. |
| `className?` | `string` | Extra class on the root element. |
| `style?` | `CSSProperties` | Inline style on the root element. |


## Policy Card

> One insurance policy: type and insurer, sum insured, premium, deductible, policy number, renewal date and status (active, pending, expiring, lapsed), with room for actions.

Component · Life · Halo kit · [Live page](https://ui.twentyfirst.media/halo/components/PolicyCard/)

One insurance policy: type and insurer, sum insured, premium, deductible, policy number, renewal
date and status (active, pending, expiring, lapsed), with room for actions.

- `maskNumber` shows only the last four characters of the policy number.

### Example

```tsx
import type * as React from "react";
import { Button, PolicyCard } from "@twentyfirstmedia/halo";

export default function Preview() {
  return (
    <div
      className="tf-grid"
      style={
        {
          "--cols": "repeat(2, minmax(0, 1fr))",
          "--cols-sm": "1fr",
          gap: 16,
        } as React.CSSProperties
      }
    >
      <PolicyCard
        type="Household contents"
        insurer="Nordhafen Insurance"
        icon="home"
        tint="sky"
        coverage={65000}
        premium={{ amount: 9.8, period: "month" }}
        deductible={150}
        policyNumber="HR-2207-551938"
        maskNumber
        renews={new Date(2027, 2, 1)}
        actions={
          <>
            <Button size="sm" variant="ghost" icon="file">
              Documents
            </Button>
            <Button size="sm" variant="secondary">
              Report a claim
            </Button>
          </>
        }
      />
      <PolicyCard
        type="Car (comprehensive)"
        insurer="Alpenland Direct"
        icon="key"
        tint="butter"
        coverage="Unlimited liability"
        premium={{ amount: 412, period: "year" }}
        deductible={300}
        status="expiring"
        renews={new Date(2026, 11, 31)}
      />
    </div>
  );
}
```

### Props

#### PolicyCard

| Prop | Type | Notes |
| --- | --- | --- |
| `surface?` | `Surface` | `"glass"`: translucent glass over a backdrop (`Ambient`, a photo, a map); `"solid"` opts out inside a glass `UIProvider`. |
| `type` | `string` | The kind of insurance: "Household contents", "Liability" … |
| `insurer` | `string` | Required |
| `icon?` | `IconName` |  |
| `tint?` | `Tint` |  |
| `policyNumber?` | `string` |  |
| `maskNumber?` | `boolean` | Show only the last four characters of the policy number. |
| `coverage?` | `number \| ReactNode` | Sum insured: a number (money) or text ("unlimited"). |
| `premium?` | `{ amount: number; period: "month" \| "quarter" \| "year" }` |  |
| `deductible?` | `number` |  |
| `renews?` | `Date \| string \| number` |  |
| `status?` | `"active" \| "pending" \| "expiring" \| "lapsed"` |  |
| `currency?` | `string` |  |
| `actions?` | `ReactNode` | Buttons at the foot (documents, report a claim …). |
| `className?` | `string` | Extra class on the root element. |
| `style?` | `CSSProperties` | Inline style on the root element. |

#### Button

| Prop | Type | Notes |
| --- | --- | --- |
| `variant?` | `"primary" \| "secondary" \| "soft" \| "ghost" \| "danger" \| "danger-solid"` |  |
| `size?` | `"md" \| "sm"` |  |
| `icon?` | `IconName` |  |
| `iconRight?` | `IconName` |  |
| `disabled?` | `boolean` |  |
| `type?` | `"button" \| "submit" \| "reset"` |  |
| `onClick?` | `(e: MouseEvent<HTMLButtonElement>) => void` |  |
| `children?` | `ReactNode` |  |
| `asChild?` | `boolean` | Render the single child element (a link, a router Link) with the button's look instead of a <button>. |
| `id?` | `string` |  |
| `name?` | `string` | Form field name and value, sent with the form when this button submits it. |
| `value?` | `string` |  |
| `form?` | `string` | The id of the form this button belongs to, when it sits outside it. |
| `title?` | `string` |  |
| `tabIndex?` | `number` |  |
| `autoFocus?` | `boolean` |  |
| `aria-label?` | `string` |  |
| `aria-labelledby?` | `string` |  |
| `aria-describedby?` | `string` |  |
| `aria-expanded?` | `boolean \| "true" \| "false"` | For disclosure and menu triggers: whether what the button controls is open. |
| `aria-controls?` | `string` |  |
| `aria-haspopup?` | `boolean \| "true" \| "false" \| "menu" \| "listbox" \| "tree" \| "grid" \| "dialog"` |  |
| `aria-pressed?` | `boolean \| "true" \| "false" \| "mixed"` | For toggle buttons. |
| `aria-current?` | `boolean \| "true" \| "false" \| "page" \| "step" \| "location" \| "date" \| "time"` |  |
| `className?` | `string` | Extra class on the root element. |
| `style?` | `CSSProperties` | Inline style on the root element. |


## Coverage Matrix

> Life risks and whether a policy covers them: covered, partly or not covered, with the policy and a note, and a count of each above the table.

Component · Life · Halo kit · [Live page](https://ui.twentyfirst.media/halo/components/CoverageMatrix/)

Life risks and whether a policy covers them: covered, partly or not covered, with the policy and a
note, and a count of each above the table. Status is a shape and a word, never colour alone.

### Example

```tsx
import { CoverageMatrix, Panel } from "@twentyfirstmedia/halo";

export default function Preview() {
  return (
    <Panel title="Are we covered?" subtitle="Your household, 6 risks" style={{ maxWidth: 720 }}>
      <CoverageMatrix
        rows={[
          {
            id: "liab",
            risk: "Damage to others",
            status: "covered",
            policy: "Personal liability",
            note: "Up to €10 m, family included",
          },
          {
            id: "home",
            risk: "Burglary and fire at home",
            status: "covered",
            policy: "Household contents",
          },
          {
            id: "bike",
            risk: "Bike theft",
            status: "partial",
            policy: "Household contents",
            note: "Only up to €1,000; the e-bike is worth €3,200",
          },
          {
            id: "work",
            risk: "Unable to work",
            status: "none",
            note: "The biggest gap for a family with one income",
          },
          {
            id: "legal",
            risk: "Legal costs",
            status: "partial",
            policy: "Legal protection",
            note: "Traffic only",
          },
          { id: "travel", risk: "Illness abroad", status: "covered", policy: "Travel health" },
        ]}
      />
    </Panel>
  );
}
```

### Props

#### CoverageMatrix

| Prop | Type | Notes |
| --- | --- | --- |
| `rows` | `CoverageRow[]` | Required |
| `label?` | `string` | Accessible name and caption (default "Coverage"). |
| `className?` | `string` | Extra class on the root element. |
| `style?` | `CSSProperties` | Inline style on the root element. |

#### Panel

| Prop | Type | Notes |
| --- | --- | --- |
| `side?` | `boolean` |  |
| `title?` | `string` |  |
| `subtitle?` | `string` |  |
| `action?` | `ReactNode` |  |
| `children?` | `ReactNode` |  |
| `surface?` | `Surface` | `"glass"`: translucent glass over what is behind (maps, 3D, video, photos); `"solid"` opts out inside a glass `UIProvider`. |
| `className?` | `string` | Extra class on the root element. |
| `style?` | `CSSProperties` | Inline style on the root element. |


## Claim Timeline

> An insurance claim from report to payout: steps that are done, current, still to come or failed, with dates and notes, and the amount claimed.

Component · Life · Halo kit · [Live page](https://ui.twentyfirst.media/halo/components/ClaimTimeline/)

An insurance claim from report to payout: steps that are done, current, still to come or failed,
with dates and notes, and the amount claimed.

### Example

```tsx
import { ClaimTimeline, Panel } from "@twentyfirstmedia/halo";

export default function Preview() {
  return (
    <Panel style={{ maxWidth: 560 }}>
      <ClaimTimeline
        title="Water damage in the kitchen"
        meta="Claim 2026-4418 · Nordhafen Insurance"
        amount={2340}
        steps={[
          {
            label: "Reported",
            date: new Date(2026, 9, 28),
            state: "done",
            note: "Photos and invoice uploaded",
          },
          { label: "Assessor visit", date: new Date(2026, 10, 4), state: "done" },
          { label: "Decision", state: "current", note: "Usually within 10 working days" },
          { label: "Payout", state: "todo" },
        ]}
      />
    </Panel>
  );
}
```

### Props

#### ClaimTimeline

| Prop | Type | Notes |
| --- | --- | --- |
| `title` | `string` | Required |
| `meta?` | `ReactNode` | Reference and insurer under the title. |
| `amount?` | `number` |  |
| `currency?` | `string` |  |
| `steps` | `ClaimStep[]` | Required |
| `className?` | `string` | Extra class on the root element. |
| `style?` | `CSSProperties` | Inline style on the root element. |

#### Panel

| Prop | Type | Notes |
| --- | --- | --- |
| `side?` | `boolean` |  |
| `title?` | `string` |  |
| `subtitle?` | `string` |  |
| `action?` | `ReactNode` |  |
| `children?` | `ReactNode` |  |
| `surface?` | `Surface` | `"glass"`: translucent glass over what is behind (maps, 3D, video, photos); `"solid"` opts out inside a glass `UIProvider`. |
| `className?` | `string` | Extra class on the root element. |
| `style?` | `CSSProperties` | Inline style on the root element. |


## Document List

> Important papers (IDs, contracts, policies, certificates) with category, holder and expiry: "Expired", "Expires in 19 days" or "Valid until May 2031".

Component · Life · Halo kit · [Live page](https://ui.twentyfirst.media/halo/components/DocumentList/)

Important papers (IDs, contracts, policies, certificates) with category, holder and expiry:
"Expired", "Expires in 19 days" or "Valid until May 2031".

- Set `today` for server rendering; `soon` (default 60 days) marks documents to renew.
- `onOpen(id)` makes each document a button.

### Example

```tsx
import { DocumentList, Panel, registerIcons } from "@twentyfirstmedia/halo";
import { idCard } from "@twentyfirstmedia/ui-core/icons";

registerIcons({ idCard });

export default function Preview() {
  return (
    <Panel title="Documents" subtitle="Family" style={{ maxWidth: 620 }}>
      <DocumentList
        today={new Date(2026, 10, 13)}
        onOpen={() => {}}
        documents={[
          {
            id: "pass",
            title: "Passport",
            category: "ID",
            icon: "idCard",
            holder: "Lena",
            expires: new Date(2026, 11, 2),
          },
          {
            id: "card",
            title: "ID card",
            category: "ID",
            icon: "idCard",
            holder: "Mara",
            expires: new Date(2031, 4, 1),
          },
          {
            id: "lic",
            title: "Driving licence",
            category: "ID",
            icon: "idCard",
            holder: "Jonas",
            expires: new Date(2026, 9, 1),
          },
          {
            id: "rent",
            title: "Rental contract",
            category: "Home",
            icon: "home",
            meta: "PDF · 1.2 MB",
          },
          {
            id: "ins",
            title: "Household contents policy",
            category: "Insurance",
            icon: "shield",
            meta: "PDF · 240 KB",
          },
        ]}
      />
    </Panel>
  );
}
```

### Props

#### DocumentList

| Prop | Type | Notes |
| --- | --- | --- |
| `documents` | `LifeDocument[]` | Required |
| `today?` | `Date \| string \| number` | The day to count expiry from (default: now). |
| `soon?` | `number` | Days ahead that count as expiring soon (default 60). |
| `onOpen?` | `(id: string) => void` |  |
| `label?` | `string` | Accessible name (default "Documents"). |
| `className?` | `string` | Extra class on the root element. |
| `style?` | `CSSProperties` | Inline style on the root element. |

#### Panel

| Prop | Type | Notes |
| --- | --- | --- |
| `side?` | `boolean` |  |
| `title?` | `string` |  |
| `subtitle?` | `string` |  |
| `action?` | `ReactNode` |  |
| `children?` | `ReactNode` |  |
| `surface?` | `Surface` | `"glass"`: translucent glass over what is behind (maps, 3D, video, photos); `"solid"` opts out inside a glass `UIProvider`. |
| `className?` | `string` | Extra class on the root element. |
| `style?` | `CSSProperties` | Inline style on the root element. |


# Patterns

- [AI Chat](https://ui.twentyfirst.media/halo/patterns/AIChatScreen.md): A complete screen built from AgentMark, AgentStatus, ApprovalCard, ChatMessage and 6 more components.
- [Agent Builder](https://ui.twentyfirst.media/halo/patterns/AgentBuilderScreen.md): A complete screen built from Button, ChatMessage, Combobox, Composer and 7 more components.
- [Analytics](https://ui.twentyfirst.media/halo/patterns/AnalyticsScreen.md): A complete screen built from AppShell, BarChart, Button, CountUp and 10 more components.
- [Auth Card](https://ui.twentyfirst.media/halo/patterns/AuthCard.md): Centered card for sign-in, sign-up, password reset, two-step codes and invites.
- [Billing](https://ui.twentyfirst.media/halo/patterns/BillingScreen.md): A complete screen built from AppShell, Avatar, Badge, BarChart and 9 more components.
- [Board](https://ui.twentyfirst.media/halo/patterns/BoardScreen.md): A complete screen built from AppShell, AvatarStack, Badge, Button and 6 more components.
- [Calendar](https://ui.twentyfirst.media/halo/patterns/CalendarScreen.md): A complete screen built from AppShell, Button, EventCard, IconButton and 4 more components.
- [Customers](https://ui.twentyfirst.media/halo/patterns/CustomersScreen.md): A complete screen built from Avatar, Badge, Drawer, IconButton and 9 more components.
- [Dashboard](https://ui.twentyfirst.media/halo/patterns/Dashboard.md): A complete screen built from AppShell, Badge, Button, Card and 10 more components.
- [Files](https://ui.twentyfirst.media/halo/patterns/FilesScreen.md): A complete screen built from Chip, CommandPalette, FileCard, IconButton and 6 more components.
- [Inbox](https://ui.twentyfirst.media/halo/patterns/InboxScreen.md): A complete screen built from AppShell, Avatar, Badge, Button and 9 more components.
- [Invite Modal](https://ui.twentyfirst.media/halo/patterns/InviteModalScreen.md): A complete screen built from AppShell, Avatar, Badge, Button and 8 more components.
- [Invoice](https://ui.twentyfirst.media/halo/patterns/InvoiceScreen.md): A complete screen built from Button, IconButton, InvoicePreview, PageHeader and 5 more components.
- [Loading](https://ui.twentyfirst.media/halo/patterns/LoadingScreen.md): A complete screen built from AppShell, Badge, Button, Card and 7 more components.
- [Map](https://ui.twentyfirst.media/halo/patterns/MapScreen.md): A city map with glass controls floating over it: search and filters on top, map layers on the start side, the selected place with directions on the end side, zoom buttons and a dock.
- [Mobile Screens](https://ui.twentyfirst.media/halo/patterns/MobileScreens.md): A complete screen built from Avatar, Badge, Card, Chip and 7 more components.
- [People](https://ui.twentyfirst.media/halo/patterns/PeopleScreen.md): A complete screen built from AppShell, Avatar, Badge, Button and 11 more components.
- [Pricing](https://ui.twentyfirst.media/halo/patterns/PricingScreen.md): A complete screen built from PageHeader, Panel, PlanCard, Segmented and 3 more components.
- [Project](https://ui.twentyfirst.media/halo/patterns/ProjectScreen.md): A complete screen built from AppShell, Avatar, AvatarStack, Badge and 11 more components.
- [Settings](https://ui.twentyfirst.media/halo/patterns/SettingsScreen.md): A complete screen built from AppShell, Avatar, Button, IconButton and 7 more components.
- [Setup](https://ui.twentyfirst.media/halo/patterns/SetupScreen.md): A complete screen built from Button, IconButton, PageHeader, StatTile and 4 more components.
- [Shop](https://ui.twentyfirst.media/halo/patterns/ShopScreen.md): A complete screen built from Alert, Button, Funnel, PageHeader and 5 more components.
- [Sign In](https://ui.twentyfirst.media/halo/patterns/SignInScreen.md): A complete screen built from AvatarStack, Badge, Button, Checkbox and 6 more components.
- [Status](https://ui.twentyfirst.media/halo/patterns/StatusScreen.md): Full-page states for errors and interruptions: code "404", "500", "403", "maintenance", "offline", or your own title / text / icon / tint.
- [Storefront](https://ui.twentyfirst.media/halo/patterns/StorefrontScreen.md): A complete screen built from Breadcrumb, Button, IconButton, Price and 6 more components.
- [Wellbeing](https://ui.twentyfirst.media/halo/patterns/WellbeingScreen.md): A wellbeing dashboard in glass: sleep, streak and steps as tinted glass tiles, last nights' sleep, today's goal, mindful minutes, mood and habits, and a journal prompt, over the kit's ambient colours.
- [Workflow](https://ui.twentyfirst.media/halo/patterns/WorkflowScreen.md): A complete screen built from Badge, Button, Flow, IconButton and 6 more components.
- [Sidebar Shell](https://ui.twentyfirst.media/halo/patterns/SidebarShellScreen.md): The app shell with a labelled sidebar instead of the icon rail: AppShell navigation="sidebar".
- [Attached Sidebar](https://ui.twentyfirst.media/halo/patterns/AttachedSidebarScreen.md): A full-height app with the sidebar attached to the left edge (Sidebar variant="attached"): the calm layout for docs, settings and content tools.
- [Filter Sidebar](https://ui.twentyfirst.media/halo/patterns/FilterSidebarScreen.md): Results with their filters in a sidebar: Sidebar as="aside" turns the navigation into a complementary region for tools beside the content.
- [Health](https://ui.twentyfirst.media/halo/patterns/HealthScreen.md): A personal health page in the app shell with a sidebar: vitals with healthy ranges, an insight with its reason, activity rings, last night's sleep and today's medication.
- [Habits](https://ui.twentyfirst.media/halo/patterns/HabitsScreen.md): A daily check-in: the mood scale and a line for the journal, the week's habits, the latest entry and longer goals beside it.
- [Data Access](https://ui.twentyfirst.media/halo/patterns/DataAccessScreen.md): The privacy page of an AI-first app: per source, what the assistant may read and do, an insight that suggests revoking unused access, and a summary of what it did this month.
- [Money](https://ui.twentyfirst.media/halo/patterns/MoneyScreen.md): Household money in the app shell with a sidebar: net worth with its trend, an insight about a duplicate subscription, the month's budgets and the subscriptions beside them.
- [Insurance](https://ui.twentyfirst.media/halo/patterns/InsuranceScreen.md): A household's insurance: the policies, what is and is not covered, renewals and notice periods, and the open claim beside them.
- [Life Overview](https://ui.twentyfirst.media/halo/patterns/LifeOverviewScreen.md): The start page of an AI-first life app: what needs you today across health, money and papers, as insights with their reasons, the next deadlines, budgets, mood and activity.
- [Real estate](https://ui.twentyfirst.media/halo/patterns/real-estate.md): A listing search page: results toolbar with bulk actions, listings as cards or rows, a map with price pins, valuation, energy class and the photo gallery.

# Icons

thumbUp, thumbDown, arrowUp, heart, tag, cart, package, truck, plus, minus, check, x, more, search, bell, clock, eye, edit, trash, users, user, home, chart, mail, grid, share, menu, play, calendar, file, card, swap, send, download, book, chevronDown, chevronLeft, chevronRight, arrowUpRight, sparkle, filter, settings, lock, link, paperclip, star, flag, trend, globe, inbox, logout, moon, bot, code, branch, terminal, server, key, database, refresh, pause, archive, reply, shield, help, cpu, zap, folder, image, pin, map, upload, copy, bed, ruler, wallet, ban, list, layers, bold, italic, underline, olist, heading, quote, undo, redo, monitor, phone, expand, sun, cookie, webhook

## Icon library

Library icons need one registration before use: `import { registerIcons } from "@twentyfirstmedia/<kit>"; import { fingerprint, brandGithub } from "@twentyfirstmedia/<kit>/icons"; registerIcons({ fingerprint, brandGithub });` (or `registerIcons(ICON_LIBRARY)` for all). Custom elements (`@twentyfirstmedia/elements`) have them all registered.

- Actions: pencil, save, eyeOff, logIn, maximize2, minimize2, zoomIn, zoomOut, share2, link2, unlink, externalLink, rotateCcw, rotateCw, repeat, shuffle, listFilter, arrowUpDown, arrowDownWideNarrow, arrowUpNarrowWide, checkCheck, circlePlus, circleMinus, circleCheck, circleX, archiveRestore, clipboardCopy, clipboardPaste, scissors, pushpin, pinOff, bookmark, bookmarkCheck, bookmarkPlus, ellipsisVertical, gripVertical, gripHorizontal, mousePointerClick, pointer, hand, move, power, scanSearch
- Navigation and layout: arrowDown, arrowLeft, arrowRight, arrowDownLeft, arrowDownRight, arrowUpLeft, arrowLeftRight, arrowDownToLine, arrowUpFromLine, chevronUp, chevronsUpDown, chevronsLeft, chevronsRight, chevronsUp, chevronsDown, cornerDownLeft, cornerUpRight, moveHorizontal, moveVertical, panelLeft, panelRight, panelBottom, panelTop, layoutDashboard, layoutGrid, layoutList, layoutTemplate, columns2, rows2, squareKanban, appWindow, sidebar, compass, navigation, settings2, slidersHorizontal, slidersVertical, toggleLeft, toggleRight, panelLeftClose, arrowDownUp, arrowRightLeft, chevronsDownUp, grid3x3, squareSplitHorizontal
- Status and alerts: info, alertCircle, alertTriangle, alertOctagon, badgeCheck, badgeAlert, badgeInfo, circleDot, circle, square, squareCheck, squareX, loader, loaderCircle, hourglass, bellOff, bellRing, bellDot, listChecks, listTodo, starHalf, flagTriangleRight, siren, circleCheckBig, octagonX, circleSlash, starOff, dot, lifeBuoy
- Security and identity: fingerprint, scanFace, keyRound, lockOpen, lockKeyhole, shieldCheck, shieldAlert, shieldOff, shieldUser, shieldKeyhole, userCheck, userX, userPlus, userMinus, userRound, userCog, userLock, userKey, usersRound, idCard, contact, scanEye, scan, scanLine, qrCode, scanQrCode, smartphoneNfc, vault, fileLock, venetianMask, circleUser, shieldQuestionMark
- Communication: messageCircle, messageSquare, messagesSquare, messageCircleMore, messageSquareText, mailOpen, mailCheck, mailPlus, sendHorizontal, atSign, phoneCall, phoneIncoming, phoneOutgoing, phoneMissed, voicemail, video, videoOff, mic, micOff, headphones, headset, megaphone, speech, rss, hash, bookUser, smile, frown, meh, laugh, smilePlus, angry, languages, heartHandshake, messageSquarePlus, messageSquareOff, messageSquareDashed, mailMinus, forward, replyAll, phoneOff
- Files and documents: fileText, filePlus, fileMinus, fileCheck, fileX, fileSearch, fileCode, fileImage, fileVideoCamera, fileMusic, fileSpreadsheet, fileArchive, fileDown, fileUp, filePenLine, files, folderOpen, folderPlus, folderTree, folderLock, clipboard, clipboardCheck, clipboardList, notebook, notebookPen, bookOpen, library, scrollText, newspaper, stickyNote, printer, hardDrive, cloud, cloudUpload, cloudDownload, cloudOff, signature, fileBadge, folderInput, folderKanban, folderCog, fileQuestionMark, bookCheck
- Editing and text: penTool, penLine, eraser, highlighter, type, textCursorInput, aLargeSmall, strikethrough, textAlignStart, textAlignCenter, textAlignEnd, textAlignJustify, listIndentIncrease, listIndentDecrease, heading1, heading2, heading3, pilcrow, codeXml, braces, brackets, wandSparkles, crop, palette, pipette, paintbrush, brush, spellCheck, caseSensitive, table, table2, sigma, textQuote, baseline, imagePlus, letterB, diamond, shapes
- Media: images, camera, cameraOff, film, clapperboard, music, musicNote, disc3, volume, volume1, volume2, volumeX, circlePlay, circlePause, circleStop, skipBack, skipForward, rewind, fastForward, micVocal, radio, tv, cast, airplay, aperture, focus, galleryHorizontal, captions, audioLines, listMusic, imageOff, imageUp, imageDown
- Devices and connectivity: laptop, smartphone, tablet, watch, keyboard, mouse, wifi, wifiOff, bluetooth, battery, batteryCharging, batteryLow, batteryFull, plug, usb, cable, router, memoryStick, gamepad2, monitorSmartphone, satelliteDish, signal, antenna, nfc, powerOff, printerCheck, speaker, webcam
- Development and AI: bug, gitPullRequest, gitCommitHorizontal, gitMerge, gitFork, gitCompare, puzzle, activity, gauge, network, workflow, blocks, box, boxes, container, cloudCog, variable, squareFunction, regex, testTube, flaskConical, atom, brain, brainCircuit, sparkles, botMessageSquare, binary, fileBraces, squareTerminal, plugZap, rocket, databaseZap, brainCog, circuitBoard, scanText, textSearch, messageSquareCode, infinity, orbit, telescope, gitGraph, botOff, squareDashedMousePointer, mousePointer2
- Charts and data: trendDown, chartPie, chartLine, chartColumn, chartBar, chartArea, chartCandlestick, chartScatter, chartNoAxesColumn, chartSpline, presentation, target, percent, kanban, tableProperties, sheet, chartNoAxesColumnIncreasing
- Time and calendar: calendarDays, calendarCheck, calendarPlus, calendarX, calendarClock, calendarRange, calendarHeart, alarmClock, timer, timerReset, history, sunrise, sunset, clockAlert, clockCheck
- Commerce and finance: shoppingBag, shoppingBasket, store, receipt, receiptText, badgePercent, ticket, gift, coins, banknote, piggyBank, landmark, handCoins, euro, dollarSign, poundSterling, swissFranc, bitcoin, calculator, scale, handshake, briefcase, building, buildings, factory, warehouse, barcode, scanBarcode, packageCheck, packageOpen, award, trophy, medal, crown, gem, circleDollarSign, tags, packageSearch, gavel
- Places and travel: mapPin, mapPinned, locate, locateFixed, route, signpost, plane, planeTakeoff, trainFront, bus, car, bike, ship, fuel, hotel, tent, mountain, trees, treePine, earth, luggage, utensils, coffee, wine, beer, mapPlus, milestone, carTaxiFront, evCharger
- Home and real estate: housePlus, doorOpen, doorClosed, sofa, bath, showerHead, lamp, lightbulb, armchair, bedDouble, bedSingle, fence, hammer, wrench, drill, paintRoller, construction, thermometer, heater, airVent, solarPanel, flame, droplet, snowflake, wind, leaf, sprout, recycle, blinds, lampDesk, washingMachine, refrigerator, microwave, keySquare, rulerDimensionLine
- Weather and nature: cloudSun, cloudRain, cloudSnow, cloudLightning, cloudFog, umbrella, rainbow, moonStar, flower, flower2, pawPrint, dog, cat, bird, fish, feather, sunMoon, tornado, waves, earthLock, rabbit
- Health and people: heartPulse, stethoscope, pill, syringe, hospital, cross, accessibility, baby, personStanding, footprints, dumbbell, apple, handHeart, handHelping, graduationCap, school, glasses, shirt, cake, partyPopper, bandage, thermometerSun, weight, salad
- Maps and 3D: draftingCompass, crosshair, satellite, rotate3d, axis3d, move3d, scale3d, frame, spline, squareDashed, lasso, layers2, magnet
- Games: swords, sword, castle, pickaxe, axe, dices, dice5, skull, ghost, joystick, bomb, heartCrack, shieldHalf, chessKing, chessQueen, chessRook, chessBishop, chessKnight, chessPawn
- Brands: brandX, brandFacebook, brandInstagram, brandThreads, brandYoutube, brandTiktok, brandWhatsapp, brandTelegram, brandSignal, brandMessenger, brandDiscord, brandBluesky, brandMastodon, brandReddit, brandPinterest, brandSnapchat, brandTumblr, brandTwitch, brandVimeo, brandSpotify, brandSoundcloud, brandMedium, brandSubstack, brandPatreon, brandXing, brandWechat, brandLine, brandViber, brandGithub, brandGitlab, brandDribbble, brandBehance, brandFigma, brandNotion, brandNpm, brandDocker, brandVercel, brandStackoverflow, brandProducthunt, brandHuggingface, brandAnthropic, brandClaude, brandApple, brandGoogle, brandAndroid, brandDropbox, brandGoogledrive, brandZoom, brandTrello, brandPaypal, brandStripe, brandKlarna, brandVisa, brandMastercard, brandApplepay, brandGooglepay, brandAirbnb, brandTripadvisor, brandYelp, brandMeta, brandGoogleads, brandGoogleanalytics, brandGooglesearchconsole, brandTrustpilot, brandGooglegemini, brandMistralai, brandPerplexity, brandOllama, brandDeepseek, brandCursor, brandGithubcopilot, brandOpenrouter, brandReplicate, brandElevenlabs, brandLangchain, brandModelcontextprotocol, brandWoocommerce, brandShopify, brandWordpress, brandCloudflare, brandHetzner, brandSupabase, brandPostgresql, brandN8n, brandMake, brandZapier, brandBitcoin, brandEthereum, brandTether, brandCoinbase, brandBinance, brandRevolut, brandKick, brandKaspersky, brandVirustotal, brandLinkedin, brandMicrosoft, brandWindows, brandSlack, brandSkype, brandAmazon, brandOpenai