# Wallarm Design System

> React components, tokens and AI tooling for Wallarm products

## Get Started

- [Introduction](https://wallarm.github.io/design-system/get-started/introduction.md): What the Wallarm Design System is, what it is built on and where to find it.
- [Installation](https://wallarm.github.io/design-system/get-started/installation.md): Install the design system and its peer dependencies, then set up Tailwind, the theme CSS and ThemeProvider.
- [Theming](https://wallarm.github.io/design-system/get-started/theming.md): Light and dark themes, the frame style, and overriding design tokens with CSS variables.
- [Routing](https://wallarm.github.io/design-system/get-started/routing.md): Connect links, navigation and RemoteShell to TanStack Router, React Router or Next.js.
- [Migration guides](https://wallarm.github.io/design-system/get-started/migrations/index.md): Upgrade across breaking design-system releases with the @wallarm-org/migrator codemod CLI.
- [Migrating to v4](https://wallarm.github.io/design-system/get-started/migrations/v4.md): Upgrade to v4.0.0, where the unused TreeBase subpath is removed.
- [Migrating to v3](https://wallarm.github.io/design-system/get-started/migrations/v3.md): Upgrade to v3.0.0, where Avatar sizes are renamed and Avatar gains a user-item composition.
- [Migrating to v2](https://wallarm.github.io/design-system/get-started/migrations/v2.md): Upgrade to v2.0.0, where NumericBadge type splits into type and color.
- [Migrating to v1](https://wallarm.github.io/design-system/get-started/migrations/v1.md): Upgrade to v1.0.0, where Table moves to TanStack Table v9.
- [Changelog](https://wallarm.github.io/design-system/get-started/changelog.md): Release notes for every @wallarm-org/design-system version.

## AI

- [MCP server](https://wallarm.github.io/design-system/ai/mcp.md): Connect Claude Code, Cursor or VS Code to the design-system MCP server for component and token metadata.
- [llms.txt and Markdown](https://wallarm.github.io/design-system/ai/llms.md): Machine-readable versions of this site for AI assistants and LLMs — llms.txt, Markdown pages and components.json.
- [Claude Design](https://wallarm.github.io/design-system/ai/claude-design.md): Prototype with the real Wallarm components, tokens, fonts and icons in Claude Design.

## Guides

- [Testing](https://wallarm.github.io/design-system/guides/testing.md): Target design-system components in Playwright and Testing Library with cascading data-testid values.
- [Analytics](https://wallarm.github.io/design-system/guides/analytics.md): Attach your analytics attributes and handlers to design-system components; they land on the real interactive element.

## Foundations

- [Tokens](https://wallarm.github.io/design-system/foundations/tokens.md): Wallarm design system tokens: color palettes, semantic light and dark colors, spacing, typography, radius, shadow, blur, focus and icon sizes, with their values.
- [Icons](https://wallarm.github.io/design-system/foundations/icons.md): Import icons from the icons entry point, size them and give meaningful icons a title.

## Components

- [Button](https://wallarm.github.io/design-system/components/button.md): Triggers an action — reach for `Link` when the control navigates somewhere instead, `ToggleButton` when it stays switched on, and `SplitButton` or `DropdownMenu` when several related actions compete for one slot. Keep one `variant='primary'` per view, and reserve `color='destructive'` for actions that are hard to undo.
- [DropdownMenu](https://wallarm.github.io/design-system/components/dropdown-menu.md): A menu of actions hanging off a trigger — reach for `Select` when the reader is choosing a value for a form, since a menu runs commands rather than holding an answer. Leave the primary action visible as a `Button` and put only the secondary ones in here; past roughly ten items, group them or move them somewhere with room.
- [SplitButton](https://wallarm.github.io/design-system/components/split-button.md): Pairs one action with a menu of related ones, for when a second action matters enough that burying it in a `DropdownMenu` would hide it. Both halves are ordinary `Button`s, so they must share a variant, colour and size — the group only joins their facing corners.
- [ToggleButton](https://wallarm.github.io/design-system/components/toggle-button.md): A button that stays pressed — for something the reader flips in place and can see the result of, like pinning a panel or holding a filter on. Reach for `Switch` when it belongs in a settings form, and `SegmentedControl` when one of several options has to win.
- [Checkbox](https://wallarm.github.io/design-system/components/checkbox.md): Collects any number of choices from a limited set, or turns a single option on or off — reach for `Radio` when only one choice is allowed, and `Switch` when the change takes effect immediately instead of on submit. Past roughly ten options, a `Select` reads better than a long column of boxes.
- [Field](https://wallarm.github.io/design-system/components/field.md): The scaffolding around a control — label, description, error and the required marker — so the control itself only has to be the control. Only `Input`, `Textarea` and `Slider` read this context automatically; wrap anything else and you get the layout, but the labelling still has to be wired by hand.
- [FileUpload](https://wallarm.github.io/design-system/components/file-upload.md): Attaches files to a form and checks their type, size and count before accepting them — the drop Area when attaching is the main task on the screen, the "Select file" button when space is tight. Picking never uploads: files travel with the form when it is saved, and the product marks a row `loading` while it sends one. To pick a photo by clicking an avatar, see Data Display/Avatar → Click To Upload.
- [ImageCropper](https://wallarm.github.io/design-system/components/image-cropper.md): Select part of an image by moving and zooming it inside a fixed frame, then export a Blob at the exact outputSize. The frame follows the output aspect ratio and preserves the source proportions. Compose Slider for zoom, FileUpload for choosing a file, and your own Save action through ImageCropperContext. All processing runs in the browser; the consumer owns uploading. Preview rounding is visual only: the saved image is rectangular. Remote images need crossOrigin="anonymous" on ImageCropperImage and server CORS permission for canvas export; local file/object URLs also work. Size the preview with width classes; CSS scale transforms on ancestors are not supported by the underlying crop geometry. Arrow keys pan, Shift accelerates, and +/− zoom.
- [InlineEdit](https://wallarm.github.io/design-system/components/inline-edit.md): Turns a displayed value into its own editor, so a reader can correct one field without opening a form — reach for a form when several values change together. Every story composes it inside an `Attribute`, because that is what keeps the read and edit states the same height and stops the row jumping on toggle.
- [Input](https://wallarm.github.io/design-system/components/input.md): Short, single-line free text — reach for `Textarea` when the answer runs to sentences, and `Select` when it comes from a known set. Wrap it in `Field` for the label and description; a placeholder is an example of the answer, never a substitute for the label and never where required information lives.
- [InputGroup](https://wallarm.github.io/design-system/components/input-group.md): Joins a field to whatever sits against it — an icon, a unit, a shortcut hint, a button — inside one bordered box that focuses as a single control. Reach for `Field` instead when what you need is a label and a description rather than something attached to the field itself.
- [InputOTP](https://wallarm.github.io/design-system/components/input-otp.md): A short code split into one cell per character, for codes that arrive by mail or from an authenticator — reach for `Input` for anything the reader knows by heart. Six cells by default, and `groupSize` inserts separators so the reader can check what they typed against what they were sent.
- [NumberInput](https://wallarm.github.io/design-system/components/number-input.md): A number the reader nudges rather than types from scratch — reach for `Input` when the figure is just data like a port or an ID, and `Slider` when the position matters more than the exact value. It starts at zero rather than empty, so pass `defaultValue` wherever a pre-filled zero would be mistaken for an answer.
- [PasswordInput](https://wallarm.github.io/design-system/components/password-input.md): A password field with a reveal toggle, which is the whole point of reaching for it over an `Input` of type password. Where rules are enforced, pair it with `PasswordComplexity` so the reader watches them being met rather than discovering them on submit.
- [Radio](https://wallarm.github.io/design-system/components/radio.md): Picks exactly one option from a set — reach for `Checkbox` when several answers can be true at once, and `Select` past roughly ten options. Radios cannot be cleared once chosen, so include the neutral answer as an option rather than expecting the reader to undo.
- [SearchInput](https://wallarm.github.io/design-system/components/search-input.md): A search field with a magnifying-glass icon and a clear button that appears once there is a value. Controlled only — pass `value` and `onChange`, and optionally `onClear` to react to the clear button specifically.
- [SegmentedControl](https://wallarm.github.io/design-system/components/segmented-control.md): Switches between renditions of the same content, with every option visible — reach for `Tabs` when the sections are distinct places rather than views of one thing, and `Radio` when the choice is an answer a form submits. It owns no panel: it reports the chosen value and you re-render the content yourself.
- [Select](https://wallarm.github.io/design-system/components/select.md): Holds one answer, or several, chosen from a list — below about six options expose them instead with `Radio` or `SegmentedControl`, and reach for `DropdownMenu` when the items run commands rather than set a value. The trigger is composed rather than configured: `SelectButton` for a button-shaped trigger, `SelectInput` for one that looks like a field.
- [Slider](https://wallarm.github.io/design-system/components/slider.md): Sets an approximate, bounded value by dragging along a track — reach for `NumberInput` when the exact figure matters, since a slider is faster to move than it is to land. A slider should always show its value: pair it with `SliderInput` for entry, or `SliderValue` for a readout. It implies a continuum, so a few fixed choices belong in `SegmentedControl`, `Radio` or `Select`, and on/off in `Switch`.
- [Switch](https://wallarm.github.io/design-system/components/switch.md): Turns one setting on or off, and takes effect the moment it is flipped — reach for `Checkbox` when the answer is submitted with a form, and `ToggleButton` when the control belongs in a toolbar rather than a settings list. Because there is no Save to undo it, avoid a switch for anything destructive or slow.
- [Textarea](https://wallarm.github.io/design-system/components/textarea.md): Multi-line free text, for answers that run to sentences — reach for `Input` when one line will do, since a tall box tells the reader to write more than you want. Like `Input`, it reads `Field` context for its label, description and error state.
- [Calendar](https://wallarm.github.io/design-system/components/calendar.md): The month grid for choosing a date the reader needs to see in context — a weekday, a distance from today — where `DateInput` is for a date they already know. It is its own popover, so compose a trigger beside it rather than wrapping it in one, and take React Aria date objects rather than a JavaScript `Date`.
- [DateInput](https://wallarm.github.io/design-system/components/date-input.md): A date typed segment by segment, for a date the reader knows — pair it with `Calendar` when they need to see the month to choose. It takes React Aria date objects rather than a JavaScript `Date`, and segment order and hour cycle come from `DateFormatProvider` app-wide rather than per input.
- [DateRangeInput](https://wallarm.github.io/design-system/components/date-range-input.md): Two dates in one field, for a period the reader knows — pair it with `Calendar` in range mode when they need to see the months to choose. Same rules as `DateInput`: React Aria date objects, and order and hour cycle from `DateFormatProvider` rather than per input.
- [TimeInput](https://wallarm.github.io/design-system/components/time-input.md): A time typed segment by segment, the companion to `DateInput` — `showTimeDropdown` adds a list of times for when the reader would rather pick than type. It takes React Aria time objects, and hour cycle comes from `DateFormatProvider` app-wide rather than per input.
- [Accordion](https://wallarm.github.io/design-system/components/accordion.md): Stacks sections behind their own headers and opens each on demand — reach for `Tabs` when a few primary sections get switched between often, and leave content on the page when people read most of it anyway. `primary` and `secondary` are inline rows for grouping; `section` is the bordered panel, and the only variant with room for `AccordionActions`.
- [Attribute](https://wallarm.github.io/design-system/components/attribute.md): Pairs one field's label with its value on a detail page — reach for `Table` when the same fields repeat across many objects, and `Field` when the value is being collected rather than read. The value slot takes whichever display component fits the data and hosts `InlineEdit` when the field is editable in place, while `AttributeActions` hangs a per-value menu off it.
- [Avatar](https://wallarm.github.io/design-system/components/avatar.md): A person's photo on a rounded plate, falling back to initials or an icon while it loads, when it fails, or when there is none. It is decorative beside a visible name; standing alone, give it `aria-label` so it reads as an image. Add `AvatarContent` with `AvatarName` (and an optional `AvatarDescription`) for the user item: plate and name in one row. To let people change it, make the avatar the `FileUploadTrigger` (`asChild`) and give it `as='button'` — picking only previews, and your form uploads.
- [Card](https://wallarm.github.io/design-system/components/card.md): Holds one self-contained thing — a metric, an integration, a saved view — in a block you can compare against its neighbours in a grid; reach for `Table` when the same fields repeat down a list, and for a `Heading` when you only mean to section a page. Passing any handler turns the whole card into the target: it becomes focusable and picks up hover and pressed overlays, while clicks on a link or button inside it stay with that control.
- [CodeEditor](https://wallarm.github.io/design-system/components/code-editor.md): An editable code surface that is visually the same component as `CodeSnippet` and reuses its header, tabs, actions and show-more — reach for `CodeSnippet` whenever the code is only read, since a page that never renders `CodeEditorContent` never loads the editor engine. Colours come from the same `CodeSnippetAdapterProvider` (plain text without one), so a read-only editor matches the snippet except for a native thin scrollbar, a caret and selection drawn by the editor, and an HTTP JSON body that stays coloured when `Content-Type` has parameters or the body has blank lines. The adapter re-tokenizes the whole document after each pause in typing, which stays within a frame up to about 2 000 lines with Prism; longer documents still edit smoothly, their colours just settle a moment later. Like the snippet, the editor sits inside a `display: contents` wrapper that keeps it mounted across fullscreen, so space editors with their own `className` (for example `mt-16`) or a `gap` on the parent — not `space-*`, `divide-*` or child selectors on the parent. `lines`, `folds`, `completions` and `schema` are compared by identity, so memoise them or hoist them to module constants — a new value on every render reconfigures the editor. Autocomplete suggests language keywords and words already in the document for every language; HTTP methods and headers and JSON Schema values have their own contextual suggestions. Pass `completions` to add application-specific results. Syntax errors are best-effort: JSON reports the `JSON.parse` message, JavaScript and TypeScript use Babel, Lua uses luaparse (first error only), YAML and Python use their Lezer parsers, which still flag a few valid Python forms such as `lambda a, /, b` and parenthesised `with` items. `lines` and `folds` stay on their line numbers while typing; to keep a decoration on a piece of text, recompute it from `value` (for example `useMemo(() => linesFor(value), [value])`, or a `folds` function such as `getHttpFolds`). The editor injects `<style>` tags, so under a strict Content Security Policy pass `cspNonce`. Tab indents, so keyboard users leave with Escape, then Tab, or press Ctrl+M (Alt+Shift+M on macOS) to switch Tab between indenting and moving focus — point `aria-describedby` at text holding `CODE_EDITOR_KEYBOARD_HINT` to tell screen-reader users.
- [CodeSnippet](https://wallarm.github.io/design-system/components/code-snippet.md): A block of code to be read and copied, never edited — reach for `InlineCodeSnippet` when the code belongs inside a sentence, and a real editor when the value is meant to change. Everything beyond the code is composed: a `CodeSnippetHeader` carrying a title or tabs, `CodeSnippetActions` for copy, wrap and fullscreen, `CodeSnippetLineNumbers`, and per-line colour, prefixes and folds — and highlighting happens only inside a `CodeSnippetAdapterProvider`. The snippet sits inside a `display: contents` wrapper that keeps it mounted across fullscreen, so space snippets with their own `className` (for example `mt-16`) or a `gap` on the parent — not `space-*`, `divide-*` or child selectors on the parent.
- [Country](https://wallarm.github.io/design-system/components/country.md): Shows one country from its ISO 3166-1 alpha-2 code — `CountryFlag`, `CountryName`, or both — and only ever a country: a flag names a place, not a language. Compose the name next to the flag wherever the reader could be in any doubt, and expect an unrecognised code to drop the flag and print the code itself.
- [FormatDateTime](https://wallarm.github.io/design-system/components/format-date-time.md): Prints a timestamp the way the house date guide says to: `relative` by default for anything recent, `date` when only the day matters, `datetime` when the exact moment does. Relative stops being relative as a date ages — past roughly five months it prints the day and month, past a year it adds the year — and it always carries the full absolute time, timezone included, in a tooltip.
- [FormatNumber](https://wallarm.github.io/design-system/components/format-number.md): Prints a number the way the house number guide says to: abbreviated by default — `12k`, `59.6M` — with the full figure in a tooltip behind a dashed underline. `type` chooses the family: `decimal`, `percent`, which refuses to round to a flat `0%` or `100%` it has not earned, and `byte`, which counts in units of 1000.
- [HttpMethod](https://wallarm.github.io/design-system/components/http-method.md): Renders an HTTP method as a fixed-colour code `Badge` — the colour is part of the vocabulary rather than a choice: safe reads green, destructive rose, the technical verbs slate. A verb outside the seven known ones prints verbatim in slate, so nothing unexpected is swallowed; reach for `Badge` itself when what you are labelling is not a method.
- [Ip](https://wallarm.github.io/design-system/components/ip.md): One IP address and what is known about it — the country it resolves to, the port, the provider owning the range — composed as a row in which the address is the identity and everything else is context. `IpList` collapses a set of them: vertical keeps the first and hides the rest behind a `+N addresses` link, horizontal fits as many as the width allows and puts the remainder in a `+N` badge.
- [List](https://wallarm.github.io/design-system/components/list.md): A semantic `ul` or `ol` with its spacing and markers under control — reach for `ordered` only when the sequence matters, and for a `Table` as soon as each item carries fields of its own. Markers are off by default and `role="list"` is set either way, so a list without bullets is still a list to a screen reader.
- [OverflowList](https://wallarm.github.io/design-system/components/overflow-list.md): Lays a set of items out in one row and folds whatever will not fit into an overflow control — reach for `OverflowTooltip` instead when the thing overrunning is a single run of text rather than a set. By default the overflow is a `+N more` chip opening a popover of every item; compose it yourself from the `OverflowListMore` parts (`Trigger`, `Content`, `Header`, `Items`, `Count`), or pass any `overflowRenderer(hiddenItems, { allItems, visibleItems })` of your own. It re-measures whenever the container changes width.
- [ParameterPath](https://wallarm.github.io/design-system/components/parameter-path.md): Shows where in a request a parameter lives — the method, then each container down to the parameter itself, with the last segment highlighted and carrying a bolt when `attack` marks it as the one that was hit. Copying a path yields a `FilterInput` query rather than the text on screen — `method = "POST" AND parameter = "JSON.nginx_config"` — so a finding can be pasted straight into a search.
- [PasswordComplexity](https://wallarm.github.io/design-system/components/password-complexity.md): The rules a password has to meet, ticked off as it meets them — show them from the moment the field appears rather than after a failed submit, and keep the same set everywhere a password is created. The component only paints: you compute each rule's `met` and pass it in, with `passwordValidators` shipped alongside for that. A satisfied rule is struck through and steps back, so what is left to do is what stands out.
- [ResponseCode](https://wallarm.github.io/design-system/components/response-code.md): Renders an HTTP status code as a code `Badge` coloured by its class — green for success, blue for a redirect, amber for a client error, red for a server error, slate for informational. A mask counts as well as a number, so `2XX` or `40X` from a filter suggestion takes the colour of its leading digit, and anything outside 100–599 falls back to slate rather than guessing. Pairs with `HttpMethod`.
- [Selection](https://wallarm.github.io/design-system/components/selection.md): Turns a set of anything — cards, rows, list items — into a selectable collection: a checkbox on each one, shift-click for a range, and a bulk-action bar that arrives once something is ticked. The selection is controlled and ordered by `items`, so what comes back follows the list rather than the order of clicks, and ids no longer present in `items` are kept rather than dropped — a selection can outlive a page change, and clearing it is the caller's decision.
- [SimpleCharts](https://wallarm.github.io/design-system/components/simple-charts.md): SimpleCharts: live examples, usage and props for the SimpleCharts component.
- [Table](https://wallarm.github.io/design-system/components/table.md): The grid for many records of one shape — reach for a `Card` grid when a row reads better as an object than as a set of columns, and for `Attribute` when you are showing one record rather than many. Everything interactive is controlled: sorting, selection, expansion, column order, pinning, sizing and visibility are each a state prop with a callback, so nothing moves unless you move it, and `manualSorting` hands the sort to the server. Filtering belongs above the grid in a `FilterInput`, and a long collection scrolls rather than paginates — `Pagination` is the deliberate exception, for when a page number is part of the task.
- [Timeline](https://wallarm.github.io/design-system/components/timeline.md): A vertical run of events in the order they happened — a timeline records what occurred, so reach for `Progress` when the question is how far along something is rather than what has already taken place. `TimelineConnector` and `TimelineContent` are each optional, and the last item looks after itself: its line and its bottom padding go without any special casing.
- [AppShell](https://wallarm.github.io/design-system/components/app-shell.md): The platform’s outermost frame — global top bar, product rail, and the content surface products mount into, with an optional `AppShellAside` panel docked to its right. There is exactly one, at the app root, and it persists while the content swaps. Do not wrap a page in it: a single product screen renders `RemoteShell` and its own content, blind to the shell. In-product navigation is `NavPanel`, and laying out a page’s insides is `Stack` and `Flex`. The gray surround — header bar plus rail, everything that is not the canvas — is the **Frame**. It carries **Ambient**, a faint still layer of soft blooms, grain and a dot cluster pooled bottom-left, painted under everything. Ambient is on by default; `ambient={false}` leaves the flat Frame fill. The Frame comes in two styles, **Neutral** and **Branded**: a user preference next to light/dark, set with `useTheme().setFrameStyle` (from `ThemeProvider`) and written on `<html>` so every micro-frontend follows it. Branded warms the Frame and turns active navigation to the brand colour; try it from the account item → Appearance.
- [Breadcrumbs](https://wallarm.github.io/design-system/components/breadcrumbs.md): The location trail for a page that sits deep in a hierarchy — each ancestor links up, and the last item is the page you are on. Skip it in a flat app of one or two levels, and never use it to move between peers at the same level: that is `Tabs`. It shows vertical hierarchy only, and complements the sidebar rather than replacing it.
- [Link](https://wallarm.github.io/design-system/components/link.md): The navigation member of the Actions family — a styled `<a>` that takes the reader somewhere. If activating it changes where you are it is a `Link`; if it does something in place it is a `Button`, however text-like it looks. `type` is semantic, so never hand-colour a link, and the hover underline is automatic. Link text has to describe its destination — “Click here” and “Learn more” read as nothing in a screen reader’s link list.
- [Pagination](https://wallarm.github.io/design-system/components/pagination.md): Page-through navigation for a bounded set — previous and next, numbered pages with automatic ellipsis, and an optional rows-per-page selector. Infinite scroll is the house default for long data, so this is the deliberate alternative: reach for it when knowing and controlling your position genuinely helps — jumping to a page, coming back to page two, choosing a page size. “Lots of rows” on its own is not the cue. It is compound, so render only the parts you want, in the order you want.
- [RemoteShell](https://wallarm.github.io/design-system/components/remote-shell.md): The frame of one product inside `AppShell` — its navigation panel, breadcrumbs and content area, all driven by a single `NavConfig`. The URL is the state: the active item, the drill level and the breadcrumbs are matched from the pathname. When a router owns the URL, hand the shell the router’s pathname through `pathname` and take its navigations back through `onNavigate` — then links in the page, the host rail or `router.navigate` keep the menu in sync. Without `pathname` the shell reads `window.location` and only notices `popstate` and its own navigations.
- [SearchModal](https://wallarm.github.io/design-system/components/search-modal.md): A command-palette dialog opened with Cmd+K (Ctrl+K on Windows/Linux). Provides a search input, grouped item lists, keyboard navigation, and a footer with keyboard hints. Content is consumer-assembled: the component is a composable shell, not a hard-wired feature.
- [SegmentedTabs](https://wallarm.github.io/design-system/components/segmented-tabs.md): The pill-skinned tab set: it owns its panels like `Tabs` but wears `SegmentedControl`’s look. Reach for it for scoped views of a single collection — All / Active / Blocked — or as a second level under primary `Tabs`, never as a page’s main tabs. The line against `SegmentedControl` is whether selecting changes *which* content shows (here) or only *how the same content looks* (there). Keep the set short: overflow goes to a “More” menu, since these pills do not scroll.
- [Stepper](https://wallarm.github.io/design-system/components/stepper.md): A horizontal row of numbered steps for a flow that is split into a few screens, such as a create drawer — it shows where the reader is and lets them jump to any step. It is compound, like Ark UI Steps: `count` on the root and `index` on every `StepperItem` and `StepperContent` are explicit. `StepperContent` shows the current step’s body, and `StepperPrevTrigger` / `StepperNextTrigger` move between steps; Next stops at the last step, where the page renders its own submit button. It never blocks a step: the page owns each step’s `status` (`completed`, `danger`, `upcoming`), and the current step always renders as active. Reach for `Timeline` for a history of events, `Tour` for guided onboarding, `Progress` for how far along a task is, and `Tabs` for sections that have no order.
- [Tabs](https://wallarm.github.io/design-system/components/tabs.md): Switches between a few peer sections of one page without going anywhere — `Tabs` owns the panels, which is what separates it from `SegmentedControl`. Underline tabs are the default for a page’s primary division; reach for `SegmentedTabs` for scoped views of one collection or a second level below these, `SegmentedControl` for a toggle that owns no panel, and `Accordion` when the sections should be open at once.
- [Tree](https://wallarm.github.io/design-system/components/tree.md): Draws structure: a vertical rail and depth indentation around nested content, with optional per-item collapse. It shows a hierarchy rather than letting you work in one — reach for `TreeView` when rows need selecting, keyboard navigation or disabled states, and for `Accordion` when the levels are sections rather than a tree.
- [TreeView](https://wallarm.github.io/design-system/components/tree-view.md): The interactive hierarchy: rows that expand, select and disable, with the connector rails drawn for you. Reach for `Tree` when you only need to *show* nesting — this one is for working in it. Rows are composed freely, so an icon, a badge or a checkbox is just a child, and nested `TreeViewItem`s become the subtree.
- [Dialog](https://wallarm.github.io/design-system/components/dialog.md): A panel the reader has to resolve before carrying on — reach for `Drawer` when they should be able to keep it open and keep working, and `Popover` when the content is a detail rather than a task. It is `Drawer` with `kind='dialog'`, which shares the panel but keeps the two families' nesting separate: a dialog only steps back for another dialog.
- [Drawer](https://wallarm.github.io/design-system/components/drawer.md): A side panel for work the reader does alongside the page — its differentiator is that it can run non-modal, so with `modal={false}` they can keep using what is behind it. Reach for `Dialog` when the panel is a decision to resolve now, since that is the same panel with the exit closed off.
- [FeedbackPulse](https://wallarm.github.io/design-system/components/feedback-pulse.md): Asks one question in place, for measuring how a change landed without sending the reader to a survey. It is deliberately small and skippable: one question, an optional comment, and a timeout that dismisses it if the reader ignores it.
- [OverflowTooltip](https://wallarm.github.io/design-system/components/overflow-tooltip.md): Shows the full value only when it is actually truncated, so a reader who can already see the text is not given a tooltip that repeats it. It finds the truncating element itself, so wrap the content rather than pointing it at a node.
- [Popover](https://wallarm.github.io/design-system/components/popover.md): A small panel anchored to what opened it, for content the reader can act on — a form, a set of controls, a detail with a link in it. Reach for `Tooltip` when the content is only a label, and `Drawer` when it is a task rather than a detail.
- [Tooltip](https://wallarm.github.io/design-system/components/tooltip.md): A short label on hover or focus, for naming something the interface cannot afford to spell out — an icon button, a truncated value. It holds no interactive content and cannot be reached by keyboard beyond its trigger, so anything the reader needs to click belongs in a `Popover`.
- [Tour](https://wallarm.github.io/design-system/components/tour.md): A guided walk through the interface, for a feature the reader would not find on their own — configured with `useTour({ steps })` and one rendered `Tour`. It owns how a step looks, not when the tour runs: deciding who sees it and how often is the application's job.
- [Alert](https://wallarm.github.io/design-system/components/alert.md): An inline message bound to one part of the screen, which stays until the state changes or the reader dismisses it — reach for `Banner` when the message would still matter on another page, `Toast` for a transient confirmation, and the field’s own error for a single invalid input. `color` carries the meaning and `AlertIcon` takes its icon from it, so the pair is not yours to mix; `primary` is the neutral default for a notice with no status to encode.
- [Banner](https://wallarm.github.io/design-system/components/banner.md): A full-width message pinned above the header, for something account- or system-wide. The test is whether it would still matter on another page: yes and it is a `Banner`, no and it is an `Alert`. There is no success variant — “it worked” is a `Toast` — and no `icon` prop either: the icon appears only when a `BannerIcon` is composed in.
- [Toast](https://wallarm.github.io/design-system/components/toast.md): A transient notification fired from `useToast()` — you never place one in the tree, and a single `Toaster` at the app root owns placement, stacking and the timer. Because it disappears, nothing may live only here: reach for a `Dialog` when the reader has to decide, `Banner` for standing account state, and `Alert` for a message that belongs to a region. Actions on a toast stay optional for the same reason.
- [Badge](https://wallarm.github.io/design-system/components/badge.md): The status chip the rest of the family is built from — reach for the dedicated component when one exists (`HttpMethod`, `ResponseCode`, `Ip`, `Country`) rather than rebuilding it here, and for `Tag` when the chip is interactive. Colour carries the meaning, so choose it from what the value is rather than from what looks right on the page.
- [Indicator](https://wallarm.github.io/design-system/components/indicator.md): A coloured dot for a state next to something that already names it — a row, a tab, an item in a list. Reach for `Badge` when the state needs naming, since colour on its own carries nothing for a reader who cannot separate the hues.
- [NumericBadge](https://wallarm.github.io/design-system/components/numeric-badge.md): A compact count, `!` / `?` glyph, or icon attached to a tab, button, menu item, or step.

`type` sets the visual weight and `color` sets the meaning. Supported combinations:

- `solid`: `brand`, `danger`
- `secondary`: `neutral`, `neutral-alt`, `info`, `success`, `danger`, `brand`
- `outline`: `neutral`, `success`, `danger`, `brand`

The default is `secondary` / `neutral`. With `type="solid"`, the default color is `brand`.

`size="default"` corresponds to Medium (20px tall, 16px icon); `size="small"` is 16px tall with a 12px icon. Pass content as children and give an icon-only badge an accessible name when it conveys meaning.

Hover and focus states apply to clickable badges. Use `asChild` with a native button or link when the badge is an action or navigation target.

Migration from the removed flat `type` API:

| Previous type | New type | New color |
| --- | --- | --- |
| `primary` | `secondary` | `neutral` |
| `primary-alt` | `secondary` | `neutral-alt` |
| `brand` | `solid` | `brand` |
| `destructive` | `solid` | `danger` |
| `outline` | `outline` | `neutral` |
| `info` | `secondary` | `info` |
- [Tag](https://wallarm.github.io/design-system/components/tag.md): An interactive chip for a keyword or attribute the reader can select or remove — a chip that only states a value is a `Badge`. Give it one job: Carbon warns against tags carrying several functions at once, and a chip that both filters and deletes is one people trigger by accident.
- [AnimatedBackground](https://wallarm.github.io/design-system/components/animated-background.md): The decorative backdrop behind the surfaces that have no chrome of their own — sign-in, the splash screen, the assistant. `pixel`, the default, sweeps a canvas dot grid; `blur` drifts a mesh gradient. Children sit centred above it. It is `aria-hidden` and lets the pointer through, with one exception: the pixel variant’s `game`, which takes pointer events for as long as it is running.
- [Flex](https://wallarm.github.io/design-system/components/flex.md): A flex container with the properties as props — `direction`, `justify`, `align`, `wrap`, plus `basis` fractions and `grow` / `shrink` for how the children size themselves. Reach for `Stack`, or `HStack` / `VStack`, when all you want is a spaced list in one direction: `Stack` carries a default gap where `Flex` has none. `Flex` takes no `className`, so everything goes through props.
- [Page](https://wallarm.github.io/design-system/components/page.md): The frame a microfrontend page renders into — a header carrying the title and its actions, then the content below. It tells the host shell how it wants to be laid out (`fullSize`, `fixedHeight`) through context and falls back to sensible behaviour when there is no host, so the same page works inside the console and on its own.
- [Resizable](https://wallarm.github.io/design-system/components/resizable.md): A layout primitive that splits a view into resizable panels separated by draggable handles. Wraps `react-resizable-panels` with design-system styling.
- [ScrollArea](https://wallarm.github.io/design-system/components/scroll-area.md): A scroll container with the house scrollbar instead of the browser’s: compose `ScrollAreaViewport` › `ScrollAreaContent`, then one `ScrollAreaScrollbar` per axis and a `ScrollAreaCorner` where two of them meet. It can only scroll inside a bounded parent, so give the wrapper a height or a width — with nothing to overflow, the content simply grows.
- [Stack](https://wallarm.github.io/design-system/components/stack.md): A column or row of children with a gap from the spacing scale — `gap` defaults to 4, which is the practical difference from `Flex`. Reach for `VStack` or `HStack` rather than `Stack` with a `direction`: they read better in a tree, and `HStack` centres its items for you. Children have to be elements — a bare string is dropped rather than rendered.
- [Loader](https://wallarm.github.io/design-system/components/loader.md): A spinner for a short, in-context wait you cannot measure — one thing at a time, placed where the waiting is happening. Reach for `Skeleton` when a page, list or table is loading a layout you already know, and for `Progress` when you can measure the wait or it runs past about ten seconds, where a spinner starts to read as frozen; a `Button` carries its own loading state, so never put one beside a button. It ships no label and no live region of its own, so the announcement has to come from a `role="status"` element around it.
- [Progress](https://wallarm.github.io/design-system/components/progress.md): A linear bar for an operation you can measure, or a long or multi-step one where watching it advance is the reassurance — a short in-context wait is a `Loader`, and a page loading a known layout is `Skeleton`. `value={null}` makes it indeterminate: use that rather than a spinner for a long wait you cannot measure, switch to a real number the moment you can, and never fake a percentage. Linear only — the system has no circular progress, so do not hand-roll a ring.
- [Skeleton](https://wallarm.github.io/design-system/components/skeleton.md): A content-shaped placeholder for a region whose layout you know but whose data has not landed — it shortens the perceived wait and stops the page jumping when the content arrives. Reach for it on the first or full load of a page, list, card or table; a single inline wait is a `Loader`, a measurable one is `Progress`, and a wait under a second wants nothing at all. Never put a skeleton and a spinner in the same region. The root is `aria-hidden`, so the loading announcement has to come from a live region of your own.
- [SplashScreen](https://wallarm.github.io/design-system/components/splash-screen.md): The full-screen entrance for a cold start — the brand `Logo` over an indeterminate bar, shown once while the app boots. Never on a route change and never as a general loading veil: in-app waits belong to `Loader`, `Skeleton` or `Progress`, and `AppShell` ships its own first-load reveal, so run one or the other rather than both. You drive `visible` and nothing else — the phases between are internal — and since it enforces no minimum on-screen time, guarding against a flash on a fast boot is the caller’s job.
- [Code](https://wallarm.github.io/design-system/components/code.md): Geist Mono for code, identifiers and machine-readable values — anything read as literal rather than as prose. This ramp is for inline fragments; multi-line blocks are `CodeSnippet`, drawn with looser leading so stacked lines breathe.
- [Heading](https://wallarm.github.io/design-system/components/heading.md): Geist for titles and section headings, where hierarchy comes from the size step — reach for `Text` when the words are copy rather than a title. Visual size and document level are independent: pick `size` for how it looks and `as` for the outline, so a visually small heading can still be the `h2` the structure needs.
- [Text](https://wallarm.github.io/design-system/components/text.md): Geist for body copy, labels and anything read as prose — reach for `Heading` when the text is a title and `Link` when it navigates. Weight carries emphasis and colour carries de-emphasis, so build hierarchy from those rather than by changing size.
- [Kbd](https://wallarm.github.io/design-system/components/kbd.md): Shows a keyboard shortcut as a `<kbd>` cap. It is display-only — the DS binds nothing, so the `keydown` handler stays yours — and `Code` is the one to reach for when what you are showing is a value rather than a key. One cap holds one key and `KbdGroup` sets out a combination; render the modifier symbols (⌘, ⇧, ⌥, ↵) rather than the words, so the same shortcut reads the same everywhere.
- [Overlay](https://wallarm.github.io/design-system/components/overlay.md): The house scrim — a fixed, dimmed, lightly blurred layer that mutes the page behind an elevated surface. `Dialog`, `Drawer` and `Tour` render it for you, so reach for those; a popover, tooltip or dropdown is non-modal and takes no scrim at all. It is presentation only: no focus trap, no click-to-dismiss, no scroll lock, and no `className`.
- [Separator](https://wallarm.github.io/design-system/components/separator.md): A 1px rule for the places where whitespace alone does not show that one group has ended — reach for `Stack` gaps first, because a drawn line is a statement. Most families ship their own (`DropdownMenuSeparator`, `SelectSeparator`, `FieldSeparator`, `NavRailSeparator` and the rest) already carrying that context’s defaults; the raw primitive is for generic content. It is decorative by default, so set `decorative={false}` only when the line marks a boundary a screen-reader user should hear.
- [Copyable](https://wallarm.github.io/design-system/components/copyable.md): Click-to-copy is a **behaviour pattern**, not a component.
Any existing element — a Button, InlineCodeSnippet, Attribute value, table cell, or DropdownMenuItem — copies a value on click and confirms it.

### Feedback rules

1. **Element can change itself** (button, icon button, code snippet action): swap in place. Copy icon → Check, label "Copy code" → "Copied" at the idle width, tooltip "Click to copy" → "Copied".
2. **Clickable text without an icon** (inline code snippet, a value): tooltip only.
3. **Element disappears after the action or has nothing to transform** (menu item): toast "Copied".

Never two feedbacks at once. Copied state resets after ~2 s.
- [FilterCascade](https://wallarm.github.io/design-system/components/filter-cascade.md): A filter over a hierarchy — organization › deployment › application, region › zone. The same 36px pill as `FilterDropdown`; each level opens as its own panel beside the option that opened it, and an item at any depth can be picked. The trigger reads the path: «Scope ● a › ● b», the tooltip carries it whole. Items are the consumer’s own objects, read through accessors; a level can load when it is first opened (`loadChildren`), and `parentLabel` adds the option that picks the level’s parent — «Deployment level». The search finds items at every depth. Compose the panels with `FilterCascadeLevels` to add group labels and options set apart; with no children, `FilterCascadeContent` renders the levels by itself. Reach for `FilterDropdown` when the values are flat.
- [FilterDropdown](https://wallarm.github.io/design-system/components/filter-dropdown.md): A lightweight filter for a list or table toolbar: a 36px trigger that opens a menu and narrows the list by one attribute. Picks apply at once — there is no Apply step. Single mode is for exclusive values and starts with «All …», which is also the reset; multi mode ticks several values that are OR-ed and clears with the ✕. From eight options the menu gains a search, and in multi mode a "Selected" section on top. Reach for `Select` inside forms, and for `FilterInput` when the query combines several attributes and operators.
- [FilterInput](https://wallarm.github.io/design-system/components/filter-input.md): A config-driven query builder — `fields` metadata in, an `ExprNode` tree out of `onChange` — for filtering a data-dense resource. Reach for a row of `Select`s instead when three or four facets picked by equality would do; reach for this when the attribute count is high, or the query needs AND/OR, grouping, or operators like `between` and `like`. The menus, chips and connectors are internal, so what you own is the field config.
- [EmptyState](https://wallarm.github.io/design-system/components/empty-state.md): EmptyState communicates that a space has no content — whether because a collection is empty, a search returned no matches, or a filter is too narrow. Use compound components: EmptyStateIllustration, EmptyStateMessage, EmptyStateTitle, EmptyStateDescription, EmptyStateActions, EmptyStateLink.

`type` picks the scale, and every slot follows it from context — no need to restate it on children. `collection-empty` is the page-level treatment: a medallion (a 36px raised tile holding a 20px icon), a pixel title, and room for actions plus a link. `no-results` is the compact inline treatment for a card, dropdown or select menu: 240px wide, with a 14px secondary title. An illustration always carries the medallion — there is no bare glyph.

Scale is not the same question as cause. A page-level "no filter matches" state still uses `collection-empty` — it just drops the create CTA and offers a neutral one instead.
- [UtilityPage](https://wallarm.github.io/design-system/components/utility-page.md): The whole-screen state template — 404, 403, 500, offline — for when the app itself cannot render; reach for `EmptyState` when only a region came back empty, and `Banner` or `Alert` when the app still works and this is only a message. It replaces the view and brings its own background and `Logo`, so what you supply is copy and one primary way out, not a layout.
- [ApprovalCard](https://wallarm.github.io/design-system/components/approval-card.md): Asks the user to approve an action Wally wants to take — a tool call, a config change — before it runs. While `status` is `pending` the card shows its children (`ApprovalCardContent` and `ApprovalCardActions`); once the app sets `approved` or `rejected`, the children are replaced by a one-line status, so the buttons need no gating of their own. The card has no outer margins or horizontal padding: the panel gutter (`ChatBody` / `ChatFooter`) places it, whether it sits inline in the conversation or docked above the input. Buttons are plain DS components composed by the app, which also owns loading — disable them while the request is in flight.
- [AssistantMessage](https://wallarm.github.io/design-system/components/assistant-message.md): A message from Wally: an `<article>` named "Wally" that left-aligns the answer and whatever led up to it. Stack its parts in this order — an optional `ChainOfThought` with the reasoning and tool calls, an optional `ApprovalCard`, the `AssistantMessageContent`, then a `MessageActions` row; the message spaces them 12px and 4px apart and lines the action icons up with the text. `AssistantMessageContent` spaces and styles markdown blocks; put `AssistantMessageMarkdown` inside it (WallyAssistant's default) or your own renderer's output. `AssistantMessageMarkdown` renders untrusted GFM as DS elements — no raw HTML, http/https/mailto/relative links only, images as alt text — and is streaming-safe: pass the whole text so far with `streaming` and it repairs only the unfinished tail. Set `aria-busy` on the message while the answer streams; before the first output, show only an `AssistantMessageLoader` "Working..." row, and if the answer fails, an `AssistantMessageError` after the content with your own Retry button in `action`.
- [ChainOfThought](https://wallarm.github.io/design-system/components/chain-of-thought.md): A read-only log of what Wally did while answering — searches, tool calls, its own reasoning — so the user can see how it got there without the steps crowding the answer. Each `ChainOfThoughtStep` is one line: a type icon, a label and an optional right-aligned metric, joined to the next step by a thin connector. A step with children becomes a collapsible trigger, and children can be another `ChainOfThought`, so runs nest as deep as the agent did. The app owns the mapping from step type to icon (see **Type Icons**); the DS only draws the row.
- [Chat](https://wallarm.github.io/design-system/components/chat.md): The Wally assistant panel: a header, a scrolling message log, and a footer gutter for suggestions, a docked approval card and the input. `Chat` is layout only — it holds no messages or agent state; the app renders `UserMessage`, `AssistantMessage` and `ChatInput` into `ChatBody` and `ChatFooter` from its own data. Header actions are composed from plain ghost `Button`s and vertical `Separator`s, so each one keeps its own `aria-label` and analytics attributes. `background` picks the decorative mesh: `strong` for an empty chat, `subtle` (default) once a conversation is running, `none` to drop it. Host the panel in a right-hand `Drawer` about 480px wide; `ChatBody` exposes its scroll element through `ref` for stick-to-bottom.
- [ChatInput](https://wallarm.github.io/design-system/components/chat-input.md): The composer at the bottom of the Wally chat: a growing textarea where Enter sends and Shift+Enter adds a line, with the send button turning into Stop while a reply streams. It is controlled — the app owns the draft and the running state — and any actions such as `ChatPermissions` go between the textarea and `ChatInputSubmit`.
- [ChatPermissions](https://wallarm.github.io/design-system/components/chat-permissions.md): The settings button in the chat composer that lists which Wally tools may run without asking first in this conversation. Each row is a switch and takes effect the moment it is flipped — there is no Save, and the popover stays open so several tools can be changed in one go. The app owns the list and its order: enabled tools first, then a `Separator` and the disabled ones.
- [Conversation](https://wallarm.github.io/design-system/components/conversation.md): Stick-to-bottom for the Wally log: `Conversation` takes `ChatBody`’s place between `ChatHeader` and `ChatFooter`, and `ConversationContent` renders the built `ChatBody` (`role=log`) as the scroller. While an answer streams the view follows it; once the reader scrolls up it stops following and `ConversationScrollButton` appears. Scrolling back down, clicking the button or changing `autoScrollKey` (pass the last user message id) re-sticks. `ConversationEmptyState` is the greeting for an empty chat, rendered inside the scroller. The scroll button is the stock small icon-only Button, floated at the bottom centre.
- [MessageActions](https://wallarm.github.io/design-system/components/message-actions.md): The small row of icon buttons under a chat message — copy, feedback, a more menu and a timestamp. Every `MessageAction` is a ghost icon button whose required `aria-label` doubles as its tooltip, so the row never needs a visible caption. By default the row is transparent until the nearest `group/message` parent is hovered or holds focus, keeping its 30px height so the conversation does not jump; pass `visible` for the latest answer. Copy is composed with `Copyable` and `CopyableIcon`, menus with `DropdownMenuTrigger asChild`, and feedback with `aria-pressed` — the row itself holds no state. Give a menu-trigger action an explicit `data-testid`: the trigger injects its own `--trigger` id, which replaces the cascaded `--action` one.
- [UserMessage](https://wallarm.github.io/design-system/components/user-message.md): A message the user sent to Wally: an `<article>` named "You" that right-aligns a light-brand bubble. The bubble keeps the text’s whitespace and clamps it to 11 lines; when it overflows, a fade appears with a Show more / Show less toggle that reports `aria-expanded` and points `aria-controls` at the text. The toggle is `UserMessageShowMore`, rendered by default — pass your own instance through `showMore` for custom labels or `data-*` attributes, or `null` for none. Put a `MessageActions` row (timestamp, then Copy) after the bubble; it is revealed when the message is hovered or focused.
- [WallyAssistant](https://wallarm.github.io/design-system/components/wally-assistant.md): The closed Wally panel: pass a `ChatSnapshot` (messages, status, suggestions, permissions, context) and callbacks, and it renders the whole Figma chat — header, stick-to-bottom log, greeting, chain of thought, docked approval and input. It holds no agent state: the app folds its stream into a new snapshot on every delta. Send is blocked while the last message has a pending approval (typing still works), and a resolved card stays docked until the next message. Every rule lives in exported pieces — `ChatViewProvider`, `deriveChatState`, `ChatMessageView`, `ChatPartView` — so a custom layout reuses them (Custom Layout). Seams like `renderPart`, `renderStepContent` and `renderMessageActions` hand back the default rendering. Stories are driven by `useMockWally()` from `WallyAssistant/mocks` and keep feedback and permissions in app state. Messages render with the default `AssistantMessageMarkdown`, and fenced code highlights with the lazy Prism adapter WallyAssistant mounts unless the app provides a `CodeSnippetAdapterProvider`.
- [WallySkeleton](https://wallarm.github.io/design-system/components/wally-skeleton.md): Use the same WallySkeleton while the host downloads the assistant remote, the remote checks access, and the runtime connects. Import it from `@wallarm-org/design-system/WallySkeleton` without loading WallyAssistant or its markdown renderer. Give the parent a height; the skeleton fills it. Placeholders and the decorative mesh are static, so remounting between loading stages preserves the image, including with reduced motion. The surface announces “Loading Wally”; override `aria-label` for localization. It has no interactive controls.
- [Logo](https://wallarm.github.io/design-system/components/logo.md): The Wallarm logo in its three forms — `icon`, `wordmark` and `full` — sized by height, with the width following. `color` is a decision about the surface rather than a style choice: `default` on light, `white` on a dark surface where the mark should keep its brand colour, and `full-white` only where the whole lockup has to be a single colour. It renders a bare `svg` with no accessible name, so pass an `aria-label` where the logo is the only thing naming a link, and leave it unlabelled where a heading beside it already does.
- [WallyIcon](https://wallarm.github.io/design-system/components/wally-icon.md): Wally, the mascot for Wallarm’s AI assistant — the mark that signals an AI surface rather than a general-purpose icon, so keep it for the assistant and reach for the icon set for everything else. `simple` is the bare mark and `circle` wraps it in its own badge so it can sit on a coloured surface; both are sized by height from 16px to 64px, with the width following.