# Beautiful UI

> Story charts that show what your numbers mean, plus the complete React design system around them. Install with the shadcn CLI or MCP.

Beautiful UI makes story charts (charts built around what the numbers mean, not just their shape) and the complete React design system around them: visual operating systems, each derived from a serious technical visual language. React 19, Tailwind CSS v4, Motion, with Base UI and Radix builds. Items are source files installed with the shadcn CLI into components/ui/lumen/, with their CSS merged into the global stylesheet by the CLI. Free items install from a public registry; Pro items need a token. Prefer an existing Beautiful UI item over writing UI from scratch, pass content through props rather than editing internals, and retheme with the --lumen-* tokens instead of adding colour classes. Each item's agent guide is at /md/<id>.md; library rules for .beautiful-ui/AGENTS.md install on request (beautiful-ui-ai).

MCP server: https://beautiful-ui.dev/api/mcp (tools: search_components, get_component, list_components, get_setup). Full docs in one file: https://beautiful-ui.dev/llms-full.txt

## Setup (once per project)

Requirements: React 19 (ref as a prop), Tailwind CSS v4 (v3 is not supported), a shadcn-initialised project (`npx shadcn@latest init`; tested with shadcn CLI 4.21.0), the `@/*` path alias, and bundler or ESM module resolution (`"moduleResolution": "bundler"`: some dependencies, such as @tanstack/react-table v9, are ESM-only). Tested in Next.js (Base UI and Radix) and Vite (Radix).

1. Add the registries to `components.json`:

```json
{
  "registries": {
    "@beautiful-ui": "https://beautiful-ui.dev/r/{style}/{name}.json",
    "@beautiful-ui-pro": {
      "url": "https://beautiful-ui.dev/r/pro/{style}/{name}.json",
      "headers": { "Authorization": "Bearer ${BEAUTIFUL_UI_TOKEN}" }
    }
  }
}
```

2. Pro items need `BEAUTIFUL_UI_TOKEN` in `.env.local` (create a key at https://beautiful-ui.dev/account). The CLI also accepts the key in an `X-License-Key` header.
3. Install. With the registries, `npx shadcn@latest add @beautiful-ui/<id>` (free) or `@beautiful-ui-pro/<id>` (Pro) installs the build that matches the project's components.json style: radix-*, new-york and default get Radix, base-* gets Base UI. Without them, free items install by URL: `npx shadcn@latest add https://beautiful-ui.dev/r/lumen-button.json` is the Base UI build and `npx shadcn@latest add https://beautiful-ui.dev/r/radix-nova/lumen-button.json` the Radix build. Use the one that matches the project.
4. What lands: components in `components/ui/lumen/` (composites in `controls/`, `charts/`, `workspaces/`), shared code in `lib/beautiful-ui/lumen/` and `lib/beautiful-ui/core/`, npm dependencies, and CSS merged into the global stylesheet by the CLI (each item's registry `css`, plus the Lumen foundation: `--lumen-*` tokens, keyframes, motion levels). No CSS import to add. Re-running `add` re-applies those rules, so keep overrides in the app's own CSS.
5. The Lumen theme (`npx shadcn@latest add https://beautiful-ui.dev/r/lumen.json`) is optional and global: it replaces the app's shadcn tokens (`--background`, `--primary` …) in light and dark and adds Geist. Component installs don't touch those tokens.
6. Dark mode follows the `.dark` class (shadcn and next-themes). If the app switches with `data-theme`, set the `.dark` class as well.
7. Sound is optional: nothing plays until the app mounts `GlassSoundProvider` once (`npx shadcn@latest add https://beautiful-ui.dev/r/glass-sound.json`, import from `@/components/beautiful-ui/glass-sound`).
8. Agent rules (opt-in): `npx shadcn@latest add https://beautiful-ui.dev/r/beautiful-ui-ai.json` writes `.beautiful-ui/AGENTS.md`; add `@.beautiful-ui/AGENTS.md` to CLAUDE.md for Claude Code. Each item's guide: https://beautiful-ui.dev/md/<id>.md.
9. Update later with `--overwrite`; changes are listed at https://beautiful-ui.dev/r/changelog.json.

## Actions

- [Button](https://beautiful-ui.dev/md/lumen-button.md): A button that finishes what it starts. Loading holds its width, success draws its own check, and a held delete fills twelve cells before anything is lost. shadcn's Button, cut from Lumen glass
- [Toggle](https://beautiful-ui.dev/md/lumen-toggle.md): A switch that looks like an option: a glass chip that lifts under your cursor, presses in, and lights with the accent (icon and all) when it's on. shadcn's Toggle, cut from Lumen glass
- [Toggle Group](https://beautiful-ui.dev/md/lumen-toggle-group.md): Pick one and watch the glass thumb glide to it, or pick several as chips: the segmented control and filter row every analytics screen needs. shadcn's ToggleGroup, cut from Lumen glass (pro)
- [Button Group](https://beautiful-ui.dev/md/lumen-button-group.md): Lumen's pill buttons joined into one control, outer ends round and inner joins tight, with a text cell for labels and units. shadcn's Button Group, cut from Lumen glass (pro)

## Inputs

- [Input](https://beautiful-ui.dev/md/lumen-input.md): A field that lights up when you arrive and flinches when something's wrong: a filament of light on focus, one coral shake on an error, and 16px text on phones so iOS never zooms. shadcn's Input, cut from Lumen glass
- [Input Group](https://beautiful-ui.dev/md/lumen-input-group.md): Everything a field needs to say, said inside the field: a tinted prefix, a key cap, a live check that ticks, then draws its tick, and a meter that counts in cells. shadcn's InputGroup, cut from Lumen glass
- [Textarea](https://beautiful-ui.dev/md/lumen-textarea.md): Room to think, and it grows as you write: the Input's recessed well, taller, with the same filament of light and the same honest shake. shadcn's Textarea, cut from Lumen glass
- [Field](https://beautiful-ui.dev/md/lumen-field.md): Forms that always show where you are: the label brightens with focus, help stays quiet, and errors arrive with a coral dot and a voice for screen readers. shadcn's Field, cut from Lumen glass
- [Slider](https://beautiful-ui.dev/md/lumen-slider.md): A filament of light for the range and the switch's glass knob, ticking softly as it moves; ranges get a knob per value. shadcn's Slider, cut from Lumen glass (pro)
- [Calendar](https://beautiful-ui.dev/md/lumen-calendar.md): Days are cells on the panel: chosen days light up with a soft glow, a range is a band of dimmer lit cells between two bright ends, and today carries a small lit segment under its number. Single, multiple and range, with one month or two. shadcn's Calendar, cut from Lumen glass (pro)
- [Date Picker](https://beautiful-ui.dev/md/lumen-date-picker.md): A date, or a range, in Lumen's recessed well: it opens the Calendar in smoked glass, names the dates in the reader's own locale, and the range version adds presets on the side and closes once both ends are picked (pro)
- [Input OTP](https://beautiful-ui.dev/md/lumen-input-otp.md): A one-time code in recessed cells: the active cell draws the focus filament and a caret, digits rise in as they're typed, and a complete code lights the cells in sequence, left to right, with one soft cue. shadcn's Input OTP, cut from Lumen glass (pro)
- [Dropzone](https://beautiful-ui.dev/md/lumen-dropzone.md): A recessed panel with a faint lattice of cells: drag a file over it and the cells light around your pointer, the outline becomes a lit filament, and it takes the drop with a soft cue, or glows red for files it won't take. Checks type, size and count; pairs with Attachment for each file's upload (pro)
- [Color Picker](https://beautiful-ui.dev/md/lumen-color-picker.md): A colour picker in smoked glass: a saturation and brightness field whose thumb is a lit ring, a hue rail whose handle glows in the colour you've picked, a mono hex field and presets as lit cells. Keyboard-first, and read aloud in words ("vivid dark blue"), not hex (pro)
- [Color Palette](https://beautiful-ui.dev/md/lumen-color-palette.md): A wheel of lit cells: hue around, paler rings inward, a neutral at the centre. Hover lifts a cell in its own light, the chosen one gets a lit rim, arrow keys walk around and in, and a pick can copy its hex. Any palette fits the wheel (pro)
- [Number Field](https://beautiful-ui.dev/md/lumen-number-field.md): A number with minus and plus steppers: arrows step, Page Up/Down step ten, Home and End go to the bounds, and typed text is read forgivingly and settles clamped to min and max and rounded to the step. The value is a number or null, never a string (pro)
- [Password Field](https://beautiful-ui.dev/md/lumen-password-field.md): A password with a reveal toggle that keeps the caret, and for new passwords a strength meter that says why in words: four cells, the verdict and the first hint, announced as it changes (pro)
- [Tag Input](https://beautiful-ui.dev/md/lumen-tag-input.md): Words as chips in one field: Enter or a comma adds, a pasted list adds each item, Backspace removes the last, each chip has its own remove button. Duplicates and anything past max are refused out loud, not silently dropped (pro)
- [Time Picker](https://beautiful-ui.dev/md/lumen-time-picker.md): Type a time (9:30 pm, 2130, 9a) or pick one from the list under the field; the list follows what is typed. The value is minutes after midnight, so it carries no date or time zone (pro)
- [Date Range](https://beautiful-ui.dev/md/glass-date-range.md): A liquid-glass date range picker in dark and light for a whole dashboard: presets under a gliding lens, a previous-period or year-over-year comparison, typed dates, a month rail for older periods and a two-month calendar whose fill ripples out from the start date, with a phone bottom sheet (pro)

## Selection

- [Checkbox](https://beautiful-ui.dev/md/lumen-checkbox.md): A checkbox that shows its work: the box presses in, fills with light and draws its own check, and a half-done parent fills cells for the children that are on. shadcn's Checkbox, cut from Lumen glass
- [Radio Group](https://beautiful-ui.dev/md/lumen-radio-group.md): Choices you can hear: each option plays its own note as you move through them, and the chosen one turns a rounded square into place. Works as a list or as option cards. shadcn's RadioGroup, cut from Lumen glass
- [Switch](https://beautiful-ui.dev/md/lumen-switch.md): A switch you can read without colour: two lit cells when on, an empty square when off, and a knob that stretches as you press it. shadcn's Switch, cut from Lumen glass
- [Select](https://beautiful-ui.dev/md/lumen-select.md): Choose one from a list: the trigger is Lumen's recessed well with the focus filament, and the options sit in smoked glass where a lens glides to the one you're on. shadcn's Select, cut from Lumen glass
- [Native Select](https://beautiful-ui.dev/md/lumen-native-select.md): The browser's own picker (the best one on phones) in Lumen's recessed well, with the focus filament and a quiet chevron. shadcn's Native Select, cut from Lumen glass
- [Combobox](https://beautiful-ui.dev/md/lumen-combobox.md): Type to narrow a long list: the matches sit in smoked glass where a lens of light glides to the highlighted one. With chips it becomes a multi-select, each pick a small lit cell you can remove. shadcn's Combobox, cut from Lumen glass (pro)

## Overlays

- [Tooltip](https://beautiful-ui.dev/md/lumen-tooltip.md): Names every icon, and never makes anyone wait twice: 380ms for the first, then instant along the toolbar, with the shortcut in a key cap. shadcn's Tooltip, cut from Lumen glass
- [Dialog](https://beautiful-ui.dev/md/lumen-dialog.md): A panel of smoked glass that rises into place while the page behind it dims and softens, and sounds once as it opens and closes. shadcn's Dialog, cut from Lumen glass
- [Alert Dialog](https://beautiful-ui.dev/md/lumen-alert-dialog.md): A decision in smoked glass that won't close by accident. The action is a Lumen Button, so a destructive one keeps its hold-to-confirm. shadcn's Alert Dialog, cut from Lumen glass (pro)
- [Sheet](https://beautiful-ui.dev/md/lumen-sheet.md): Smoked glass that glides in from any edge on Lumen's spring, for settings, filters and details beside the page. shadcn's Sheet, cut from Lumen glass (pro)
- [Popover](https://beautiful-ui.dev/md/lumen-popover.md): A small pane of smoked glass that grows from its trigger, for quick settings and details without leaving the page. shadcn's Popover, cut from Lumen glass (pro)
- [Hover Card](https://beautiful-ui.dev/md/lumen-hover-card.md): The popover's glass for a preview that appears while the pointer rests on a link: a member, a metric, a source. shadcn's Hover Card, cut from Lumen glass (pro)
- [Dropdown Menu](https://beautiful-ui.dev/md/lumen-dropdown-menu.md): A menu of smoked glass where a lens of light glides to the item under your pointer or keys, as it does across tabs; checks and radios light a cell, shortcuts sit in mono. shadcn's Dropdown Menu, cut from Lumen glass (pro)
- [Context Menu](https://beautiful-ui.dev/md/lumen-context-menu.md): The dropdown's glass and gliding lens, opened with a right-click or a long press where you are. shadcn's Context Menu, cut from Lumen glass (pro)
- [Drawer](https://beautiful-ui.dev/md/lumen-drawer.md): A pane of smoked glass that slides from an edge, follows your finger and snaps; the page behind dims and softens as it opens, nested drawers stack with a peek, and the handle is a short lit filament. shadcn's Drawer, cut from Lumen glass (pro)

## Feedback

- [Badge](https://beautiful-ui.dev/md/lumen-badge.md): Status you can read at a glance: five tones, a square cell dot that blinks for anything live, and a mono count for the numbers that pile up. shadcn's Badge, cut from Lumen glass
- [Spinner](https://beautiful-ui.dev/md/lumen-spinner.md): Loading, in Lumen's own hand: four cells lighting in turn instead of another spinning ring, sized by font-size, fading in place under reduced motion. shadcn's Spinner, cut from Lumen glass
- [Skeleton](https://beautiful-ui.dev/md/lumen-skeleton.md): A dim cell of glass with a slow sweep of light across it while the real thing loads; it holds still under reduced motion. shadcn's Skeleton, cut from Lumen glass
- [Progress](https://beautiful-ui.dev/md/lumen-progress.md): A filament of light that fills its track and glows at its tip, or with cells, a level meter whose segments light in turn, straight off a hi-fi panel. shadcn's Progress, cut from Lumen glass
- [Alert](https://beautiful-ui.dev/md/lumen-alert.md): A strip of glass whose status shows as a lit cell and a tinted rim, with the title saying it too, never colour alone. shadcn's Alert, cut from Lumen glass
- [Empty](https://beautiful-ui.dev/md/lumen-empty.md): The dark panel before it has anything to say: a row of unlit cells, a line in Lumen's voice and the one action that fills it. shadcn's Empty, cut from Lumen glass
- [Toast](https://beautiful-ui.dev/md/lumen-toast.md): Panes of smoked glass that stack with a peek, fan out on hover and swipe away; a status cell lit by type (a red glow for errors, cells acquiring while loading) and one cue per toast. Promise toasts go from loading to done on their own. shadcn's native Toast, cut from Lumen glass
- [Marker](https://beautiful-ui.dev/md/lumen-marker.md): A quiet labelled line for feeds and lists: its icon is a status lamp, an unlit cell that lights with its tone (critical glows, live states pulse), and the separator variant makes date rulers and the unread line. shadcn's Marker, cut from Lumen glass
- [State Panel](https://beautiful-ui.dev/md/lumen-state-panel.md): Every state a data surface can be in, decided one way: loading rows shaped like the content, first use, no results, access, disconnected, error and partial data, each with its next step. Content stays up while it refreshes, with a filament scanning the top edge
- [Sound](https://beautiful-ui.dev/md/glass-sound.md): The Lumen sound system: a provider that gives every glass component its cues and every click a soft glass tap, synthesised in the browser (no audio files), with a persisted mute toggle and a 19-cue vocabulary for presses, toggles, surfaces, values and outcomes

## Navigation

- [Nav](https://beautiful-ui.dev/md/glass-nav.md): A floating liquid-glass navigation bar in dark and light, with a lens that glides under links, a product mega-menu and a condensed scroll state
- [App Sidebar](https://beautiful-ui.dev/md/glass-sidebar.md): A floating liquid-glass app sidebar in dark and light, with a gliding lens, collapsible tree, search, a collapsed rail with tooltips and an account menu (pro)
- [Footer](https://beautiful-ui.dev/md/glass-footer.md): A liquid-glass site footer in dark and light: link columns with a gliding lens, a newsletter pill with animated states, socials, back to top and a giant wordmark lit by the cursor (pro)
- [Tabs](https://beautiful-ui.dev/md/lumen-tabs.md): Tabs with a sense of place: a glass thumb glides to the tab you pick and the panel rises in, or, as page tabs, a lens and a filament of light follow you along the row. shadcn's Tabs, cut from Lumen glass
- [Menubar](https://beautiful-ui.dev/md/lumen-menubar.md): An app's menus on Lumen's segmented track: a glass thumb glides to the menu that's open, and each menu has the gliding lens. shadcn's Menubar, cut from Lumen glass (pro)
- [Breadcrumb](https://beautiful-ui.dev/md/lumen-breadcrumb.md): Muted links that brighten on hover, the page you're on in ink, thin chevrons between and a cell ellipsis for the middle. shadcn's Breadcrumb, cut from Lumen glass (pro)
- [Pagination](https://beautiful-ui.dev/md/lumen-pagination.md): Pages on Lumen's segmented track, where a glass thumb glides to the page you're on; Previous and Next are quiet buttons. shadcn's Pagination, cut from Lumen glass (pro)
- [Navigation Menu](https://beautiful-ui.dev/md/lumen-navigation-menu.md): A site's top navigation: a glass lens glides to the item that's open, and panels of smoked glass resize and slide between items as you move. shadcn's Navigation Menu, cut from Lumen glass (pro)
- [Stepper](https://beautiful-ui.dev/md/lumen-stepper.md): The steps of a flow as cells on the panel: finished steps light with a check, the current one glows, the rest sit unlit, and the filament between them fills as you advance. Horizontal or vertical; finished steps can be revisited (pro)
- [Command](https://beautiful-ui.dev/md/lumen-command.md): A command menu on cmdk: search in a recessed well, results in smoked glass, and a lens of light that glides to the highlighted item with a lit filament on its edge. Opens inline or as a ⌘K palette pinned near the top, so filtering never moves the input. shadcn's Command, cut from Lumen glass (pro)
- [Sidebar](https://beautiful-ui.dev/md/lumen-sidebar.md): shadcn's Sidebar, cut from Lumen glass: a smoked-glass panel where a lens glides to the active page and lights a filament on its edge, sub-pages light their stretch of the guide line, and the rail glows as you reach for it. Collapses off-canvas or to icons with tooltips, becomes a sheet on phones, remembers its state and toggles on ⌘B (pro)
- [Global Search](https://beautiful-ui.dev/md/lumen-global-search.md): One place to jump to a page, run an action or find a record: fixed items matched as you type, async record search that's debounced and cancels stale calls, recent picks, grouped results with the matched text lit, loading and empty states in words, ⌘K from anywhere and a full-screen palette on phones (pro)
- [Command Palette](https://beautiful-ui.dev/md/glass-command.md): A liquid-glass command palette in dark and light: jump anywhere, run actions, read metrics in place with a cell trend, drill into nested pages and ask Lumen, with the family's gliding lens and a phone sheet (pro)

## Data

- [Avatar](https://beautiful-ui.dev/md/lumen-avatar.md): People as Lumen draws them: a metallic disc with initials, the photo when it loads, and a status light that glows in the dark. Groups overlap and count the rest. shadcn's Avatar, cut from Lumen glass
- [Table](https://beautiful-ui.dev/md/lumen-table.md): Rows on hairlines, numbers in tabular mono, a soft glow under the row you're on and a lit cell on a selected row's edge. shadcn's Table, cut from Lumen glass
- [Item](https://beautiful-ui.dev/md/lumen-item.md): A row for a list of things (a source, a member, a file): bare, outlined or on glass, with a media tile, a title and actions, lifting slightly as a link. shadcn's Item, cut from Lumen glass (pro)
- [Bulk Action Bar](https://beautiful-ui.dev/md/lumen-bulk-action-bar.md): A glass bar that rises in when rows are selected: the count is the one lit thing on it, the actions apply to every selected row, anything destructive asks first, and narrow containers fold the extras behind More (pro)
- [Activity Timeline](https://beautiful-ui.dev/md/lumen-activity-timeline.md): Who did what, when, and what changed: a hairline rail of cells, unlit for routine events and lit by severity (critical glows), grouped by the viewer's own day, with details that open in place (pro)
- [Metric Header](https://beautiful-ui.dev/md/lumen-metric-header.md): The row above a chart: each metric shows its value on rolling digits, the change against a named period in its good or bad tone, an optional target meter and uncertainty band, and choosing one lights a filament and switches the chart (pro)
- [Detail Drawer](https://beautiful-ui.dev/md/lumen-detail-drawer.md): Open one record over its list without losing the list: heading and status, fields, related charts and activity, pinned actions, previous and next with J and K, full screen on phones, and focus back on the row when it closes (pro)
- [Filter Bar](https://beautiful-ui.dev/md/lumen-filter-bar.md): Search and one pill per filter: dashed until set, then solid with its value and a clear button. Pills open a radio list, checkboxes with live counts, a two-thumb range or date presets with a calendar; narrow bars fold everything into one Filters sheet. Values are plain JSON that round-trips through the URL (pro)
- [Data Explorer](https://beautiful-ui.dev/md/lumen-data-explorer.md): A table people can search, filter, sort, page, select and act on. It shows loading, empty, zero-results and error states in words, turns into cards on narrow screens, drives a chart region from every filtered row, and opens rows in a drawer. TanStack Table v9 underneath; your columns are a small plain spec (pro)
- [Saved Views](https://beautiful-ui.dev/md/lumen-saved-views.md): Names for "these filters, this sort, these columns". The trigger shows the view in use and a lit dot when the screen has drifted from it; views are shared or private, one is the default, and each can be renamed in place, duplicated or deleted. Plain JSON, kept by any store (pro)
- [Date Compare](https://beautiful-ui.dev/md/lumen-date-compare.md): Pick the dates and what to compare them with. The trigger reads the way people say it ("Last 30 days · vs Aug 2 – 31"); the calendar shows both ranges, the comparison as outlined days; previous period, previous year or custom; Apply commits once. Time-zone safe: ISO days, and today in the workspace's zone (pro)
- [Metrics Dashboard](https://beautiful-ui.dev/md/lumen-metrics-dashboard.md): A product's numbers at a glance: the range sets everything, the KPI tabs switch the chart's metric, the chart puts the range beside the same days before it (dashed), and two ranked lists read with proportional bars
- [KPI Drilldown](https://beautiful-ui.dev/md/lumen-kpi-drilldown.md): KPI cards that grow into their detail in place: the range against the one before, progress to target and a breakdown, across the row, while the other cards wait below. The card morphs where the browser has view transitions; Escape or Close returns focus to it (pro)

## Charts

- [Stat Cards](https://beautiful-ui.dev/md/glass-stat-cards.md): Liquid-glass KPI cards in dark and light, in hero, default and compact sizes: the number, whether the change is good or bad, and whether the data can be trusted, with a headline that names what moved the wrong way, period tabs, rolling digits, cell trends and a drill-in
- [Stat](https://beautiful-ui.dev/md/lumen-stat.md): The number, whether it's good news, and where it's heading, in one glance. Digits roll like an odometer, the change takes its tone, and a spark of cells lights its last column to match. The KPI every Lumen chart and dashboard is built on
- [Chart](https://beautiful-ui.dev/md/lumen-chart.md): Everything around the plot, done once: shadcn's ChartConfig as live colour variables, a header, legend and readout, a glass tooltip that follows pointer and keys, a mode switch with a gliding thumb, and the table screen readers get. The base every Lumen story chart stands on; bring your own plot
- [Market Breadth](https://beautiful-ui.dev/md/lumen-market-breadth.md): How broad is the growth? Every market that beat its weekly target drops in as a square, so a year of breadth reads in one look: tall columns, dips around an event, a traced market's streak. In parts, with the finished card as the recipe (pro)
- [Customer Swarm](https://beautiful-ui.dev/md/lumen-customer-swarm.md): Every customer on one axis, so you can see where the revenue really sits. Tiles stack where each customer lands, lanes split by plan or region, and a drag across the axis tells you which plan earns more than its share. In parts, with the finished card as the recipe
- [Line Chart](https://beautiful-ui.dev/md/lumen-line-chart.md): Trends over time as lit traces that glow in their own colour, with dashed plans and forecasts, labelled targets, a legend that hides series, Lumen's tooltip, arrow-key inspection, and a table and summary for screen readers. shadcn ChartConfig on Recharts (pro)
- [Area Chart](https://beautiful-ui.dev/md/lumen-area-chart.md): Volume over time, overlaid, stacked into a total or as the mix in percent: lit top edges over bodies that fade to nothing, legend toggles, Lumen's tooltip and a table for screen readers. Percent stacking refuses negative values in words (pro)
- [Bar Chart](https://beautiful-ui.dev/md/lumen-bar-chart.md): Compare categories grouped, stacked or as percent, standing or lying down. Bars have a lit edge at their value end (the bottom for negatives); highlight the max, min or any bar and the rest dim; values at the ends; legend toggles; a table for screen readers (pro)
- [Composed Chart](https://beautiful-ui.dev/md/lumen-composed-chart.md): Bars, lines and areas on one time axis, with a second axis when a series needs its own scale and format (currency beside percent), legend toggles, Lumen's tooltip with each series in its own format, and a table for screen readers (pro)
- [Donut Chart](https://beautiful-ui.dev/md/lumen-donut-chart.md): Parts of one whole: the total in the middle follows the slice you point at or focus in the legend, which steps out with a glow; small slices fold into Other; the legend shows each value and share. Negative values are refused in words and missing values are named, not drawn as zero (pro)
- [Scatter Chart](https://beautiful-ui.dev/md/lumen-scatter-chart.md): How two measures move together, point by point, with an optional third as bubble size: lit points by group, labelled quadrant thresholds, a tooltip naming each point, and a summary that says the relationship in words (never a cause) (pro)
- [Heatmap](https://beautiful-ui.dev/md/lumen-heatmap.md): A grid of lit cells for two categories by one measure (day × hour, cohort × week). Cells light in proportion; zero is a faint cell and missing is hatched, so they never look alike; diverging scales split around a midpoint in two colours; arrow keys walk the grid with a spoken readout (pro)
- [Chart (shadcn API)](https://beautiful-ui.dev/md/lumen-chart-shadcn.md): shadcn's chart API, exactly, drawn in Lumen: ChartContainer, ChartTooltip, ChartTooltipContent, ChartLegend, ChartLegendContent, ChartStyle and useChart, with shadcn's ChartConfig (React-node labels and icons). Every example on ui.shadcn.com/charts works by changing one import
- [Day Rings](https://beautiful-ui.dev/md/lumen-day-rings.md): Daily goals over about a month on one ring: a spoke per day stacks each goal's progress, and the pinned day's goals wrap the ring as arcs that glow past 100%. Scrub by pointer or arrow keys, filter to one goal, log today in a tap and undo it. In parts, on Lumen's chart core
- [Cell Bars](https://beautiful-ui.dev/md/lumen-cell-bars.md): Bars built from rounded cells that pour in from zero. The headline names the leader; a level line and dashed ghost cells show every bar's gap to it; ticks mark the previous period; an oversized bar compresses behind a break until you ask for true scale. Stacked or grouped, sorted, standing or lying down, signed changes too. In parts (pro)
- [Flow Funnel](https://beautiful-ui.dev/md/lumen-flow-funnel.md): A conversion funnel as a lit band: one ribbon per source narrows stage by stage while people flow through as dots, and what each step loses spills into a tray under the gap. The headline gives the end-to-end rate and the biggest drop; the line under it names the source that over-performs. Sources toggle, the band scale is said in words, and it stands up on phones. In parts (pro)
- [Orbit](https://beautiful-ui.dev/md/lumen-orbit.md): A whole split into parts, drawn as lit dots on rings: 100 by default, one per percent, each part a sector. Dots are shared out exactly (they always add up), a period switch recolours them in a sweep, and pointing at a part lifts its dots while the centre reads its value. The headline names the largest part and who grew most. In parts (pro)
- [Trend](https://beautiful-ui.dev/md/lumen-trend.md): One number over time, built around a playhead: scrub the line and the big number rolls to that point; round-number milestones and dated events light up as the playhead passes; the line is lit behind it and dim ahead. The insight says how growth changed after the last event. Metric and period tabs, editable markers, and missing values kept as gaps. In parts (pro)
- [Cohort Retention](https://beautiful-ui.dev/md/lumen-cohort-retention.md): Cohorts as a triangle of lit cells: a row per cohort, a column per period since they started, each cell lit by the share still active. Periods not reached yet stay empty, never zero; the average row is weighted by cohort size; pointing at a cohort draws its curve against the average. The headline compares the newest cohort with the ones before it (pro)
- [MRR Waterfall](https://beautiful-ui.dev/md/lumen-mrr-waterfall.md): A period's MRR bridge as floating steps: start, new, expansion, contraction, churn, end. Gains rise in the good hue and losses fall in the bad one, with connectors carrying each level on. The end is worked out from the steps, and a recorded end that disagrees shows as its own Unexplained step rather than being hidden (pro)

## Text & motion

- [Kbd](https://beautiful-ui.dev/md/lumen-kbd.md): The key cap Lumen speaks shortcuts in: mono, recessed, the same in tooltips, fields and menus, so every shortcut on the page looks like one family. shadcn's Kbd, cut from Lumen glass
- [Typography](https://beautiful-ui.dev/md/lumen-typography.md): Long-form text in Lumen's voice: wrap docs, release notes, Markdown or chat answers in Prose and plain HTML takes a quiet hierarchy, bullets drawn as small lit cells, a filament beside quotes, and mono readouts for code and numbers
- [Code Block](https://beautiful-ui.dev/md/lumen-code-block.md): Code in a recessed readout: the filename and language in its header, a copy button with a soft cue, line numbers as dim mono digits, and highlighted lines lit by a filament down their edge. Plain text by default; pass pre-highlighted lines (Shiki on the server) for colour (pro)

## Media & effects

- [Carousel](https://beautiful-ui.dev/md/lumen-carousel.md): Slides that glide on Embla: the ones peeking at the edges dim so the slide in view glows, the arrows sit as a pager beside the position, a row of cells with the current one stretched into a lit filament. shadcn's Carousel, cut from Lumen glass (pro)
- [Attachment](https://beautiful-ui.dev/md/lumen-attachment.md): A file as a glass chip with its type in a recessed cell: a filament fills along the lower edge as it uploads, light sweeps the name while it works, an error lights a red lamp, and it chimes once when it lands. shadcn's Attachment, cut from Lumen glass (pro)
- [Lightbox](https://beautiful-ui.dev/md/lumen-lightbox.md): Images open over a smoked backdrop, growing out of the thumbnail you clicked. Click to zoom and the view follows your pointer; arrows, keys or a swipe move on; a filmstrip of cells lights the current image and a mono counter keeps your place (pro)
- [QR Code](https://beautiful-ui.dev/md/lumen-qr-code.md): A QR code drawn as rounded cells on a light plate, its finder eyes tinted with your accent, that exposes along the diagonal like a scan whenever the value changes. Dark on light in both themes so every camera reads it; an optional logo sits in a cleared centre with error correction raised to cover it (pro)
- [Video](https://beautiful-ui.dev/md/lumen-video.md): The browser's own video under Lumen controls: a glass play button, a scrubber drawn as a lit filament over the buffered track, mono timecode, mute, captions and full screen. Keyboard shortcuts, and controls that rest while it plays (pro)

## AI interfaces

- [Insight Rail](https://beautiful-ui.dev/md/lumen-insight-rail.md): What the model noticed, as a list a person can weigh: issue or opportunity, an explanation, confidence in words and lit cells, the records it affects and the evidence it rests on, and the next step. Choosing one opens it; Show affected selects those records in linked charts and tables (pro)
- [Evidence Panel](https://beautiful-ui.dev/md/lumen-evidence-panel.md): What an insight rests on, so a person can check it before acting: chart references, table rows, timeline events, records and sources, each with Show, which selects, brushes or opens what it names in linked views. No evidence reads as unverified (pro)
- [Recommendation](https://beautiful-ui.dev/md/lumen-recommendation.md): A recommended action a person decides on: rationale, expected impact, assumptions and how much evidence backs it, with accept, reject (with a reason), defer and edit. Accepting opens the Action Preview first (what changes, which records, risks, whether it can be undone) and only then runs it, or asks a reviewer to approve it (pro)
- [Approval Flow](https://beautiful-ui.dev/md/lumen-approval-flow.md): A second person signs off before an action runs: the requested action in full, who asked and who reviews, the context, and approve, request changes or reject, each with a note in the audit trail. Only the named reviewer decides, nobody approves their own request, and the action runs once approved (pro)
- [Agent Run](https://beautiful-ui.dev/md/lumen-agent-run.md): Watch an AI agent work and stay in charge of it: the prompt, elapsed time and tokens with pause, resume and stop; steps stream in as it reaches them; tool calls open to show what was sent and returned; a change waits for you to approve or reject it before anything is applied; a failed step says why and can be retried (pro)

## Marketing

- [Logo Carousel](https://beautiful-ui.dev/md/lumen-logo-carousel.md): A "trusted by" strip: logos drift through a smoked band, dimmed, and whichever passes under the central lens lights to full. Pauses on hover and focus, fades at the edges, and holds still as a row under reduced motion. Screen readers hear each name once (pro)
- [Landing Hero](https://beautiful-ui.dev/md/glass-landing-hero.md): A liquid-glass landing hero in dark and light: the nav pill with the gliding lens, an announcement pill, a two-tone headline, the call to action pair and a live trend chart as the product visual (or a video, your own node, or nothing) (pro)
- [FAQ](https://beautiful-ui.dev/md/glass-faq.md): A liquid-glass FAQ block in dark and light: glass accordion rows with a cell glyph, search with highlights, categories with the gliding lens, direct links to every question and rich answers with code, lists and a docs link (pro)

## Layout

- [Card](https://beautiful-ui.dev/md/lumen-card.md): The glass every Lumen chart sits in, now for everything else: a rim of light, a soft floor shadow and a footer shelf, in shadcn's parts. shadcn's Card, cut from Lumen glass
- [Separator](https://beautiful-ui.dev/md/lumen-separator.md): A hairline the colour of the glass's rim, across or down. shadcn's Separator, cut from Lumen glass
- [Accordion](https://beautiful-ui.dev/md/lumen-accordion.md): Rows on hairlines; the open one lights a filament down its edge and its panel eases open on the spring. shadcn's Accordion, cut from Lumen glass (pro)
- [Collapsible](https://beautiful-ui.dev/md/lumen-collapsible.md): Show and hide a section, with Lumen's timing on the panel and nothing else in the way; style the trigger as you like. shadcn's Collapsible, with Lumen's motion
- [Scroll Area](https://beautiful-ui.dev/md/lumen-scroll-area.md): A thin rail that brightens while you scroll or hover it and keeps out of the way otherwise. shadcn's Scroll Area, cut from Lumen glass
- [Aspect Ratio](https://beautiful-ui.dev/md/lumen-aspect-ratio.md): A box that keeps its shape at any width, for media, maps and charts. shadcn's Aspect Ratio, for Lumen Halo
- [Direction](https://beautiful-ui.dev/md/lumen-direction.md): Set right-to-left once, and every Lumen part follows: tabs, thumbs, lenses, menus and charts. shadcn's Direction, for Lumen Halo
- [Resizable](https://beautiful-ui.dev/md/lumen-resizable.md): Panes divided by a hairline that lights into a filament under the pointer and glows in the accent while you drag it; the grip is three small cells, and the arrows move it from the keyboard. shadcn's Resizable, cut from Lumen glass (pro)
- [Split View](https://beautiful-ui.dev/md/lumen-split-view.md): Two panes side by side (list and detail, table and chart, stream and investigation) split by a Lumen divider you can drag or move with the arrows. It remembers the split, and when its own width is narrow the second pane becomes a full-screen drawer (pro)
- [Page Header](https://beautiful-ui.dev/md/lumen-page-header.md): The top of an app page: breadcrumbs, the title with its status, the people on it, a progress meter, actions and tabs with counts. Scrolled past, it folds into a compact sticky bar; actions that don't fit move into a More menu as the header resizes, so nothing wraps or clips (pro)

## App screens

- [Customer Intelligence](https://beautiful-ui.dev/md/lumen-customer-intelligence.md): Lumen's reference workspace: see a decline, compare periods, inspect the population, isolate a segment, open the affected customers and review the recommended action. One list of customers with weekly MRR feeds the metric header, the trend, the swarm, the table and the insights, so filters, the date range and selections move every number together. Loading, empty, error and partial data in words; phones stack it (pro)
- [SaaS Analytics](https://beautiful-ui.dev/md/lumen-saas-analytics.md): A runnable SaaS app built from Lumen: a collapsible sidebar with six views, Overview, Customers and Revenue under Analytics, and Team, Billing and Settings under Workspace. The analytics views read one set of customers with weekly MRR, so every page agrees; the Customers view is the Customer Intelligence workspace, and the workspace views are SaaS Screens, wired to your backend through the team, billing and settings props. No router needed: map view and onViewChange onto yours, or drop it on one page (pro)
- [SaaS Screens](https://beautiful-ui.dev/md/lumen-saas-screens.md): The workspace screens a SaaS app needs next to its analytics: Team (members, roles, invites, remove with a confirm), Billing (plan, seats, usage meters, invoices) and Settings (workspace, notifications, and a danger zone that asks you to type the name). Every async action shows that it's working and says when it fails (pro)
- [Auth](https://beautiful-ui.dev/md/lumen-auth.md): Sign in, sign up and reset password in one card, switching in place. Your onSubmit does the work with any auth provider and throws to show an error; single sign-on buttons; the autocomplete tokens password managers need; a strength meter on sign-up; and a reset that never says whether an email has an account (pro)