Windcraft

Component contracts.

The grammar your AI tools generate against — every component’s variants, sizes, and rules, in one place.

forms

ButtonPrimary interactive control for triggering actions. Use whenever a user must commit a decision (save, submit, confirm, cancel, navigate to a destructive flow).
IconButtonSquare button rendering only an icon. For dense toolbars, table rows, and headers where a label would crowd the layout.
ToggleButtonButton that maintains a pressed state — visual "this option is currently active". Use for view modes, filters, and segmented controls.
InputSingle-line text entry control. The default form primitive; ~80% of form fields are this.
TextareaMulti-line text entry. Use when expected input exceeds ~80 characters.
NumberInputNumeric input with steppers. For quantities, ages, durations.
PasswordInputPassword entry with reveal/hide toggle and optional strength meter.
SearchSpecialised input for query/find flows. Includes leading magnifier, clear button, and built-in debounce contract.
OTPInputSix-digit one-time-passcode input for 2FA / email verification.
SelectChoose one option from a fixed (≤30) list. For >30 use Combobox. For ≤5 use a SegmentedControl.
ComboboxSearchable dropdown for >30 options. Filters as the user types.
MultiSelectPick multiple from a list. Renders selections as chips inside the trigger.
CheckboxIndependent boolean toggle. Often grouped under a single Label/Legend.
RadioMutually exclusive choice within a RadioGroup. Use ≤5 options; for more, use Select.
SwitchiOS-style toggle for binary settings. Activates immediately on tap (no apply button).
SliderContinuous or stepped numeric range — for volume, opacity, price ranges.
DatePickerCalendar-based date selection. Trigger is an input + calendar icon; opens a popover with month grid.
DateRangePickerTwo-thumbed date selector. Defaults to two-month side-by-side calendar.
TimePickerHour + minute selector. Locale-aware 12/24h.
FileUploadDrag-and-drop + click-to-browse file input. With progress and error per file.
ColorPickerColor selection with HEX/RGB/HSL tabs and a saturation/value canvas. Used in admin tooling and theming UIs.

display

AvatarCircular representation of a user, organisation, or system entity. Falls back from image → initials → generic icon.
AvatarGroupStacked avatars with overlap. Truncates with "+N" when over the limit.
BadgeSmall status pill — for state on a card, list row, or inline tag.
TagUser-applied label for filtering/categorisation. Removable; differs from Badge (system-applied).
ChipCompact selectable item used in filter rows and contact pickers.
CardGrouped surface for related content. Most common composition primitive.
AlertInline non-dismissible notice tied to a section. For warnings/errors that aren't toasts.
BannerFull-width notice at the top of a page or layout. For account-wide events.
ToastTransient feedback message. Slides in from the bottom-right (desktop) or top (mobile).
TooltipHover/focus-triggered explanation. For icon-only buttons and disabled states only.
PopoverClick-triggered floating panel for richer content than a tooltip.
SkeletonLoading placeholder that mirrors the shape of the eventual content.
ProgressDeterminate progress bar. For uploads, multi-step flows, and rate limits.
SpinnerIndeterminate progress indicator. Use only when total time is unknown.
StatSingle big number with an optional label and trend.
KPIStat + sparkline + period selector. Card-sized; for the top of dashboards.
EmptyStatePlaceholder shown when a list, search, or feature has no content yet. Always offers a next step.
ErrorStatePage-level or section-level failure surface. Different from Toast (transient) and Alert (in-flow).

navigation

HeaderTop app bar — branding, primary navigation, account menu, search.
SidebarPersistent vertical navigation. The default left rail in dashboards.
TabsSwitch between sibling views in the same scope. Keyboard-driven.
BreadcrumbHierarchical location indicator. For deep object trees.
PaginationPage-by-page navigation for lists and tables.
StepperSequential step indicator for multi-page flows (onboarding, checkout).
NavigationMenuMulti-column dropdown for marketing site nav (Apple-style mega-menu).
CommandPaletteCmd+K palette — search-first navigation surfacing actions, navigations, recents.
MobileTabBarBottom tab bar for mobile-first apps (iOS-style).

layout

ContainerCentred horizontal max-width wrapper. The outermost layout primitive on most pages.
StackFlexbox primitive. Lays children in a row or column with consistent gap.
GridCSS Grid primitive with responsive column counts.
DividerHairline separator. Horizontal by default; vertical when in a row.
ScrollAreaCustom scrollbar with overlay scroll behaviour.
AspectRatioResponsive box that maintains a fixed ratio.
SheetEdge-anchored panel that slides in for secondary tasks.
ModalCentred, blocking surface for short flows. Use Dialog for confirmations, Sheet for browse/edit.
DialogConfirmation modal — focused decision surface.
ContextMenuRight-click contextual actions.
DropdownMenuClick-triggered actions menu.
DrawerMobile-first bottom sheet that slides up from the screen edge.

data

TableStatic tabular data. Use DataTable when you need sort/filter/pagination.
DataTableInteractive table with sort, filter, pagination, and row selection.
ListVertical list of items. Lighter than Table — no columns.
ListItemSingle row inside a List. Image + title + subtitle + meta + chevron.
TreeViewExpandable hierarchy — files, org charts, nested categories.
CalendarMonth/week/day calendar view. For booking flows, schedules, agenda boards.
KanbanColumnSingle vertical column of cards in a Kanban board.
TimelineVertical list of events ordered chronologically.

media

IconSF-Symbol-paired icon primitive. Names map 1-to-1 with the project tokens.sfSymbols entries (e.g. "settings" → SF "gearshape" / lucide-react "Settings"). Pick the semantic name; the renderer picks the right glyph for the platform.
ImageOptimised image with built-in loading + alt enforcement.
VideoInline video player. Lighter than a Lightbox; auto-pauses out of viewport.
LightboxFull-screen image viewer with zoom + keyboard navigation.
GalleryGrid of images that opens into a Lightbox.
ThemeToggleLight / Dark / System tri-state toggle. Lives in the header or settings.
LocaleSwitcherLanguage / region selector. Lives in the header or settings footer.
KeyboardShortcutVisual representation of a keyboard shortcut (kbd elements).
FormComposite of inputs + actions with validation, submission, and error summarisation.