# SW3 UI SDK (@peerproblem/sw3-ui) > An agentic design system: React components, design rules and tokens that agents can read, build with and operate. Squircle surfaces, motion presets, Unovis charts and MapLibre maps. Setup: `import "@peerproblem/sw3-ui/styles.css"` once, wrap the app in ``, add `className="sw-root"` to the page. Charts: `@peerproblem/sw3-ui/charts`. Maps: `@peerproblem/sw3-ui/map`. Optional peers: install `@unovis/react@~1.8.1 @unovis/ts@~1.8.1 d3-hierarchy@^3.1.0` for charts or `maplibre-gl@^6.18.0` for maps. Every rendered component has `data-sw=""` with state in data-*/ARIA attributes. Design check: `npx --no-install sw3-check src` for source diagnostics, `checkDesign(viewRoot)` from `@peerproblem/sw3-ui/check` for a rendered view. ## How to read these docs 1. Read `llms/foundations.txt` once. It separates structure rules (always) from the default look (change it with tokens). 2. Read the topic file for what you are building. A settings form needs `forms`; a dashboard needs `dashboards`, then `charts`. 3. For a single component, read `components/.md`. 4. `registry.json` has the same data as JSON. `llms-full.txt` has everything in one file, for tools that cannot follow links. ## Topics - [Foundations](llms/foundations.txt) (35 KB): Design principles (structure vs. look), color, type, corners, motion, layout, dark mode, tokens, SwProvider. Read once per task. - [Actions, layout and display](llms/actions-and-layout.txt) (71 KB): Buttons, toolbars, cards, accordions, scroll areas, badges, stats, tables, progress, toasts and other building blocks. - [Inputs, selection and dates](llms/forms.txt) (95 KB): Text fields, Field wiring, switches, sliders; Select, Combobox, Autocomplete, Listbox, RadioGroup; date and time pickers. - [Overlays and navigation](llms/overlays-and-navigation.txt) (53 KB): Dialogs, drawers, popovers, menus, tooltips; tabs, command palette, pagination, breadcrumbs, navigation menus. - [Dashboards](llms/dashboards.txt) (32 KB): AppShell, SidebarNav, DashboardGrid: dashboard frame, density, list interactions and chart choice per tile. - [Charts](llms/charts.txt) (30 KB): @peerproblem/sw3-ui/charts: which chart answers which question, ChartCard, labeling, raw Unovis inside ChartSurface. - [Maps](llms/maps.txt) (11 KB): @peerproblem/sw3-ui/map: MapLibre maps with routes, pins and areas, bundler setup. - [Agents](llms/agents.txt) (25 KB): Design check, operating rendered pages, the agent bridge (snapshot / query / act, WebMCP), AgentConsole and CitationChip. - [Hooks and utilities](llms/hooks.txt) (7 KB): useReorder, useAsyncOptions, useShortcut and other hooks for building with SW3. - [Extras](llms/extras.txt) (24 KB): @peerproblem/sw3-ui/extras: PosterCard, ActionSquare, PillButton, Canvas, WeekSchedule. Use only when the request names the pattern. - [Build and contribute components](llms/extend.txt) (6 KB): Build a new component from SW3 primitives and add it to the SDK. - [Tokens](tokens.md): Every CSS variable with light and dark values. ## Components ### Foundations - [SwProvider](components/provider.md): Sets the theme and motion defaults for all SW3 components. Wrap the app once. - [Squircle](components/squircle.md): Smoothed corners for any element. Use or combine useSquircle() with . - [Typography](components/typography.md): Display, Outline, Heading, Text, Link, Caption and Kbd: the type scale for pages, panels and inline text. - [Preferences](components/preferences.md): Applies user preferences (theme, reduced motion, contrast, density, font size) as data-* attributes on , saves them to localStorage and a cookie, and ships a ready-made settings panel. ### Actions, layout and display - [Button](components/button.md): A squircle button with press motion. Ink, app-brandable accent and quiet variants. - [Card](components/card.md): A squircle surface with a 1px frame. Plain by design: no background patterns, no hover movement. - [Badge](components/badge.md): A small pill label for status, counts and tags. - [Stat](components/stat.md): A KPI: mono label, big tabular number, colored delta, optional sparkline. - [Toggle / ToggleGroup](components/toggle.md): A button that stays pressed (aria-pressed). ToggleGroup is a row of them for toolbars and filters: several on at once, or one that can be cleared. One tab stop, arrow-key focus. - [Separator](components/separator.md): A 1px hairline between groups of content, horizontal or vertical, optionally with a mono caption ("OR"). - [Meter](components/meter.md): A value in a known range (storage, quota, score), coloured good / so-so / bad from low, high and optimum like a native . - [Progress](components/progress.md): Task progress: a bar that fills as work completes (determinate) or slides while the amount is unknown (`value={null}`). - [Skeleton](components/skeleton.md): A static squircle placeholder that reserves space while content loads. - [EmptyState](components/empty-state.md): A heading and optional action for a view with no content to display. - [Toast](components/toast.md): Imperative notifications — `toast("Saved")` — stacked in a host: actions, promise states, pause on hover, swipe to dismiss, announced politely. - [Accordion](components/accordion.md): Stacked sections whose headings expand and collapse their panels, with an animated height. - [Collapsible](components/collapsible.md): One trigger that shows and hides one panel, with an animated height. - [Toolbar](components/toolbar.md): A row of buttons, toggles, links and fields with a single tab stop; arrow keys move between them. - [Tree](components/tree.md): A hierarchy with expandable branches, folder/file icons and single or multiple selection (APG tree view). - [ScrollArea](components/scroll-area.md): Native scrolling with slim overlay scrollbars, edge fades, and an optional stick-to-bottom mode for chat logs. - [Resizable](components/resizable.md): Panel groups split by draggable, keyboard-operable handles, with min/max, collapsible panels and saved layouts. - [Carousel](components/carousel.md): Slides on native scroll-snap with Previous / Next, page dots, keyboard paging and optional autoplay with a pause control. - [Table](components/table.md): Read structured rows and columns with sortable headers and keyboard-accessible horizontal scrolling. - [Avatar](components/avatar.md): A person or team picture that shows initials (or an icon) while the image loads and if it fails; AvatarGroup overlaps several with a "+N" count. - [Timeline](components/timeline.md): Dated events in order — activity feeds, changelogs, run or order progress — with complete/current/upcoming markers and one tab stop that arrow keys move. - [Waterfall](components/waterfall.md): Trace or network spans as bars on one shared time axis; nested spans expand and collapse (treegrid), bars are colored by kind with the chart palette, and hover shows details. ### Inputs, selection and dates - [Switch](components/switch.md): An on/off toggle with a spring-animated thumb, optionally with label and description. - [SegmentedControl](components/segmented-control.md): Pick one of 2–5 options; the active pill glides between segments (motion layout animation). - [Input](components/input.md): A text field with label, hint, error and optional prefix/suffix, in a squircle frame. - [Field](components/field.md): Connects one form control to its label, description and error (ids, for, aria-describedby, aria-invalid, required, disabled). - [Label](components/label.md): Names any control; pressing it focuses or activates the control, even groups a native label cannot reach. - [Textarea](components/textarea.md): Multi-line text field that grows with its content between minRows and maxRows, with an optional character count. - [Checkbox / CheckboxGroup](components/checkbox.md): A squircle box with an animated check: checked, unchecked or indeterminate. CheckboxGroup shares one array value and supports a select-all parent. - [RadioGroup / Radio](components/radio.md): One choice out of a few, all visible: radio dots, or card rows with icons (`variant="card"`). Arrow keys move and check; submits natively with `name`. - [Slider](components/slider.md): Pick a number or a range by dragging or with the keyboard. Steps, marks, Intl-formatted value and onValueCommit for saving. - [NumberInput](components/number-input.md): A number field with − / + steppers, min/max/step snapping, Intl formatting (currency, percent, units) and spinbutton keys. - [PasswordInput](components/password-input.md): A password field with an eye / eye-off reveal toggle and a Caps Lock hint. Hides again when its form submits. - [OTPInput](components/otp-input.md): One-time-code entry: N squircle boxes backed by one real input, so paste fills every box and phones autofill the code from a message. - [Rating](components/rating.md): Star rating: a radio group of scores with hover preview, half steps, keyboard, and a read-only mode that shows any fraction. - [Select](components/select.md): Pick one or several options from a popup list, with groups, optional search inside the dropdown, and a native form value. - [Listbox](components/listbox.md): An always-visible framed list to pick one or several options, with one tab stop and full keyboard support. - [Combobox](components/combobox.md): A searchable select: type to filter a popup list and pick one value, or several shown as chips. Async-friendly. - [Autocomplete](components/autocomplete.md): A text field with suggestions: the value is whatever is typed, and picking a suggestion fills it in. - [Trigger Menu](components/trigger-menu.md): Suggestions at the caret when a trigger like @, / or # is typed in a textarea, input or Token Input; inserts the chosen item. - [Token Input](components/token-input.md): A text field that mixes editable text with tokens (people, files, tags) shown as chips; tokens come from Enter/comma, a Trigger Menu or code. - [Calendar](components/calendar.md): An inline month grid for picking one date, several dates or a range, with full grid keyboard support. Values are ISO date strings. - [DateInput](components/date-input.md): Segmented date entry: month, day and year are spinbuttons in the order and with the separators of the user's locale. Value is ISO "YYYY-MM-DD". - [DatePicker](components/date-picker.md): DateInput plus Calendar in a popup: type a date or pick it from the month grid. Single date or a range, optional presets; submits ISO. - [TimeInput](components/time-input.md): Segmented time entry — hour, minute, optional second and AM/PM on 12-hour locales. Value is 24-hour ISO "HH:mm". - [ColorPicker](components/color-picker.md): Pick a color with a saturation/brightness area, hue and alpha sliders, a text field that accepts any CSS color, and preset swatches. The value is a CSS color string. - [FileInput](components/file-input.md): Choose, drop or paste files; validate type, size and count; list them with remove; submit them with a form through a real file input. - [ImageCropper](components/image-cropper.md): Move and resize a crop over an image (or pan and zoom the image under a fixed frame) with pointer and keyboard; the crop is {x, y, width, height} in image pixels, and cropImage() turns it into a Blob. ### Overlays and navigation - [Popover](components/popover.md): A small non-modal dialog anchored to its trigger for a quick task with form content: share a link, rename, filter with fields. - [Tooltip](components/tooltip.md): A short plain-text hint that names or describes a control on hover and keyboard focus. - [HoverCard](components/hover-card.md): A preview card for a link (person, repo, doc) on hover or keyboard focus; the link still navigates. - [Dialog](components/dialog.md): A modal squircle panel over a dimmed page for a focused task, with focus trap, scroll lock, Escape and backdrop dismissal. - [AlertDialog](components/alert-dialog.md): A modal question that needs an explicit answer — Cancel or the action — plus an imperative `await confirm({...})`. - [Drawer](components/drawer.md): A sheet that slides in from an edge (bottom by default); drag it toward its edge to dismiss, with optional snap points. - [Menu](components/menu.md): A popup list of actions opened from a button, or at the pointer on right-click (ContextMenu), with groups, checkboxes, radios, submenus and shortcut hints. - [Menubar](components/menubar.md): A horizontal bar of menus (File, Edit, View) with one tab stop, arrow keys between menus and hover-switching while one is open. - [Command](components/command.md): A command palette: a search field over grouped commands with shortcuts and nested pages; `CommandDialog` opens it with ⌘K. - [Tabs](components/tabs.md): A list of tabs with a sliding indicator, each showing one panel. Automatic or manual activation, horizontal or vertical. - [NavigationMenu](components/navigation-menu.md): Site navigation: a row of triggers that open panels of links on hover or press, plus plain top-level links. - [Pagination](components/pagination.md): Numbered pages with ellipses and Previous / Next, as buttons (onPageChange) or links (getHref). - [Breadcrumbs](components/breadcrumbs.md): Where you are in the hierarchy ("Acme / API / Incidents") for the shell header. Middle items shrink first. ### Dashboards - [AppShell](components/app-shell.md): The frame of a dashboard: a header, a sidebar that folds to a rail, a main region and an inspector, all joined by 1px lines. - [SidebarNav](components/sidebar-nav.md): Dense sidebar navigation: 28px rows with icons, counts and hover actions, plus groups that fold. In the rail it becomes icon buttons with tooltips. - [DashboardGrid](components/dashboard-grid.md): A 12-column grid of DashboardTiles that share 1px lines in one frame, or sit apart as separate cards. Tiles reorder by their header grip, and DashboardSection folds a row. ### Charts - [TrendChart](components/trend-chart.md): A small time-series chart for dashboard tiles and KPI cells. The fill fades to nothing, the line is 2px, the latest value gets a dot, a crosshair scrubs, and there are options for a previous period, a threshold, event markers and an unfinished last bucket. - [BarList](components/bar-list.md): Ranked rows with a bar behind each label: top endpoints, traffic by country, spend by team. The bar is the row background. - [Tracker](components/tracker.md): Status ticks over time, one per day or run (uptime, checks, job runs). Hover or use ←/→ to read a tick. - [ChartCard](components/chart-card.md): A Card laid out for a chart: title, description, headline value, actions, chart, legend. - [ChartSurface](components/chart-surface.md): Themes any raw @unovis/react chart with SW3 tokens — for Sankey, Graph, Timeline, Chord, Heatmap, maps and every other Unovis type. - [LineChart](components/line-chart.md): Trends over time for 1–5 series. Built on Unovis VisLine. - [AreaChart](components/area-chart.md): Volume over time; overlapping translucent areas or stacked part-to-whole. Built on Unovis VisArea. - [BarChart](components/bar-chart.md): Compare categories, grouped or stacked, vertical or horizontal. Built on Unovis VisGroupedBar / VisStackedBar. - [ScatterChart](components/scatter-chart.md): Correlation between two numeric fields, optional size field. Built on Unovis VisScatter. - [DonutChart](components/donut-chart.md): Part-to-whole for 2–6 slices with a central label. Built on Unovis VisDonut. - [Sparkline](components/sparkline.md): A tiny axis-less trend line for Stats and table cells. - [Treemap](components/treemap.md): Part-to-whole for many items, optionally grouped one level deep. Squircle tiles with concentric inner corners and HTML labels that fit the tile. ### Maps - [MapView](components/map-view.md): A MapLibre GL map in a squircle Card with routes, pins, categorized locations, and highlighted areas. ### Agents - [CitationChip](components/citation-chip.md): An inline source reference that opens citation details and a link to the original source. - [Agent bridge](components/agent-bridge.md): Lets an AI agent list the SW3 components on a page and change them through their APIs: snapshot, query, act, subscribe, WebMCP. - [AgentConsole](components/agent-console.md): A chat panel that turns a request into agent-bridge steps and runs them one at a time: it marks each field it changes, logs the exact agent.act() call and its result, then sums up. ### Hooks and utilities - [useReorder](components/reorder.md): The headless drag-and-drop and keyboard reordering behind Listbox and DashboardGrid. Use it for your own sortable rows, chips or columns. - [useAsyncOptions](components/async-options.md): Hook that loads list items as someone types: debounced, cancels stale requests, keeps old results while loading, pages with loadMore. - [useShortcut](components/shortcuts.md): Keyboard shortcuts with platform-aware hints. `mod` is ⌘ on Apple and Ctrl elsewhere. `shortcuts.list()` exposes them to agents. ### Extras - [PosterCard](components/poster-card.md): A gallery tile: tight display words (outlined + solid) top-left, a mono caption under them, and a live component below. Height follows content. - [ActionSquare](components/action-square.md): A text label paired with a squircle icon tile ("Learn more [+]", "Close [−]"). - [PillButton](components/pill-button.md): A fully rounded button with an optional leading icon ("Export", "View tasks"). - [WeekSchedule](components/week-schedule.md): A week board — day columns × hour rows with meeting, focus and away blocks you drag to move, drag by the bottom edge to resize, or nudge with arrow keys; shows the hours booked. - [Canvas](components/canvas.md): A small design artboard of rectangles, ellipses and display text: click to select, drag to move, corner handles to resize, with a built-in layers / X·Y·W·H / fill / opacity inspector.