# Seed

> A calm, neutral-first design system for React and Tailwind CSS v4. Packages: @flinbu/seed (React components on Radix) and @flinbu/seed-tokens (tokens, Tailwind theme, createTheme, seed CLI).

## Setup
- npm i @flinbu/seed @flinbu/seed-tokens lucide-react
- CSS: @import "tailwindcss"; @import "@flinbu/seed/styles.css";
- Without Tailwind: import "@flinbu/seed/compiled.css"
- Theme: <ThemeProvider> and <ThemeScript /> in <head>; useTheme() gives theme, resolvedTheme, setTheme.

## Rules
- Use semantic token utilities only: bg-primary, text-secondary, border-primary, text-icon-secondary, p-base, gap-xs, rounded-control, shadow-elevation-raised, h-control-md, and Seed type styles like label-label-2-medium or body-body-3-regular. Never raw hex or px.
- Icons are components: leftIcon={<Plus />} from lucide-react.
- Brand themes: npx seed theme --brand "#hex" --name acme --out acme.css, then <ThemeProvider brand="acme">.

## More
- Full design system with live previews, tokens and guides (principles, voice and tone, writing, accessibility): https://claude.ai/artifact/3EcyStkY8yCeAxSM7a1biz
- Figma library (variables, styles and components named like the code): https://www.figma.com/community/file/1694480861909658527
- Claude plugin with the Seed skill: https://github.com/flinbu/seed/tree/main/plugin (Claude Code: /plugin marketplace add flinbu/seed)

## Components
### Button
Starts an action. One primary button per view; start every label with a verb.
- variant: 'primary' | 'secondary' | 'tertiary' | 'ghost' | 'destructive' | 'success' | 'link' (default 'primary'). Visual weight.
- size: 'sm' | 'md' | 'lg' (default 'md'). sm 32px, md 40px, lg 48px.
- leftIcon: IconProp. Icon before the label. An element like <Search /> (works in server components) or, in client components, the component itself.
- rightIcon: IconProp. Icon after the label. An element like <Search /> (works in server components) or, in client components, the component itself.
- icon: IconProp. Makes a square icon-only button. Needs aria-label. An element like <Search /> (works in server components) or, in client components, the component itself.
- loading: boolean (default false). Spinner in place of the left icon; ignores clicks but stays readable and focusable.
- fullWidth: boolean (default false). Stretches to its container.
- href: string. Renders an <a> with the same look.
- asChild: boolean (default false). Styles your own element, like a router Link.
- className: string. Extra classes. They win over Seed's, so you can adjust one thing without forking.

### Input
A single line of text: names, emails, search, numbers.
- size: 'sm' | 'md' | 'lg' (default 'md'). sm 32px, md 40px, lg 48px.
- invalid: boolean. Error border and aria-invalid. Field sets it from error.
- leftIcon: IconProp. Icon inside the start of the field. An element like <Search /> (works in server components) or, in client components, the component itself.
- rightIcon: IconProp | ReactNode. An icon, or a small ghost Button for an action (clear, show password).
- …: InputHTMLAttributes. Every native input prop is passed to the <input>; ref points to it.
- className: string. Extra classes. They win over Seed's, so you can adjust one thing without forking.

### Textarea
Several lines of text.
- invalid: boolean. Error border and aria-invalid.
- resize: boolean (default true). false locks the size.
- rows: number (default 3). Starting height.
- className: string. Extra classes. They win over Seed's, so you can adjust one thing without forking.

### Field
A label, one control, a hint and an error, wired together for screen readers.
- label: ReactNode. The visible label.
- labelAside: ReactNode. Small text at the right of the label, like Optional.
- hint: ReactNode. Helper text under the control.
- error: ReactNode. Error message; marks the control invalid.
- required: boolean. Asterisk on the label and required on the control.
- disabled: boolean. Disables the control and dims the label.
- children: ReactElement. Exactly one control.

### Label
The name of a control. Field uses it for you.
- required: boolean. Adds a red asterisk (decorative).
- disabled: boolean. Dimmed.
- size: 'sm' | 'md' (default 'md'). 12 or 14 px.
- className: string. Extra classes. They win over Seed's, so you can adjust one thing without forking.

### Checkbox
Turns an option on or off in a list, or picks several.
- label: ReactNode. Text next to the box.
- description: ReactNode. Helper line under the label.
- checked / defaultChecked: boolean. Controlled or initial state.
- onCheckedChange: (checked: boolean) => void. Called with true or false.
- indeterminate: boolean. Shows a dash.
- invalid: boolean. Error border.
- disabled: boolean. Can't be changed.

### RadioGroup
Picks exactly one option from a short list.
- value / defaultValue: string. Selected option.
- onValueChange: (value: string) => void. Called when the selection changes.
- orientation: 'vertical' | 'horizontal' (default 'vertical'). Layout and arrow-key direction.
- invalid: boolean. Error border on every Radio.
- Radio: value: string. The option's value.
- Radio: label, description: ReactNode. Text next to the circle.

### Switch
A setting that applies right away.
- label, description: ReactNode. Text next to the switch.
- checked / defaultChecked: boolean. Controlled or initial state.
- onCheckedChange: (checked: boolean) => void. Called on change.
- size: 'sm' | 'md' (default 'md'). 40 × 20 or 32 × 16 px.
- disabled: boolean. Can't be changed.

### Toggle and ToggleGroup
Buttons that stay pressed: text styles, view switches, filters.
- pressed / defaultPressed: boolean. Toggle state.
- onPressedChange: (pressed: boolean) => void. Called on change.
- icon: IconProp. Icon-only toggle. An element like <Search /> (works in server components) or, in client components, the component itself.
- leftIcon: IconProp. Icon before the label. An element like <Search /> (works in server components) or, in client components, the component itself.
- size: 'sm' | 'md' | 'lg' (default 'md'). sm, md or lg.
- ToggleGroup: type: 'single' | 'multiple'. One or many pressed.
- ToggleGroup: allowEmpty: boolean (default true). Single groups: false keeps one selected.
- ToggleGroup: variant: 'ghost' | 'outline' (default 'ghost'). outline frames the group as a segmented control.

### Badge
A short status or count next to what it describes.
- variant: 'neutral' | 'accent' | 'error' | 'success' | 'warning' | 'info' | 'offer' (default 'neutral'). Meaning.
- appearance: 'soft' | 'solid' | 'outline' (default 'soft'). Weight.
- icon: IconProp. Small leading icon. An element like <Search /> (works in server components) or, in client components, the component itself.
- dot: boolean. A leading dot in the text color.
- className: string. Extra classes. They win over Seed's, so you can adjust one thing without forking.

### Avatar
A person or a workspace: the photo when it loads, initials when it doesn't.
- src: string. Photo URL.
- name: string. Initials and accessible name.
- alt: string. Overrides the accessible name.
- size: 'xs' | 'sm' | 'md' | 'lg' (default 'md'). 24, 32, 40 or 48 px.
- shape: 'circle' | 'square' (default 'circle'). square for organizations.

### Card
Groups related content and actions.
- interactive: boolean. Hover elevation and pointer cursor.
- CardTitle: as: 'h2' | 'h3' | 'h4' (default 'h3'). Heading level.
- className: string. Extra classes. They win over Seed's, so you can adjust one thing without forking.

### Alert
A message in the page: what happened, and what to do.
- variant: 'neutral' | 'info' | 'success' | 'warning' | 'error' | 'offer' (default 'info'). Meaning and icon.
- emphasis: 'subtle' | 'loud' (default 'subtle'). subtle: only the icon is in color. loud: the hairline takes the tone (border-{tone}-subtle).
- title: ReactNode. One line.
- icon: IconProp | false. Replace or hide the variant's icon.
- action: ReactNode. One or two small Buttons.
- onDismiss: () => void. Shows a close button.
- live: boolean. Set when the alert appears after the page loads, so it's announced.
- toneLabel: string | false. The hidden word read before the message. Default Info, Success, Warning or Error; none for neutral and offer.
- className: string. Extra classes. They win over Seed's, so you can adjust one thing without forking.

### Progress
How far along something is. Leave value out when you can't tell.
- value: number | null. Omit for an indeterminate bar.
- max: number (default 100). Top of the scale.
- label: ReactNode. Names the bar.
- showValue: boolean. Shows the percentage or valueText.
- valueText: string. Replaces the percentage, e.g. 9.2 of 10 GB.
- variant: 'accent' | 'success' | 'warning' | 'error' (default 'accent'). Bar color.
- size: 'sm' | 'md' (default 'md'). 4 or 8 px tall.

### EmptyState
What's missing and how to fill it, with one main action.
- icon: IconProp. Defaults to an inbox; false hides it. An element like <Search /> (works in server components) or, in client components, the component itself.
- title: ReactNode. What isn't here yet.
- description: ReactNode. How to add it.
- actions: ReactNode. One primary Button, optionally a secondary.
- size: 'sm' | 'md' (default 'md'). sm inside tables and narrow panels.

### Skeleton
A placeholder in the shape of content that's loading.
- width / height: number | string. Size.
- shape: 'block' | 'text' | 'circle' (default 'block'). text is a 12px line.

### Spinner
Something is working and will finish soon.
- size: 'xs' | 'sm' | 'md' | 'lg' (default 'sm'). 12 to 24 px.
- label: string | null (default 'Loading'). Announced text.

### Icon
Draws any icon at Seed's sizes.
- as: ComponentType. The icon component, e.g. Search from lucide-react.
- size: 'xs' | 'sm' | 'md' | 'lg' | number (default 'sm'). 12, 16, 20 or 24 px.
- label: string. Accessible name; makes the icon meaningful.
- strokeWidth: number (default 2). Line weight.

### Kbd
A keyboard key.
- className: string. Extra classes. They win over Seed's, so you can adjust one thing without forking.

### Separator
A 1px line between groups.
- orientation: 'horizontal' | 'vertical' (default 'horizontal'). Direction.
- decorative: boolean (default true). false exposes role separator.
- className: string. Extra classes. They win over Seed's, so you can adjust one thing without forking.

### Select
Picks one value from a list. Seed never uses the native select.
- value / defaultValue: string. Selected value.
- onValueChange: (value: string) => void. Called on change.
- SelectTrigger: placeholder: ReactNode. Shown when nothing is selected.
- SelectTrigger: size: 'sm' | 'md' | 'lg' (default 'md'). Same heights as Input.
- SelectTrigger: leftIcon: IconProp. Icon at the start of the field. An element like <Search /> (works in server components) or, in client components, the component itself.
- SelectTrigger: invalid: boolean. Error border. Field sets it from error.
- SelectItem: icon: IconProp. Leading icon. An element like <Search /> (works in server components) or, in client components, the component itself.
- SelectItem: description: ReactNode. A second line.
- SelectItem: disabled: boolean. Shown but can't be picked.

### DropdownMenu
A list of commands that opens from a button: row actions, More menus, view options.
- DropdownMenuItem: icon: IconProp. Leading icon. An element like <Search /> (works in server components) or, in client components, the component itself.
- DropdownMenuItem: shortcut: ReactNode. Shown at the end, like ⌘D.
- DropdownMenuItem: destructive: boolean. Red, for deleting.
- DropdownMenuItem: onSelect: (e: Event) => void. Runs the command; the menu closes.
- DropdownMenuContent: align / side: 'start' | 'center' | 'end' / Side (default 'start' / 'bottom'). Placement; flips to stay on screen.

### Dialog
A blocking task on top of the page: a short form, a review, a decision.
- open / defaultOpen: boolean. Controlled or initial state.
- onOpenChange: (open: boolean) => void. Called on open and close.
- DialogContent: size: 'sm' | 'md' | 'lg' (default 'md'). 384, 512 or 672 px wide.
- DialogContent: hideClose: boolean. Hides the close button; keep a Cancel button.
- DialogContent: closeLabel: string (default 'Close'). Accessible name of the close button.

### Popover
Content that floats next to its trigger: filters, a small form, details.
- PopoverContent: side / align: Side / 'start' | 'center' | 'end' (default 'bottom' / 'start'). Placement; flips to stay on screen.
- PopoverContent: inline: boolean. Render in place instead of a portal.
- className: string. Extra classes. They win over Seed's, so you can adjust one thing without forking.

### Tooltip
Names an icon button or explains a control, on hover and focus.
- content: ReactNode. A few words.
- shortcut: ReactNode. Shown after the text.
- side: Side (default 'top'). Placement.
- delay: number (default 300). ms before it opens on hover.
- children: ReactElement. One focusable trigger.

### Tabs
Switches between views of the same thing.
- value / defaultValue: string. Active tab.
- onValueChange: (value: string) => void. Called on change.
- TabsList: variant: 'line' | 'pill' (default 'line'). Underline or segmented control.
- TabsList: fullWidth: boolean. Tabs share the width.
- TabsTrigger: icon: IconProp. Leading icon. An element like <Search /> (works in server components) or, in client components, the component itself.
- TabsTrigger: count: ReactNode. A count after the label.

### Table
Rows of records with sortable headers.
- density: 'comfortable' | 'compact' (default 'comfortable'). 48 or 40 px rows.
- stackOnMobile: boolean (default true). Below 768px each row is a card: the first cell as its title, every other cell under its header. false keeps the table, scrolling sideways in its frame.
- frameClassName: string. Classes for the frame.
- TableCell: label: string. The header shown above the value on phones. Default the column header's text.
- TableRow: selected: boolean. Neutral selection color.
- TableHead: sort: 'ascending' | 'descending' | false. Makes the header a sort button.
- TableHead: onSort: () => void. Called on click.
- TableHead / TableCell: align: 'left' | 'center' | 'right' (default 'left'). Right-align numbers.

### Combobox
A field you type into to find and pick one option from a long list.
- options: ComboboxOption[]. { value, label, description?, icon?, keywords?, disabled? }.
- value / defaultValue: string | null. Selected value.
- onValueChange: (value: string | null) => void. Called on pick and clear.
- clearable: boolean. A clear button once something is picked.
- filter: (option, query) => boolean. Your own matching.
- emptyText: ReactNode (default 'No matches'). Shown when nothing matches.
- size: 'sm' | 'md' | 'lg' (default 'md'). Same heights as Input.

### Sheet
A panel that slides in from an edge: details, filters, a form next to the page.
- SheetContent: side: 'right' | 'left' | 'bottom' (default 'right'). The edge it slides from. Side sheets are up to 448px wide.
- SheetContent: hideClose: boolean. Hides the close button.
- SheetContent: closeLabel: string (default 'Close'). Accessible name of the close button.

### Toast
A short message about something that just happened, with one action at most.
- toast(options | title): (ToastOptions | string) => id. Shows a toast. Also toast.success, .error, .warning, .info and .dismiss(id?).
- title: ReactNode. One short line.
- description: ReactNode. Optional detail.
- action: { label, onClick }. One action, like Undo.
- duration: number (default 5000). ms on screen; errors default to staying.
- Toaster: position: 'bottom-right' | 'bottom-left' | 'bottom-center' | 'top-…' (default 'bottom-right'). Where they appear. Render one Toaster near the root.

### Accordion
Sections that open and close in place.
- type: 'single' | 'multiple'. One or many open.
- collapsible: boolean. single only: the open one can close.
- value / defaultValue: string | string[]. Open sections.
- AccordionTrigger: level: 2 | 3 | 4 | 5 | 6 (default 3). Heading level.

### Breadcrumb
Where the page sits, with the path back up.
- items: { label, href?, onClick? }[]. Top level first; the last is the current page.
- maxItems: number (default 4). Collapse the middle into a menu above this.
- linkAs: ElementType (default 'a'). Your router's Link.

### Pagination
Moves through pages of results.
- page: number. 1-based current page.
- count: number. Number of pages.
- onPageChange: (page: number) => void. Called with the new page.
- siblings: number (default 1). Pages shown on each side of the current one.
- summary: ReactNode. Text before the buttons.
- size: 'sm' | 'md' (default 'sm'). Button size.

### Slider
Picks a number, or a range, on a track.
- value / defaultValue: number | number[]. One number, or two for a range.
- onValueChange: (value) => void. While dragging.
- onValueCommit: (value) => void. When the person lets go.
- min / max / step: number (default 0 / 100 / 1). Scale.
- showValue: boolean. Value at the right.
- formatValue: (v: number) => string. Shown and announced text.
- thumbLabels: string[]. Names for each thumb.

### OtpInput
One-time codes, one cell per character.
- length: number (default 6). Number of cells.
- value / defaultValue: string. The code.
- onChange: (value: string) => void. On every change.
- onComplete: (value: string) => void. Once every cell is filled.
- alphanumeric: boolean. Letters too; default digits only.
- groupSize: number. A gap after this many cells.
- invalid / disabled / autoFocus: boolean. States.

### Stepper
Where someone is in a flow with a few known steps.
- steps: (string | { label, description?, optional? })[]. The steps.
- current: number (default 0). Index in progress; earlier ones are done.
- orientation: 'horizontal' | 'vertical' (default 'horizontal'). Layout.
- size: 'sm' | 'md' (default 'md'). Dot size.
- onStepClick: (index: number) => void. Lets finished steps go back.

### Sidebar
The app's main navigation. It collapses to icons with tooltips.
- items: SidebarItem[]. { label, icon?, href?, onClick?, active?, badge?, items?, defaultOpen? } or { type: 'section', label }.
- header / subheader: ReactNode. Logo row; a switcher under it (hidden when collapsed).
- footer: ReactNode | (collapsed) => ReactNode. Account, credits.
- collapsible: boolean. Shows the collapse button.
- collapsed / defaultCollapsed: boolean. Icons only.
- onCollapsedChange: (collapsed: boolean) => void. Remember it per person.
- linkAs: ElementType (default 'a'). Your router's Link.

### HoverCard
A preview of what a link points to, on hover.
- content: ReactNode. The preview.
- children: ReactElement. One link.
- openDelay / closeDelay: number (default 500 / 200). ms.
- side / align: Side / Align (default 'bottom' / 'start'). Placement.

### Calendar
A month grid for picking a date or a range.
- mode: 'single' | 'range' (default 'single'). Range values are { from, to }.
- value / defaultValue: Date | DateRange | null. Selection.
- onValueChange: (value) => void. Called on pick.
- months: 1 | 2 (default 1). Months side by side.
- min / max: Date. Limits.
- isDateDisabled: (date: Date) => boolean. Unavailable days.
- weekStartsOn: number (default 1). 0 Sunday to 6 Saturday.
- locale: string. Month and day names.

### DatePicker and DateRangePicker
Fields that open a Calendar: one date, or a range with presets.
- value / defaultValue: Date | DateRange | null. Selection.
- onValueChange: (value) => void. DatePicker: on pick. DateRangePicker: on Apply or a preset.
- placeholder: string. Shown when empty.
- DateRangePicker: presets: { label, range() }[] | false. Default: Today, Last 7 days, Last 30 days, This month, Last month, This year.
- DateRangePicker: months: 1 | 2 (default 2). Months in the popover.
- formatDate / formatRange: function. Your own text.
- size: 'sm' | 'md' | 'lg' (default 'md'). Same heights as Input.

### CommandPalette
Search every action and place from one box, with ⌘K.
- groups: { label?, items: CommandItem[] }[]. CommandItem: { label, icon?, description?, shortcut?, keywords?, onSelect?, disabled? }.
- trigger: ReactElement. A Button that opens it.
- hotkey: string | false (default 'k'). With ⌘ or Ctrl.
- open / defaultOpen / onOpenChange: boolean. Control it yourself.
- placeholder / emptyText: string / ReactNode. Texts.

### FileUpload
Drop files or browse for them; type and size are checked first.
- files / defaultFiles: UploadFile[]. { id, name, size, type?, file?, progress?, error? }.
- onFilesChange: (files) => void. New files arrive with error set when they fail.
- accept: string. Like <input accept>: .json,image/*.
- maxSize: number. Bytes.
- multiple: boolean (default true). More than one file.
- title / hint / buttonLabel: ReactNode. Texts in the drop zone.

### FileTree
Files and folders, like an export or a repo.
- items: { name, children?, meta?, icon? }[]. The tree.
- selected / defaultSelected: string | null. Path, like css/tokens.css.
- onSelect: (path: string) => void. Files only.
- expanded / defaultExpanded: string[]. Open folders.
- expandAll: boolean. Opens every folder when uncontrolled.

### Stack and Inline
Columns and rows with token gaps. Use them instead of margins between siblings.
- gap: 'none' | 'xxxs' … '4xl'. Stack default base, Inline default xs.
- align / justify: 'start' | 'center' | 'end' | 'between' …. Flex alignment. Inline centers by default.
- Stack: divider: boolean. A line between children.
- Inline: wrap: boolean (default true). Wrap onto new lines.
- as / asChild: ElementType / boolean. Render another element.

### Grid
Equal columns that collapse on small screens, or as many as fit.
- columns: 1 | 2 | 3 | 4 | 6 | 12 (default 2). Collapses to fewer on small screens.
- minChild: 'xs' | 'sm' | 'md' | 'lg'. 16, 18, 20 or 24rem minimum; overrides columns.
- gap: 'none' | 'xxxs' … '4xl'. Default base.

### Container
Centers content at a readable width, with gutters that grow with the screen.
- size: 'sm' | 'md' | 'lg' | 'xl' | 'prose' | 'full' (default 'lg'). 672, 768, 1024, 1280px, 65 characters, or none.
- padding: boolean (default true). 16, 24, then 40px gutters.

### VisuallyHidden
Text for screen readers only, and skip links.
- focusable: boolean. Visible while focused.
- as: ElementType (default 'span'). Use a for skip links.

### PageHeader
The top of a page: where you are, what this is, and the main actions.
- title: ReactNode. A noun.
- eyebrow / description / meta: ReactNode. Mono label, one or two sentences, Badges.
- actions: ReactNode. At most one primary Button.
- breadcrumbs / back: ReactNode / { label, href, onClick }. Where you came from.
- tabs: ReactNode. A TabsList under it.
- display: boolean. Fenly Serif title, for hero screens.

### Banner
One message about the whole app or page, edge to edge.
- variant: 'info' | 'neutral' | 'success' | 'warning' | 'error' | 'offer' | 'inverse' (default 'info'). Meaning.
- emphasis: 'subtle' | 'loud' (default 'subtle'). loud gives the bottom hairline the tone's color. inverse ignores it.
- title: ReactNode. Bold lead-in with a period.
- action: ReactNode. One small Button.
- onDismiss: () => void. Shows a close button.
- sticky: boolean. Stays on top while scrolling.
- live: boolean. Set when the banner appears after the page loads, so it's announced.
- toneLabel: string | false. The hidden word read first. Default Info, Success, Warning or Error.

### Tag
A small label people act on: filter by it, remove it, or read a token's color.
- variant: 'neutral' | 'accent' | 'success' | 'warning' | 'error' (default 'neutral'). Meaning.
- size: 'sm' | 'md' (default 'md'). 24 or 32px.
- swatch: string. A CSS color chip.
- icon: IconProp. Leading icon. An element like <Search /> (works in server components) or, in client components, the component itself.
- onClick / selected: function / boolean. A toggle.
- onRemove: function. Adds a remove button.

### CopyField and CopyButton
A read-only value with a copy button, and the button on its own.
- value: string. What gets copied.
- CopyField: secret / revealPrefix: boolean / number. Masks it with a Show button; keeps the first characters.
- label / copyLabel: string (default 'Copy'). Tooltip and accessible name.
- onCopy: (value) => void. After copying.

### DescriptionList
Pairs of labels and values.
- items: { term, description?, mono?, copy? }[]. The pairs.
- layout: 'horizontal' | 'vertical' | 'grid' (default 'horizontal'). Stacks on small screens.
- columns: 2 | 3 | 4 (default 3). For grid.
- dense: boolean. No dividers, tighter rows.

### Timeline
Events in order: a version history, an activity feed, the steps of a sync.
- items: { title, description?, time?, status?, icon?, content? }[]. Newest first for activity.
- status: 'default' | 'accent' | 'success' | 'warning' | 'error'. Colors the marker.
- now / locale: Date / string. For relative times.
- dense: boolean. Tighter spacing.

### Link
Text that goes somewhere. Use Button for actions.
- variant: 'default' | 'subtle' | 'standalone' (default 'default'). Weight.
- external: boolean. New tab.
- icon: IconProp. Leading icon. An element like <Search /> (works in server components) or, in client components, the component itself.
- asChild: boolean. Style your router Link.

### AlertDialog
One hard-to-undo decision: delete, discard, overwrite.
- AlertDialogContent: size: 'sm' | 'md' (default 'sm'). 384 or 512px.
- AlertDialogAction: variant: 'destructive' | 'primary' (default 'destructive'). Weight of the action.
- AlertDialogCancel: children: ReactNode (default 'Cancel'). Always Cancel.

### Drawer
A panel that rises from the bottom with a grab handle.
- open / defaultOpen / onOpenChange: boolean. Control it yourself.

### ContextMenu
Commands on right-click or long press.
- Item: icon: IconProp. Leading icon. An element like <Search /> (works in server components) or, in client components, the component itself.
- Item: shortcut: ReactNode. Shown at the end.
- Item: destructive: boolean. Red, for deleting.
- Item: onSelect: (e: Event) => void. Runs the command.

### Menubar
Desktop-style menus in a row: File, Edit, View.
- Item: icon: IconProp. Leading icon. An element like <Search /> (works in server components) or, in client components, the component itself.
- Item: shortcut: ReactNode. Shown at the end.
- Item: destructive: boolean. Red, for deleting.
- Item: onSelect: (e: Event) => void. Runs the command.

### Collapsible
One section that opens and closes.
- open / defaultOpen / onOpenChange: boolean. State.

### ScrollArea
Native scrolling with Seed's thin scrollbars.
- orientation: 'vertical' | 'horizontal' | 'both' (default 'vertical'). Scrollbars to show.
- aria-label: string. Names the region.
- viewportClassName: string. Classes for the viewport.

### ButtonGroup
Joins related buttons into one control.
- orientation: 'horizontal' | 'vertical' (default 'horizontal'). Direction.

### InputGroup
The input shell with add-ons, or a prompt box with toolbars.
- start / end: ReactNode. Text, an icon, a small Button or a Kbd.
- multiline: boolean. A textarea with top and bottom bars.
- top / bottom: ReactNode. Bars around the multiline field.
- size: 'sm' | 'md' | 'lg' (default 'md'). Same heights as Input.

### AvatarGroup
A stack of people, with presence. Avatar takes status too.
- people: { name, src?, status? }[]. In order of relevance.
- max: number (default 4). Faces before +N.
- size: 'xs' | 'sm' | 'md' | 'lg' (default 'sm'). Avatar size.
- label: string. Names the group.
- Avatar: status: 'online' | 'away' | 'busy' | 'offline'. Presence dot.

### PasswordInput
A password field with Show and Hide, and live requirements.
- requirements: { label, test(value) }[]. Rules, never errors.
- autoComplete: string (default 'current-password'). new-password when creating one.
- …: InputProps. Everything Input takes.

### TagInput
A field that turns typed text into tags.
- value / defaultValue / onValueChange: string[]. The tags.
- suggestions: string[]. Offered as people type.
- validate: (tag) => true | string. The message to show when it fails.
- max: number. Limit.
- swatchFor: (tag) => string | undefined. Color chips for tokens.

### Toolbar
A row of related tools with one Tab stop.
- orientation: 'horizontal' | 'vertical' (default 'horizontal'). Direction and arrow keys.
- ToolbarButton: asChild: boolean. Wrap a Seed Button so it joins the arrow-key order.

### Meter and ProgressRing
A level within a range, and circular progress.
- value / min / max: number. The level.
- low / high / optimum: number. Colors it like HTML's meter.
- tone: 'accent' | 'success' | 'warning' | 'error' | 'neutral'. Override.
- valueText: string. Shown and announced.
- ProgressRing: size: 'sm' | 'md' | 'lg' | 'xl' (default 'md'). 20, 40, 64 or 96px.

### Item and AspectRatio
A row for one thing, and media kept at a fixed shape.
- title / description: ReactNode. Text.
- media: IconProp | ReactNode. An icon (in a tile) or an Avatar.
- actions: ReactNode. Buttons or Badges.
- href: string. The row becomes a link.
- variant: 'plain' | 'outline' | 'muted' (default 'plain'). Frame.
- AspectRatio: ratio: number (default 16/9). Width over height.

### Typography, Heading and Text
Rendered rich text and Markdown in Seed's reading styles, and single lines of copy.
- Typography: size: 'body' | 'small' (default 'body'). 16/26 or 14/22, Fenly Serif Light.
- Heading: level / size: 1–6. Element and look.
- Heading: display: boolean. Fenly Serif, for hero screens.
- Text: variant: 'lead' | 'body' | 'small' | 'muted' | 'caption' | 'reading' | 'label' | 'value' (default 'body'). The type style.

### NavigationMenu
Site navigation: links and panels of links.
- items: NavigationItem[]. { label, href, current? } or { label, links: { label, href, description?, icon? }[], columns?, footer? }.
- linkAs: ElementType (default 'a'). Your router's Link.

### MentionInput
A text area that suggests people, tokens or components after @ or #.
- sources: Record<string, MentionItem[]>. Trigger to items: { '@': people, '#': tokens }.
- items: MentionItem[]. One source on @.
- onMention: (item, trigger) => void. After inserting.
- onSubmit: (value) => void. ⌘ or Ctrl + Enter.

### TimePicker
A time typed or picked, shown in the reader's format.
- value / defaultValue: string | null. 24-hour HH:mm.
- step: number (default 15). Minutes between options.
- min / max: string. Limits.
- hourCycle: 12 | 24. Default from the locale.

### Tour
A short guided walk: a spotlight on one element at a time.
- steps: { target?, title, body?, side?, align?, padding? }[]. target is a selector, ref or element.
- open / defaultOpen / onOpenChange: boolean. State.
- step / onStepChange: number. Current step.
- onFinish / onSkip: () => void. How it ended.

### TableOfContents
An On this page list that follows the reader.
- items: { id, label, level? }[]. Heading ids.
- root: selector | ref | element. The scrolling element, when not the window.
- offset: number (default 16). Sticky header space.
- title: ReactNode | false (default 'On this page'). Label.

### CommentThread
People's conversation pinned to something, resolvable.
- comments: { author: { name, src?, role? }, body, time?, edited? }[]. Oldest first.
- anchor: ReactNode. What it's about.
- onReply: (text) => void. Shows the reply box.
- resolved / onResolvedChange: boolean. Resolving collapses it.
- commentActions: (comment) => ReactNode. A menu per comment.

### Message
One turn in a conversation: who said it, what, and what you can do with it.
- from: 'user' | 'assistant' | 'system' (default 'assistant'). Sets side and look.
- children: string | ReactNode. A string becomes a Bubble.
- actions: ReactNode. Ghost Buttons, three or fewer.
- status: 'sending' | 'error'. Send state.
- avatar / name / time / footer: ReactNode. Optional parts.
- scrollAnchor: boolean. For MessageScroller.

### Bubble
The petal-shaped surface of one chat turn.
- variant: 'neutral' | 'ghost' | 'outline' | 'muted' | 'accent' | 'error' (default 'neutral'). Surface.
- align: 'start' | 'end' (default 'start'). Where the tight corner points.
- size: 'md' | 'sm' (default 'md'). Padding.
- href: string. Makes it a link.
- reactions: { icon?, label, count?, pressed?, onPressedChange? }[]. Small toggles under it.

### MessageScroller
The transcript: follows new output, never moves you while you read back.
- autoScroll: boolean (default true). Follow output at the bottom.
- peek: number (default 48). Previous turn left visible (px).
- defaultScrollPosition: 'end' | 'start' (default 'end'). Where it starts.
- height: number | string. Or give the parent a height.
- jumpLabel: string (default 'Jump to latest'). Button text.

### Attachment
A file in a conversation or upload list, with its state.
- name: string. File name; picks the icon.
- description: ReactNode. Type and size, or the error.
- state: 'done' | 'idle' | 'uploading' | 'processing' | 'error' (default 'done'). Upload state.
- progress: number. 0 to 100.
- src / icon: string / icon. Preview or icon.
- onRemove / actions / href: …. What you can do.
- size / orientation: 'md' | 'sm' / 'horizontal' | 'vertical'. Layout.

### CodeBlock
Code, commands, logs and diffs, with copy.
- code: string. The code.
- language: 'tsx' | 'ts' | 'js' | 'jsx' | 'css' | 'json' | 'html' | 'bash' | 'text' | 'diff' (default 'tsx'). Highlighting.
- title: ReactNode. Adds the header.
- lineNumbers / startLine / highlightLines: …. Lines.
- maxLines: number. Collapse long code.
- highlight: (line, language) => ReactNode. Your own highlighter.
- variant / size: 'default' | 'error' / 'md' | 'sm'. Look.

### Marker
A small inline line: what's happening, a note, or a labeled divider.
- variant: 'note' | 'border' | 'separator' (default 'note'). Look.
- icon: icon. Leading icon.
- status: 'running' | 'error'. State.
- href: string. Link to what it mentions.

### Trace
The steps behind an answer, folded under one line.
- steps: { title, description?, icon?, status?, detail?, href? }[]. In order.
- summary: ReactNode. Folds the trace.
- open / defaultOpen / onOpenChange: boolean (default true). Folded state.

### Questionnaire
A few questions, one at a time, before Pluto can help.
- items: { name, prompt, description?, required?, multiple?, choices?, input? }[]. The questions.
- onSubmit: (answers) => void. Answers by name.
- onCancel / cancelLabel: () => void / string (default 'Not now'). First step.
- submitLabel: string (default 'Send answers'). Last step.
- step / onStepChange: number. Controlled position.
- shortcuts: boolean (default true). Number keys.

### ColorSwatch
One color token: its color, name, value and alias, with copy.
- color: string. Any CSS color, usually var(--token).
- name: string. Token name; copied.
- value: ReactNode. Shown instead of the measured value.
- alias: ReactNode. The primitive, for the theme shown.
- usage: ReactNode. Where it's used.
- layout: 'card' | 'row' | 'chip' (default 'card'). Layout.
- size / selected / copy: …. More.

### ColorScale
A color ramp from 50 to 950 in one row.
- steps / colors: { label, color }[] / Record. The ramp, light to dark.
- name: string. Mono label.
- anchor: string. The brand step.
- showValues: boolean (default false). Hex under each step.
- value / onValueChange: string. Makes it selectable.

### TokenPreview
What a non-color token does: a bar, a corner, a shadow, motion.
- kind: 'space' | 'size' | 'radius' | 'shadow' | 'border' | 'opacity' | 'duration' (default 'space'). What to draw.
- value: string. CSS value, usually var(--token).
- display: ReactNode. Text in place of the value.
- name / usage: …. Labels.
- layout: 'row' | 'tile' (default 'row'). Layout.

### TypeSpecimen
One text style: its name, specs and a sample.
- styleName: string. The type style class.
- sample: ReactNode (default pangram). Sample text.
- specs: { family, size, lineHeight, weight, tracking }. Shown instead of measuring.
- usage: ReactNode. Where it's used.
- layout: 'row' | 'stack' (default 'row'). Layout.

### ContrastPair
A WCAG contrast check for one pair, in Light and Dark.
- fg / bg: string. CSS colors, usually tokens.
- kind: 'text' | 'large' | 'ui' (default 'text'). Threshold.
- themes: string[]. Side by side, each in its own data-theme.
- label / description: ReactNode. Heading.

### ColorPicker
Pick a color by eye or by value, with OKLCH and swatches.
- value / onValueChange: string (default '#2563eb'). Hex.
- swatches: (string | { color, name })[]. Suggestions.
- inline: boolean (default false). Panel without the trigger.
- size / invalid / disabled: …. Works in Field.

### TokenInput
Point at a token instead of a raw value.
- tokens: { name, value?, color?, kind?, icon?, group? }[]. The options; semantic first.
- value / onValueChange: string | null. The token name.
- clearable / placeholder / size: …. Combobox props.

### NumberInput
A number with a unit and steppers.
- value / onValueChange: number | null. The number.
- min / max / step: number (default step 1). Bounds; decimals follow the step.
- unit: string. px, ms, %.
- stepper: boolean (default true). Show the Buttons.

### Stage
The frame where a component or a customer's design is shown.
- title / actions: ReactNode. Toolbar.
- theme / onThemeChange: 'light' | 'dark' (default 'light'). Themes only the frame.
- width / widths: 'full' | 'desktop' | 'tablet' | 'mobile' (default 'full'). Preview widths.
- background: 'checker' | 'plain' (default 'checker'). Canvas.
- height / align / toolbar: …. Layout.

### PropsTable
A component's API as a table.
- props: { name, type?, default?, required?, description? }[]. The rows.
- component: string. Names the table.
- stackOnMobile: boolean (default true). Below 768px each prop is a card: name, then Type, Default and Description.

### Chart
Bar, stacked, line and area charts with a tooltip, keyboard reading and a table view.
- type: 'bar' | 'stacked' | 'line' | 'area' (default 'bar'). Form.
- data: Record<string, number | string>[]. Rows.
- x: string (default 'x'). Key for the horizontal axis.
- series: { key, label?, color? }[]. Stable order; palette in that order.
- title / description: ReactNode. Caption.
- height: number (default 240). Plot height (px).
- valueFormat / xFormat: (v) => string (default compact). Formatting.
- labels: 'end'. Direct labels.
- legend / toolbar: boolean (default true). Legend and table toggle.
- defaultView: 'chart' | 'table' (default 'chart'). Start view.

### StatTile
One number that answers a question at a glance.
- label: ReactNode. Sentence case.
- value: ReactNode. Numbers get separators.
- delta: number | { value, unit?, display?, period?, goodWhen? }. Change.
- trend: number[]. Sparkline.
- icon / size / format: …. More.

### DataTable
Records with search, sorting across pages, columns, pagination and bulk actions.
- columns: { key, header, render?, align?, sortable?, sortValue?, hideable? }[]. Columns.
- rows: object[]. Records.
- rowKey: string | (row, i) => key (default 'id'). Identity.
- pageSize: number (default 10). Rows per page.
- noun: [string, string] (default ['row', 'rows']). Summary words.
- selectable / bulkActions: boolean / (rows, clear) => ReactNode. Selection.
- sort / onSortChange: { key, dir } | null. Sorting.
- toolbar: ReactNode. Buttons on the right.
- stackOnMobile: boolean (default true). Below 768px each row is a card under a bar of sort buttons.
- loading / empty / density / onRowClick: …. More.

### Carousel
A row of slides that scrolls sideways. No autoplay.
- items / children: ReactNode[]. Slides.
- slidesPerView: number (default 1). Fractions hint at more.
- loop: boolean (default false). Wrap around.
- showDots: boolean (default true). Dots or '2 / 6'.

### Resizable
Panels split by handles people drag.
- direction: 'horizontal' | 'vertical' (default 'horizontal'). Split.
- sizes / onSizesChange: number[]. Remember a layout.
- withHandle: boolean (default false). Grip on handles.
- ResizablePanel: { defaultSize?, minSize?, maxSize?, label? } (default min 10, max 90). Each panel.

### DirectionProvider
Sets right-to-left or left-to-right for everything inside.
- dir: 'ltr' | 'rtl' (default 'ltr'). Direction.
- wrap: boolean (default true). Render a wrapper with dir.

### RichTextEditor
A WYSIWYG editor that emits clean HTML.
- defaultValue / value / onChange: string (HTML). Content.
- toolbar: RteTool[] (default all). Tools; '|' separates.
- placeholder: string. Empty text.
- minHeight / maxHeight: number | string (default 160). Size.
- maxLength / showCount: number / boolean. Counting.
- readOnly / disabled / invalid: boolean (default false). States.
- pasteFormatting: boolean (default false). Keep formatting on paste.