# @nils/ui

> A small, opinionated React + Tailwind v4 UI library: console-flavoured, white and grey with one blue accent, quick and firm motion. Every page below is plain markdown; the same files ship inside the npm package under node_modules/@nils/ui/.

Start with AGENTS.md (how to install and use the library, and the rules you must follow), then DESIGN.md (tokens, type, motion). Each component page has props, examples you can copy, and do/don't rules.

## Start

- [AGENTS.md](/agents.md): Start here. How to install and use @nils/ui, where every doc lives, and the rules an agent must follow when building UI with it.
- [Getting started](/getting-started.md): Install the package, import the stylesheet, set the theme, and render a first component.
- [Design](/design.md): The visual contract — principles, tokens, type, spacing, corners, elevation, motion and copy. Every number here is what a change is judged against.

## Examples

- [Console showcase](/examples/console.md): A working machine console composed from library parts: sortable rows, live metrics, filters, deployment form and a details sheet.

## Controls

- [Button](/components/button.md): Every pressable action. Five variants, three sizes, icon-only, loading, and a built-in shortcut hint.
- [Field](/components/field.md): Label, control, help text and error, wired together. Wrap every form control in one, and use Form for validation.
- [Input](/components/input.md): A single-line text field in three sizes, with optional leading and trailing adornments for icons, units and hints.
- [Textarea](/components/textarea.md): A multi-line text field. Resizes by hand, or grows with its content.
- [Checkbox](/components/checkbox.md): A square on/off box for choices that apply on save, with an indeterminate state for "some of these".
- [Radio group](/components/radio-group.md): Pick exactly one of a few options that should all stay visible. Radio + RadioGroup.
- [Switch](/components/switch.md): An on/off setting that takes effect the moment you flip it.
- [Segmented control](/components/segmented-control.md): Pick one of 2–5 short options shown side by side, like a view mode or time range. The selection slides.
- [Select](/components/select.md): Pick one value from a list in a popup. A props API for the common case, parts for groups and custom items.
- [Kbd](/components/kbd.md): A keyboard key hint, drawn as a small mono keycap. Display only.
- [Combobox](/components/combobox.md): A text field with a filtered list. Pick one, several (as chips), or type something new with creatable — that's the tag input.
- [NumberField](/components/number-field.md): A number input with arrow-key stepping, optional −/+ buttons and units, and a scrubbable leading label you drag like a design tool.
- [Slider](/components/slider.md): Pick a number or a range by dragging. A firm square thumb, an accent fill, optional ticks and a mono value readout.
- [Calendar](/components/calendar.md): A month grid for picking a day or a range, built on Intl with no date library. Full keyboard support; today in accent, selection in ink.
- [DatePicker](/components/date-picker.md): A date field you can type into (YYYY-MM-DD) or pick from a calendar popover. Submits ISO, shows a weekday hint, works inside Field.
- [OTPField](/components/otp-field.md): One-time codes: one mono box per character, auto-advance, Backspace to go back, paste to fill all. Optional visual groups.
- [FileDrop](/components/file-drop.md): A dashed drop zone with a file list: drag files in or browse, see names (middle-truncated) and sizes, remove, and get plain reasons for rejected files.

## Data

- [DataTable](/components/data-table.md): A table from columns and rows, with sorting, row selection, whole-row clicks, a sticky header, loading and empty states, and a brief flash on rows that change.
- [Table](/components/table.md): The styled table parts (Table, TableHeader, TableBody, TableFooter, TableRow, TableHead, TableCell) for markup DataTable can't express.
- [Stat](/components/stat.md): One metric (label, value, optional delta and caption) and StatGroup, a hairline-divided row of them. Values roll when they change.
- [NumberRoll](/components/number-roll.md): A formatted number whose changed digits roll to their new value. Up for increases, down for decreases, never on first render.
- [KeyValue](/components/key-value.md): A description list for the properties of one thing (keys in the mono label voice, values in ink), as a key column or stacked.
- [Tabs](/components/tabs.md): Switch between views of the same thing. An ink underline slides to the active tab; panels swap instantly.
- [Progress & Meter](/components/progress.md): Thin bars for how far a task has got (Progress, accent, can be indeterminate) and for a level within a range (Meter, neutral, warns past thresholds). Optional segmented console look.
- [Skeleton](/components/skeleton.md): A quiet placeholder block for loading content. It waits 300ms before appearing, so fast loads never flash.

## Feedback

- [Callout](/components/callout.md): A note in the page — status dot, ink title, short body, one optional action. Inline box or full-width banner. Never a coloured wash.
- [Badge](/components/badge.md): A 20px hairline label for counts, versions, states and tags. Optional status dot, optional mono. Never filled with colour.
- [Avatar](/components/avatar.md): A rounded square picture of a person or org in four sizes, with mono initials as the fallback, and an overlapping AvatarGroup.
- [Accordion](/components/accordion.md): Stacked, hairline-separated sections that open in place. A caret turns, the height eases open in 180ms.
- [Collapsible](/components/collapsible.md): One show/hide region with a quiet caret trigger. For "Show advanced options" and similar, not for lists of sections.
- [Spinner](/components/spinner.md): A small ring that turns once every 600ms, in the current text colour. For waits that take a moment, not for page loads.
- [CopyButton](/components/copy-button.md): Copies a value to the clipboard; the icon crossfades into a green check, holds 1.2s, and returns. The library's signature confirm.
- [Code](/components/code.md): Inline Code for values in a sentence, and CodeBlock for snippets with a filename header, line numbers and a copy button.
- [HoverCard](/components/hover-card.md): A preview that appears when you rest on a link, name or ID. Opens after 400ms, grows from the trigger, never holds anything essential.

## Overlays

- [Popover](/components/popover.md): A small floating panel anchored to a trigger, for extra detail or a few quick controls. Grows out of its trigger.
- [Menu](/components/menu.md): A dropdown list of actions opened from a button, with shortcuts, checkboxes, radio groups, labels and submenus.
- [ContextMenu](/components/context-menu.md): A right-click (or long-press) menu for an area, filled with the same item parts as Menu.
- [Dialog](/components/dialog.md): A modal panel over a scrim, for focused tasks that need an answer before going back to the page.
- [ConfirmDialog](/components/confirm-dialog.md): Asks "are you sure?" before a consequential action. One component, async-aware, can't be dismissed by accident.
- [Tooltip](/components/tooltip.md): A small dark label naming an icon-only control, with an optional shortcut. Shows on hover after a beat, or on focus.
- [Toast](/components/toast.md): Short notices that confirm something happened, bottom-right, with an optional status, detail, and one action. Call toast() from anywhere.

## Layout

- [Panel](/components/panel.md): A grouped region with a hairline edge and an optional header and footer row. Use it instead of cards.
- [List](/components/list.md): Flat rows separated by hairlines, with leading, title, meta, description and trailing slots. Whole-row links and buttons.
- [Status](/components/status.md): A coloured dot plus an ink word ("● Online"). The only way status colour appears in this library.
- [Separator](/components/separator.md): A hairline between groups of content, horizontal or vertical, with an optional mono label set into the line.
- [EmptyState](/components/empty-state.md): What a list, table or page shows when there is nothing in it. A fact, a reason and the next action. No illustrations.
- [CommandPalette](/components/command-palette.md): The ⌘K command list. A modal search over grouped commands with icons and shortcut hints, arrow keys and Enter. Opens instantly.

## Shell

- [AppShell](/components/app-shell.md): The frame of an app — a sidebar beside a main column with a sticky top bar. Folds the sidebar into a sheet when narrow.
- [Sidebar](/components/sidebar.md): The app's navigation column — a brand row, labelled sections of 28px items with counts or shortcuts, and a pinned footer.
- [TopBar](/components/top-bar.md): The 48px bar over the main column — breadcrumbs on the left, actions on the right, translucent and sticky.
- [Breadcrumbs](/components/breadcrumbs.md): Where you are, as a trail of links — Projects / turbine / Settings. Long trails fold their middle into a menu.
- [PageHeader](/components/page-header.md): The top of a page — title, one-sentence description, actions on the right, and a mono row of facts.
- [Toolbar](/components/toolbar.md): A row of related controls with one tab stop and arrow-key navigation — formatting buttons, view toggles, filters.
- [Sheet](/components/sheet.md): A panel that slides in from the side of the window, for details, editing and filters without leaving the page. Swipe to dismiss.

## Optional

- [Everything in one file](/llms-full.txt): every page above, concatenated.