# ionbase-ui > IonBase is a React design system for enterprise SaaS, built to be consumed by an agent rather than read by a developer. Every component ships a machine-readable contract carrying the judgement a type signature cannot: when to use it, what to use instead, the anti-patterns, and what it guarantees for accessibility versus what it requires of you. Version 0.138.1. 131 components. ## Read these, in this order 1. `dist/meta/index.json` — every component with its summary and variant axes. Pick one from here. 2. `dist/meta/.json` — the full contract for that one component: props with their origins and defaults, variant guidance, slots, accessibility guarantees and requirements, anti-patterns, tokens. Both are importable: `ionbase-ui/meta/index` and `ionbase-ui/meta/.json`. Do NOT load `ionbase-ui/meta` (`components.json`) — it is all 35 contracts in one file, for tooling that wants a single fetch, and it will bury the component you need. ## Components `Accordion`, `AccordionItem`, `AgentActivity`, `AgentActivityStep`, `AgentStop`, `AILabel`, `Alert`, `ApprovalGate`, `AppSwitcher`, `Avatar`, `AvatarGradient`, `AvatarGroup`, `Badge`, `Banner`, `Breadcrumb`, `BreadcrumbItem`, `Button`, `ButtonGroup`, `Calendar`, `Card`, `ChartLegend`, `ChartTooltip`, `ChatMessage`, `Checkbox`, `CheckboxGroup`, `Citation`, `CitationList`, `CitationListItem`, `Coachmark`, `CodeSnippet`, `ColorPicker`, `Combobox`, `CommandPalette`, `ConfidenceIndicator`, `ContextMenu`, `CopyButton`, `DatePicker`, `DateRangePicker`, `DateTimePicker`, `DescriptionList`, `DescriptionListItem`, `Divider`, `Drawer`, `DualListbox`, `EmptyState`, `Fieldset`, `FileUpload`, `FullCard`, `Grid`, `Header`, `I18nProvider`, `Icon`, `InlineEdit`, `InlineLoading`, `Input`, `Kbd`, `Link`, `List`, `Logo`, `LogoMark`, `Menu`, `MenuItem`, `MenuSection`, `MenuTrigger`, `Modal`, `MultiSelect`, `NavItem`, `NotificationsPanel`, `NumberInput`, `PageHeader`, `Pagination`, `PasswordInput`, `PhoneInput`, `Popover`, `ProgressBar`, `ProgressRing`, `PromptInput`, `Radio`, `RadioGroup`, `ScrollProgress`, `SearchField`, `SegmentedControl`, `SegmentedControlItem`, `Select`, `SelectableTile`, `SettingRow`, `Sidebar`, `SidebarItem`, `SidebarSection`, `SidePanel`, `SidePanelLayout`, `Skeleton`, `SkipLink`, `Slider`, `Spinner`, `SplitButton`, `SplitPane`, `Stack`, `StatGroup`, `StatTile`, `StatusIndicator`, `Stepper`, `StepperStep`, `StreamingText`, `TabItem`, `Table`, `TableBatchBar`, `TableBody`, `TableCell`, `TableColumnsMenu`, `TableHead`, `TableRow`, `Tabs`, `Tag`, `TagGroup`, `Textarea`, `ThemeZone`, `TimeField`, `Timeline`, `TimelineItem`, `Toast`, `ToastProvider`, `Toggle`, `Toggletip`, `Toolbar`, `ToolCall`, `Tooltip`, `Tour`, `TreeGrid`, `TreeView`, `TruncatedText` ## Patterns Compositions of the components above, in `dist/meta/patterns/`. Read `dist/meta/patterns/index.json`, then one recipe. They are the only place the empty, loading and error states are specified — no component owns those, which is why they are the part that gets left out. `AgentRun`, `AssistantAnswer`, `DataTable`, `DestructiveConfirm`, `FilteredDataTable`, `Form`, `FullPageError`, `HumanApproval`, `ListDetail`, `PageShell`, `SettingsPanel`, `Wizard` `DataTable`, `FilteredDataTable`, `ListDetail` also have a worked example: one complete screen in TSX, type-checked against these types, in `dist/meta/patterns/examples/` and in the recipe as `example.source`. Copy one and change the record, not the structure. ## Drawing a chart? Draw it with visx — IonBase does not draw charts and does not depend on visx — and style it with these, so it themes and passes contrast: - ``, `` — axes and gridlines take the tokens instead of the `#222` visx writes. - `className={chartSeriesClass(n)}` on a series group, with `ion-chart__line`, `__area`, `__bar` or `__point` on its marks; `ion-chart__reference` for a target line; `ion-chart__heat--0…5` for a heatmap cell. - `ChartTooltip` inside ``, and `ChartLegend` for more than one series. Read their contracts. - Always a text summary and the values in a table: the tooltip is pointer-only. - `--chart-1` … `--chart-8` — categorical series, in order. Each clears 3:1 against `--surface-default`, `--surface-page` and `--surface-raised` in Light and Dark. Set them as CSS `fill` / `stroke`, not SVG attributes, which do not reliably resolve `var()`. - `--chart-sequential-1` … `--chart-sequential-5` — one hue, low to high, for magnitude (a heatmap). Use `--surface-sunken` for zero. Do not fake a ramp with opacity: it reads differently on every ground. - **Bin a wide range into the five steps; do not ask for more.** Like GitHub's contribution graph (four steps and empty): zero is its own level, and the non-zero values split into five equal groups by rank, each cut the top of its group — rank, so one outlier does not flatten the rest. Past five to seven steps of one hue, readers cannot tell neighbours apart. - **Continuous scale?** Blend neighbouring steps in CSS, which still themes: `color-mix(in oklab, var(--chart-sequential-2) 60%, var(--chart-sequential-3))`. A JS colour scale cannot read `var()`. Pair it with a labelled axis or tooltip. ## Driving an agent run? Do not hand-build the state behind AgentActivity, ApprovalGate, StreamingText and AgentStop. `useAgentRun()` takes the events a run reports — `step-started`, `approval-requested`, `output`, `run-stopped` and the rest — and returns `log`, `stopProps`, `outputProps` and `approvalProps` to spread. It applies the AgentRun and HumanApproval patterns: one active step, a stop keeps what was done, an unanswered approval is never a yes. `replay(recording)` plays a stored run; `agentRunFrom(events)` rebuilds a finished one. The full event list is in `dist/meta/patterns/AgentRun.json` under `drivenBy`. ## Shipping in another language? Every string a component shows or announces can be replaced — by a prop (`closeLabel`) or a key in its `labels`. `dist/meta/strings.json` (`ionbase-ui/meta/strings.json`) lists every one: the English default and what to pass. Wrap the app in `I18nProvider` with the locale: react-aria's own strings (calendar, number field, tag remove) are already translated and follow it, and so do the numbers and units the components format. ## Coming from a Figma design? `dist/figma-map.json` maps every Figma component and node id in the IonBase library to the React component and the real props — what Code Connect does, without needing an Organization plan. Look up the node id or the component name rather than guessing from a screenshot. ## Rules that ship with this package - `ionbase-ui/eslint-plugin` — five rules driven from the contracts: deprecated props, missing accessible names, raw style values, measured contrast failures, competing primary actions. - `ionbase-ui/stylelint-config` — bans raw colour, spacing and duration values in favour of tokens. Turn both on. They encode the same judgement as the contracts, enforced. ## Hosted https://raza-ahmed.github.io/ionbase-design-system/llms.txt — the same index with per-component markdown pages.