# garn

> A Radix + Tailwind v4 design system, distributed as a copy-in source registry. Components are documented from one machine-readable source (ComponentInfo) — judgment included (when to use / not, do-don'ts, a11y contracts, relationships, recipes), not just props.

Library version: 0.3.0 (`@garn/ui`). All components share this version.

Conventions: consume only semantic `--garn-*` tokens (never raw hex/px); compose via the
documented slots; honor each component's a11y contracts. Full corpus: /llms-full.txt.

## Components

- [Accordion](https://garn.design/components/accordion): Let users expand/collapse sections to manage long content — FAQs, settings groups, nested details.
- [Activity Grid](https://garn.design/components/activity-grid): Show activity/frequency density over time as a calendar-style grid (contributions, logins, streaks).
- [Alert Dialog](https://garn.design/components/alert-dialog): Force an explicit decision before continuing — confirming a destructive or irreversible action (delete, discard, sign out).
- [Alert](https://garn.design/components/alert): Call out a persistent, inline status or message in the page flow — a form-level error, an info notice, a success summary.
- [App Shell](https://garn.design/components/app-shell): The top-level frame of an application screen — a dashboard, console, inbox, or records view that needs a persistent sidebar, header, and content area.
- [Aspect Ratio](https://garn.design/components/aspect-ratio): Constrain media (image, video, embed, map) to a fixed width:height ratio that scales with its container.
- [Avatar](https://garn.design/components/avatar): Represent a person or entity with their photo, falling back to initials or a person glyph — with optional presence/status, a name + detail AvatarItem, or an AvatarGroup that stacks many.
- [BadgeSelect](https://garn.design/components/badge-select): A single value you pick to change, displayed as a badge: a status / priority / category / assignee cell in a table, board, or inline-edit field. The trigger reads as a tinted lozenge whose tone follows the chosen value.
- [Badge](https://garn.design/components/badge): Tag or categorize inline — a status, count, or short label next to content.
- [Bar List](https://garn.design/components/bar-list): Show a ranked breakdown — the top N items by a metric (pages, referrers, products, errors).
- [Board](https://garn.design/components/board): A Kanban / status board where cards move between ordered columns and the move writes back a field: a sprint / project board (To do → In progress → Done), a CRM pipeline, a content workflow, an agent task board. Reach for it with `Board.Column` children, or drive it from data with `columns` + `items` + `renderCard`. Add WIP limits, swimlanes, collapse-to-rail and an inline composer as needed.
- [Breadcrumb](https://garn.design/components/breadcrumb): Show where the current page sits in a hierarchy and let users jump to an ancestor.
- [Bullet](https://garn.design/components/bullet): Show one measure against a target (and optional qualitative bands) compactly — KPI tiles, tables, dashboards.
- [Button Group](https://garn.design/components/button-group): Bind related actions into one attached cluster — toolbars, segmented controls, and split buttons (a primary action plus a menu of related ones).
- [Button](https://garn.design/components/button): An in-place action: submit, save, confirm, delete, or open a dialog/menu.
- [Calendar](https://garn.design/components/calendar): Pick a date, several dates, or a date range from a month grid — inline (booking, availability, scheduling) or inside a popover as a date field. Constrain with `minDate` / `maxDate` / `isDateUnavailable`; choose `mode` for the selection; add `getDayIndicators` for per-day dots or `showToday` for a Today footer.
- [Card](https://garn.design/components/card): Group related content and actions into one bordered surface — a summary, a form section, a list item, a dashboard tile.
- [Carousel](https://garn.design/components/carousel): Show a set of peer items (images, cards, testimonials) in a swipeable/steppable track when they don't all fit at once.
- [Chart](https://garn.design/components/chart): Build a real chart with axes, tooltip, and legend — line, area, bar, pie, scatter, radar, radial, combo, funnel.
- [Checkbox](https://garn.design/components/checkbox): Toggle an independent boolean, or select several items from a list.
- [Collapsible](https://garn.design/components/collapsible): Show/hide a single independent region — a 'show more', an expandable row, an optional details block.
- [Combobox](https://garn.design/components/combobox): Pick one option from a long list where search helps — a typeahead/autocomplete field. Use the `options` prop or compound ComboboxItem children, drive `inputValue` for server-side search, and opt into `allowCustomValue` for free-text tags/labels.
- [Command](https://garn.design/components/command): Let users find and run an action (or jump to a thing) by typing — a ⌘K command palette, a searchable action menu, a quick switcher. Reach for the elevated surface when the palette must navigate sub-commands (nested pages / prefix routing), search an async source, rank recents, bind per-item shortcuts, or expose per-row secondary actions.
- [Context Menu](https://garn.design/components/context-menu): Offer actions contextual to an element via right-click / long-press — canvas objects, file/list rows, rich editors.
- [Counter](https://garn.design/components/counter): Show a numeric total beside an owner — a notification/unread count on an icon button or nav item, a tally on a tab or list. Use Counter.Indicator to anchor a count or a presence dot onto the corner of a child (a bell icon, an avatar).
- [DataList](https://garn.design/components/data-list): A read-only set of 'field: value' pairs about one entity — demographics, an order/receipt summary, settings recap, a details tab, or a metadata sidebar. Use `row` for the classic detail block, `grid` when values must align across rows, `stacked` for narrow asides.
- [DatePicker](https://garn.design/components/date-picker): Collect a single date (or a date range) in a form where typing is often faster than clicking, but a calendar is still wanted for browsing. Use DateRangePicker for a start/end span with optional presets.
- [DateTimePicker](https://garn.design/components/date-time-picker): Collect a date and a time together as one timestamp (event start, deadline, appointment).
- [Dialog](https://garn.design/components/dialog): Interrupt the flow for a focused task or message that needs attention before continuing — a short form, details, or confirmation.
- [Drawer](https://garn.design/components/drawer): Surface a secondary task or details from the bottom edge on touch/mobile — quick settings, a picker, contextual actions you can swipe away.
- [Dropdown Menu](https://garn.design/components/dropdown-menu): Offer a list of commands or toggles from a button — row/overflow (kebab) actions, an account menu, view options.
- [Empty](https://garn.design/components/empty): Communicate a blank state — no search results, nothing created yet, a cleared list.
- [Field](https://garn.design/components/field): Pair a Switch / Checkbox / RadioGroupItem with a label (+ optional description), as a plain row or a selectable card.
- [File Upload](https://garn.design/components/file-upload): Letting a user attach one or more documents — a résumé, email attachments, a batch of deal-room docs — via drag-and-drop or a file picker, with validation, per-file status/progress, and retry/remove. Omit `files` for a simple form field; pass `files` + `onFilesChange` to show real upload progress.
- [FilterBar](https://garn.design/components/filters): Letting users author a predicate over a collection: a data-table / list / board filter bar, a faceted search, a saved-segment view, or an agent/MCP surface that returns editable filter chips. Use `<FilterBar fields={…} records={…}/>` for a self-contained bar, or drive `useFilters` yourself and pass the `engine` to share one model with a table/CollectionView.
- [Form](https://garn.design/components/form): Build accessible forms with React Hook Form — consistent label / control / description / error wiring out of the box.
- [Gallery](https://garn.design/components/gallery): Displaying a large set of images / thumbnails where the visuals ARE the content: a DAM / asset library, a photo stream, an e-commerce product grid, a Pinterest-style moodboard, a portfolio. Use masonry for variable-height pins, justified for a photo stream that fills each row, uniform for a cropped contact sheet. Add selection for batch ops, a lightbox to inspect, reorder to curate, virtualization to scale.
- [Gantt](https://garn.design/components/gantt): Laying out and editing work against a horizontal time axis — a product roadmap, a project plan with dependencies and a critical path, a delivery/release schedule, a construction or campaign timeline, or a WBS with rolled-up summary bars.
- [Gauge](https://garn.design/components/gauge): Show a single value on a dial against thresholds/target — capacity, score, throughput, health.
- [Heatmap](https://garn.design/components/heatmap): Show a labelled value matrix — retention cohorts, correlation, hour×day activity.
- [Hover Card](https://garn.design/components/hover-card): Preview supplementary detail when hovering/focusing a link or name — a user/profile card, a link preview, a definition peek.
- [InlineEdit](https://garn.design/components/inline-edit): Editing a single value in place — a field in a detail panel, a table/board cell, an entity property, or a title you rename without a modal. Use the quiet preset for fast edits, the explicit preset (Save/Cancel) for costly-to-mistake data cells.
- [Input OTP](https://garn.design/components/input-otp): Enter a short, fixed-length code — OTP, 2FA, email/phone verification, a PIN.
- [Input](https://garn.design/components/input): Collect a single line of freeform text — name, email, search query, etc. Add a leading/trailing slot for an icon or unit, or the built-in clearable / password-reveal / loading affordances.
- [Kbd](https://garn.design/components/kbd): Show a keyboard key or shortcut inline — menus, tooltips, command hints, docs.
- [Label](https://garn.design/components/label): Caption a form control so clicking the text focuses it and screen readers announce its name.
- [List](https://garn.design/components/list): A vertical collection of peer item rows — settings rows, an inbox / notification feed, a file or resource list, search results, a member list. Use terse <List.Item> for the common row; compose the slots for rich rows; set `selectionMode` for selectable lists and `href`/`onActivate` for navigable ones.
- [Menubar](https://garn.design/components/menubar): A persistent application menu bar (File / Edit / View …) for a desktop-like app or editor.
- [MultiSelect](https://garn.design/components/multi-select): Select several values held as removable chips — from a searchable list, or as free-text tags. Use the `options` prop or compound MultiSelect.Item children; opt into `allowCustomValue` for tags (paste/comma tokenize, dedupe, validate); cap with `max` and collapse overflow with `visibleLimit`.
- [Navigation Menu](https://garn.design/components/navigation-menu): Primary site navigation with optional rich dropdown panels — a top header nav or mega-menu.
- [NumberField](https://garn.design/components/number-field): Enter a quantity, price, percentage, or measurement by typing or stepping — with locale-correct formatting and a real number value.
- [Pagination](https://garn.design/components/pagination): Split a long, ordered result set into pages and let users move between them.
- [Popover](https://garn.design/components/popover): Show contextual detail or a small interactive form anchored to a control, without blocking the page.
- [Progress](https://garn.design/components/progress): Show determinate progress of a task with a known percentage — upload, install, multi-step completion.
- [Radio Group](https://garn.design/components/radio-group): Pick one option from a few (≈2–5) mutually exclusive choices, all visible at once.
- [Rating](https://garn.design/components/rating): Collect or display a score on a small fixed scale — a star review, a helpfulness vote, a difficulty rating — where cumulative symbols read faster than a number.
- [Resizable](https://garn.design/components/resizable): Let users rebalance space between adjacent regions — a sidebar/content split, an editor/preview, multi-pane layouts.
- [Scheduler](https://garn.design/components/scheduler): Displaying and editing events against time — a day/week planner, a booking/availability grid, a team calendar, a room/resource schedule, or an agenda feed.
- [Scroll Area](https://garn.design/components/scroll-area): Give a height-constrained region its own styled scrollbar — a sidebar, a long list, a code block, a chat log.
- [Select](https://garn.design/components/select): Pick one option from a medium-to-long list (~5+) where the choices fit in a popover.
- [Separator](https://garn.design/components/separator): Visually divide content groups — between list items, sections, or toolbar clusters.
- [Sheet](https://garn.design/components/sheet): Slide a panel in from a screen edge for a secondary task or navigation that shouldn't replace the page — filters, a detail/edit panel, a nav drawer.
- [Skeleton](https://garn.design/components/skeleton): Hold the page's shape while content loads — mirror the size/shape of the incoming text or media.
- [Slider](https://garn.design/components/slider): Let users pick a number (or a range) where the approximate position matters more than an exact figure — volume, brightness, a price range.
- [Sonner (Toast)](https://garn.design/components/sonner): Confirm an action or surface a transient, non-blocking message that auto-dismisses — 'Saved', 'Copied', 'Undo'.
- [Sortable](https://garn.design/components/sortable): Making a collection reorderable by drag (and keyboard): a to-do / priority list, a Kanban board that moves cards between columns, a tile/image grid, a settings list of pinned items. Use it directly with <Sortable> + <Sortable.Item>, or wire the `useSortable` hook into a component that owns its own rows.
- [Sparkline](https://garn.design/components/sparkline): Show a trend inline — in a Stat tile, a table row, or beside a KPI — where a full chart's axes and legend would be overkill.
- [Spinner](https://garn.design/components/spinner): Indicate an indeterminate loading or pending state, inline or inside a control.
- [Stat](https://garn.design/components/stat): A headline metric on a dashboard / overview / report — a labelled number with an optional period-over-period delta, an icon, supporting copy, and a trend slot. Use Stat.Group for a responsive row of related KPIs.
- [Stepper](https://garn.design/components/stepper): Guide a user through an ordered, often-gated process — a checkout, an onboarding wizard, a multi-section form — showing where they are, what's done, and what's left.
- [Switch](https://garn.design/components/switch): A setting that applies immediately — no Save step (notifications on/off, dark mode).
- [Table](https://garn.design/components/table): Present structured data in rows and columns where alignment and comparison matter — invoices, users, metrics — with sorting, selection, sticky/pinned columns, and pagination via the smart parts.
- [Tabs](https://garn.design/components/tabs): Switch between a few peer views in the same context, one panel at a time — settings sections, overview/detail, related lists.
- [Tag](https://garn.design/components/tag): Removable + selectable chips: dismissable filter tokens (applied filters, recipients, keywords) and pick-to-toggle option chips. Use a standalone <Tag onRemove> for a lone token, or a <TagGroup> to coordinate selection (selectionMode) and removal with roving-keyboard a11y across a set.
- [Textarea](https://garn.design/components/textarea): Collect multi-line freeform text — comments, descriptions, messages, notes.
- [TimeField](https://garn.design/components/time-field): Enter a time of day by typing, with Arrow-key nudging — in a form where a slot list would be overkill.
- [TimePicker](https://garn.design/components/time-picker): Pick a time from fixed slots (appointment, reservation) while still allowing free typing.
- [Timeline](https://garn.design/components/timeline): A read-only chronology of events that already happened — an activity feed, audit log, order/shipment history, changelog, or status thread. Reach for the terse <Timeline.Item> per event; compose the slots for rich entries.
- [Toggle Group](https://garn.design/components/toggle-group): Group related toggles into one control — a segmented single-choice selector or a multi-select toolbar (alignment, formatting marks).
- [Toggle](https://garn.design/components/toggle): A single two-state (on/off) button — toggling a formatting mark, a view option, or a toolbar setting.
- [Toolbar](https://garn.design/components/toolbar): A strip of 3+ related controls (buttons, toggles, links, a search field) that should behave as ONE tab stop with arrow-key navigation — editor formatting bars, app / data-table action bars, vertical tool rails, and selection bubbles — especially when they must stay reachable as the container narrows.
- [Tooltip](https://garn.design/components/tooltip): Add a brief, supplementary text hint to a control — clarify an icon button, abbreviate a label, surface a shortcut.
- [Tracker](https://garn.design/components/tracker): Show a categorical status history over time — uptime, incidents, SLA windows, run health.
- [Tree](https://garn.design/components/tree): A hierarchy the user expands and collapses to arbitrary depth — a file/folder explorer, a nested navigation sidebar, a category/org structure, threaded comments. Use terse <Tree.Item> for the common node and compose the slots for rich rows; set `selectionMode` for active-node selection, `checkable` for a checkbox tree, and `Tree.Search` / `filterValue` to find nodes in a deep tree.

## Optional

- [Full component corpus](https://garn.design/llms-full.txt): every component's complete reference in one file.