@persona/design-system 0.1.8 → 0.2.0

package/skills/ui-authoring/COMPONENTS.md

@@ -0,0 +1,331 @@
+# Component Patterns & Props Reference
+
+## Form Configuration
+
+```tsx
+import ConfigFormGroup from '@persona/design-system/components/ConfigFormGroup';
+import { TextField, TextAreaField } from '@persona/design-system/components/FormField';
+
+const [config, setConfig] = useState({ name: '', description: '', prompt: '' });
+
+<ConfigFormGroup>
+  <TextField
+    label="Name"
+    value={config.name}
+    onChange={(e) => setConfig({ ...config, name: e.target.value })}
+    configField={true}       // helperText becomes a tooltip
+    helperText="Unique identifier"
+    errorText={errors.name}
+    rightActions={<Button size="sm" variant="basic">Generate</Button>}
+  />
+  <TextAreaField
+    label="Prompt"
+    value={config.prompt}
+    onChange={(e) => setConfig({ ...config, prompt: e.target.value })}
+    configField={true}
+    warningText={warnings.prompt}
+  />
+</ConfigFormGroup>
+```
+
+- `configField={true}` → helper text becomes a tooltip instead of inline text
+- `ConfigFormGroup` provides consistent 20px spacing between fields
+- Use controlled inputs; clear `errorText` on change via `updateField` in form state hook
+
+## Form State Hook
+
+```tsx
+const useFormState = (initialConfig) => {
+  const [config, setConfig] = useState(initialConfig);
+  const [errors, setErrors] = useState({});
+
+  const updateField = useCallback((field, value) => {
+    setConfig(prev => ({ ...prev, [field]: value }));
+    setErrors(prev => { const next = { ...prev }; delete next[field]; return next; });
+  }, []);
+
+  const validate = useCallback(() => {
+    const newErrors = {};
+    if (!config.name) newErrors.name = 'Required';
+    setErrors(newErrors);
+    return Object.keys(newErrors).length === 0;
+  }, [config]);
+
+  return { config, errors, updateField, validate };
+};
+```
+
+## Dynamic List (ListBox)
+
+```tsx
+import { ListBox } from '@persona/design-system/components/ListBox';
+
+<ListBox
+  items={items}
+  selectedKeys={selectedKeys}
+  onSelectionChange={setSelectedKeys}
+  onAdd={() => setItems([...items, { id: uuid(), name: 'New' }])}
+  onDelete={(keys) => setItems(items.filter(i => !keys.has(i.id)))}
+  selectionMode="multiple"
+  emptyText="No items"
+>
+  {items.map(item => (
+    <ListBox.Item key={item.id}>{item.name}</ListBox.Item>
+  ))}
+</ListBox>
+```
+
+Drag-drop reordering: add `reorderConfig={{ onReorder: (items) => void, dragIcon: ReactNode }}`.
+
+## Editable Table (TableBox)
+
+Use `TableBox` for **small, form-adjacent tables** — config editors, field mappings, inline-editable row lists. Use `DataTable` for **data views** with pagination, sorting, and server-side data.
+
+```tsx
+import TableBox from '@persona/design-system/components/TableBox';
+
+const columns = [
+  { key: 'name', title: 'Name' },
+  { key: 'type', title: 'Type' },
+];
+
+<TableBox columns={columns} aria-label='File list' selectionMode='none'>
+  {items.map((item) => (
+    <TableBox.Row key={item.id} id={item.id} onDelete={() => removeItem(item.id)}>
+      <TableBox.Cell>{item.name}</TableBox.Cell>
+      <TableBox.Cell>{item.type}</TableBox.Cell>
+    </TableBox.Row>
+  ))}
+</TableBox>
+```
+
+- `aria-label` is **required**
+- Rows are composed via `TableBox.Row` + `TableBox.Cell` children (not an `items` prop)
+- Row actions: pass `actions={[{ label, onClick }]}` or `onDelete` on `TableBox.Row`
+- Drag-drop reordering: `reorderConfig={{ items, itemKeyPath: 'id', onReorder }}`
+- Empty state: `emptyText`; pass `onCreateNewRow` to make the message a clickable "add row" button
+- `onCreateNewRow` also fires after Enter on the **last cell of the last row** (single-line text inline edit only)
+
+### Inline editing
+
+Declare `inlineEditConfig` on column definitions; pass `columnKey`, `itemId`, and `value` on each cell:
+
+```tsx
+const columns = [
+  {
+    key: 'name',
+    title: 'Name',
+    inlineEditConfig: { type: 'text', onChange: (id, value) => updateField(id, 'name', value) },
+  },
+  {
+    key: 'role',
+    title: 'Role',
+    inlineEditConfig: {
+      type: 'combobox',
+      options: roleOptions,
+      onChange: (id, value) => updateField(id, 'role', value),
+    },
+  },
+];
+
+<TableBox columns={columns} aria-label='Editable users'>
+  {users.map((user) => (
+    <TableBox.Row key={user.id} id={user.id}>
+      <TableBox.Cell columnKey='name' itemId={user.id} value={user.name} errorText={errors[user.id]?.name}>
+        {user.name}
+      </TableBox.Cell>
+      <TableBox.Cell columnKey='role' itemId={user.id} value={user.role}>
+        {roleLabel(user.role)}
+      </TableBox.Cell>
+    </TableBox.Row>
+  ))}
+</TableBox>
+```
+
+- Inline editing forces fixed-width layout (no horizontal scroll) automatically
+- Cell/row validation: pass `errorText` on `TableBox.Cell` or `TableBox.Row`
+- For adding rows from a form field, prefer `TableBoxField` (below) over bare `onCreateNewRow`
+
+### Form field wrapper (TableBoxField)
+
+Use inside `ConfigFormGroup` when the table needs a label, add/delete toolbar, and row creation:
+
+```tsx
+import { TableBoxField } from '@persona/design-system/components/FormField';
+
+<TableBoxField
+  label='Case actions'
+  labelProps={{ size: 'md' }}   // defaults to 'sm'; match sibling ControlPanel labels
+  columns={columns}
+  createNewRow={() => addRow()}
+  onDelete={(selectedKey) => removeRow(selectedKey)}
+  selectionMode='single'
+>
+  {rows.map((row) => (
+    <TableBoxField.Row key={row.id} id={row.id}>
+      <TableBoxField.Cell columnKey='key' itemId={row.id} value={row.key}>
+        {row.key}
+      </TableBoxField.Cell>
+    </TableBoxField.Row>
+  ))}
+</TableBoxField>
+```
+
+`TableBoxField.Row` and `TableBoxField.Cell` are aliases for `TableBox.Row` / `TableBox.Cell`.
+
+## Collapsible Sections (Card)
+
+```tsx
+import { Card } from '@persona/design-system/components/CardV2';
+
+<Card>
+  <Card.Section header="Basic Settings" collapsible={true} defaultCollapsed={false}>
+    {/* Content */}
+  </Card.Section>
+  <Card.Section header="Advanced" collapsible={true}>
+    {/* Content */}
+  </Card.Section>
+</Card>
+```
+
+## Modal
+
+```tsx
+import { Modal } from '@persona/design-system/components/Modal';
+
+<Modal
+  isOpen={isOpen}
+  onClose={() => setIsOpen(false)}
+  title="Add Tools"
+  footer={
+    <>
+      <Button variant="basic" onClick={() => setIsOpen(false)}>Cancel</Button>
+      <Button variant="primary" onClick={handleSave}>Save</Button>
+    </>
+  }
+>
+  {/* Content */}
+</Modal>
+```
+
+## Testing
+
+```tsx
+import { render as dsRender, screen } from '@persona/design-system/utils/testing';
+import userEvent from '@testing-library/user-event';
+import { waitFor } from '@testing-library/react';
+
+it('handles input', async () => {
+  dsRender(<MyComponent />);
+  await userEvent.type(screen.getByLabelText('Name'), 'Test');
+  expect(screen.getByLabelText('Name')).toHaveValue('Test');
+});
+
+it('shows validation errors', async () => {
+  dsRender(<MyComponent />);
+  await userEvent.click(screen.getByRole('button', { name: /save/i }));
+  await waitFor(() => expect(screen.getByText('Required')).toBeInTheDocument());
+});
+```
+
+- Use `dsRender` (wraps with ThemeProvider)
+- Prefer `userEvent.type()` over `fireEvent.change()`
+- Use `waitFor()` for async state updates
+- Prefer `getByRole`, `getByLabelText`, `getByText` over `getByTestId`
+
+## Props Reference
+
+### TextField / TextAreaField
+- `label` — field label
+- `value` / `onChange` — controlled input
+- `helperText` — help text (tooltip if `configField={true}`)
+- `errorText` — error message (red)
+- `warningText` — warning message (yellow)
+- `configField` — boolean, renders helper as tooltip
+- `rightActions` — ReactNode for buttons/icons next to label
+- `disabled` — boolean
+
+### ListBox
+- `items` — array of items
+- `selectedKeys` / `onSelectionChange` — controlled selection (`Set<string>`)
+- `selectionMode` — `"single"` | `"multiple"` | `"none"`
+- `onAdd` — add button callback
+- `onDelete` — delete callback (receives `Set<string>` of keys)
+- `reorderConfig` — `{ onReorder: (items) => void, dragIcon: ReactNode }`
+- `emptyText` — shown when no items
+
+### TableBox
+- `columns` — `{ key, title, inlineEditConfig? }[]` (required)
+- `aria-label` — accessible table name (required)
+- `emptyText` — shown when no rows
+- `selectionMode` — `"single"` | `"none"` (default `"none"`)
+- `selectedKey` / `onSelectionChange` / `defaultSelectedKey` — row selection
+- `onCreateNewRow` — makes empty state clickable; fires after Enter on last cell of last row (single-line text)
+- `newRowId` — auto-opens inline edit on the first column of the new row
+- `disabled` — view-only; blocks edits, delete, and reorder
+- `reorderConfig` — `{ items, itemKeyPath, onReorder }` for drag-drop row reorder
+- `disableHorizontalScroll` — fixed-width/truncating layout (auto when any column has `inlineEditConfig`)
+- `hideHeader` — hide column headers (e.g. single-column tables under a `FormField` label)
+
+#### TableBox.Row
+- `id` — row identifier (required)
+- `actions` — `[{ label, onClick }]` dropdown menu items
+- `onDelete` — renders row delete button
+- `errorText` — row-wide validation error (shown in first cell)
+- `dropdownFormFields` / `dropdownContent` / `dropdownHeadingText` / `dropdownFooter` — expandable row popover (requires `selectionMode='single'`; opens when row is selected)
+
+#### TableBox.Cell
+- `columnKey` / `itemId` / `value` — required for inline editing
+- `errorText` — cell validation error
+- `inlineEditConfigOverride` — per-cell override of column `inlineEditConfig`
+
+#### TableBoxField (extends TableBox + FormField)
+- `label`, `helperText`, `errorText`, `warningText`, `configField` — standard form field props
+- `createNewRow` — returns new row id; wires add button and empty state
+- `onAdd` — alternative add handler (when not using `createNewRow`)
+- `onDelete` — deletes the currently selected row
+- `actions` — toolbar dropdown actions (receives `selectedKey`)
+- `addDropdownConfig` — `{ options, onSelection }` for add-menu instead of direct add
+
+### Card / Card.Section
+- `collapsible` — boolean
+- `defaultCollapsed` — boolean
+- `header` — section header text
+- `loading` — boolean
+- `empty` — boolean
+
+### Stack / HStack
+- `spacing` — spacing value (default: `Spacing[2]`)
+- `align` — `"start"` | `"center"` | `"end"` | `"stretch"`
+- `justify` — `"start"` | `"center"` | `"end"` | `"space-between"`
+- `wrap` — boolean
+- `fullWidth` — boolean
+
+### Modal
+- `isOpen` / `onClose` — controlled open state
+- `title` — modal title
+- `footer` — footer content (ReactNode)
+
+### Sticker
+- `variant` — `"blue"` | `"teal"` | `"green"` | `"yellow"` | `"orange"` | `"red"` | `"purple"` | `"darkGrey"` | `"white"` | `"success"` | `"danger"` | `"caution"` | `"basic"` | `"grey"`
+- `icon` — optional icon component (use 12px icons)
+- `onDismiss` — dismiss button callback
+- `required` — boolean, shows asterisk
+
+## Key File Paths
+
+- `@persona/design-system/components/ConfigFormGroup/ConfigFormGroup.tsx`
+- `@persona/design-system/components/FormField/FormField.tsx`
+- `@persona/design-system/components/Input/Input.tsx`
+- `@persona/design-system/components/TextArea/TextArea.tsx`
+- `@persona/design-system/components/ListBox/ListBox.tsx`
+- `@persona/design-system/components/TableBox/TableBox.tsx`
+- `@persona/design-system/components/FormField/TableBoxField.tsx`
+- `@persona/design-system/components/CardV2/Card.tsx`
+- `@persona/design-system/components/Stack/Stack.tsx`
+- `@persona/design-system/components/Text/` (Heading, Paragraph, Label)
+- `@persona/design-system/components/Sticker/Sticker.tsx`
+- `@persona/design-system/components/Modal/Modal.tsx`
+- `@persona/design-system/components/Popover/Popover.tsx`
+- `@persona/design-system/utils/testing.tsx`
+- `@persona/design-system/components/DataTable/`

package/skills/ui-authoring/EXAMPLES.md

@@ -0,0 +1,370 @@
+# PDS UI Examples
+
+Common patterns for building UI with the Persona design system.
+
+## Table of Contents
+
+- [Buttons](#buttons)
+- [Forms](#forms)
+- [Modals](#modals)
+- [Data Tables](#data-tables)
+- [Status Indicators](#status-indicators)
+- [Layout](#layout)
+- [Navigation — Tabs](#navigation--tabs)
+- [Text Components](#text-components)
+- [Feedback Components](#feedback-components)
+- [Empty States](#empty-states)
+
+## Buttons
+
+```tsx
+import Button from '@persona/design-system/components/Button';
+import { PlusIcon, ArrowRightIcon } from '@persona/icons';
+
+// Variants
+<Button variant="primary" size="md">Save Changes</Button>
+<Button variant="basic" size="md">Cancel</Button>
+<Button variant="danger" size="md">Delete Account</Button>
+<Button variant="outline" size="md">Learn More</Button>
+<Button variant="text" size="md">Skip</Button>
+
+// States
+<Button variant="primary" disabled>Submit</Button>
+<Button variant="primary" isPending>Saving...</Button>
+
+// With icons
+<Button variant="primary" prefixIcon={<PlusIcon />}>Add Item</Button>
+<Button variant="basic" suffixIcon={<ArrowRightIcon />}>Next</Button>
+
+// Icon-only (must include aria-label)
+<Button variant="basic" width="icon" aria-label="Add"><PlusIcon /></Button>
+
+// Widths
+<Button variant="primary" width="full">Full Width</Button>
+<Button variant="primary" width="auto">Auto Width</Button>
+```
+
+## Forms
+
+**Always use `ConfigFormGroup` + `TextField`/`TextAreaField` — never hand-roll `styled.input` or `styled.label`.**
+
+### Basic form
+
+```tsx
+import ConfigFormGroup from '@persona/design-system/components/ConfigFormGroup';
+import { TextField, TextAreaField } from '@persona/design-system/components/FormField';
+import { Select } from '@persona/design-system/components/Select';
+import { TextUnderlineTooltip } from '@persona/design-system/components/Tooltip';
+import { Label } from '@persona/design-system/components/Text';
+import Stack from '@persona/design-system/components/Stack';
+import { Spacing } from '@persona/design-tokens';
+
+<ConfigFormGroup>
+  {/* Field with tooltip: use TextUnderlineTooltip, never an info icon */}
+  <TextUnderlineTooltip tooltip="Must be unique." side="right">
+    <TextField
+      label="Name"
+      value={config.name}
+      onChange={(e) => setConfig({ ...config, name: e.target.value })}
+      configField={true}
+      errorText={errors.name}
+    />
+  </TextUnderlineTooltip>
+
+  <TextAreaField
+    label="Description"
+    value={config.description}
+    onChange={(e) => setConfig({ ...config, description: e.target.value })}
+    configField={true}
+    helperText="Short summary shown in listings."
+  />
+
+  {/* Dropdown */}
+  <Stack spacing={Spacing[2]}>
+    <Label size="sm" color="secondary">Enforcement</Label>
+    <Select
+      value={config.enforcement}
+      onChange={(val) => setConfig({ ...config, enforcement: val })}
+      options={[
+        { label: 'Strict', value: 'strict' },
+        { label: 'Lenient', value: 'lenient' },
+        { label: 'Disabled', value: 'disabled' },
+      ]}
+    />
+  </Stack>
+</ConfigFormGroup>
+```
+
+### Form state hook
+
+```tsx
+const useFormState = (initialConfig) => {
+  const [config, setConfig] = useState(initialConfig);
+  const [errors, setErrors] = useState({});
+
+  const updateField = useCallback((field, value) => {
+    setConfig(prev => ({ ...prev, [field]: value }));
+    setErrors(prev => { const next = { ...prev }; delete next[field]; return next; });
+  }, []);
+
+  const validate = useCallback(() => {
+    const newErrors = {};
+    if (!config.name) newErrors.name = 'Required';
+    setErrors(newErrors);
+    return Object.keys(newErrors).length === 0;
+  }, [config]);
+
+  return { config, errors, updateField, validate };
+};
+```
+
+### Form with footer buttons
+
+```tsx
+import Stack from '@persona/design-system/components/Stack';
+import { HStack } from '@persona/design-system/components/Stack';
+
+<Stack spacing={Spacing[5]}>
+  <ConfigFormGroup>
+    <TextField label="Name" value={config.name} onChange={...} />
+    <TextAreaField label="Description" value={config.description} onChange={...} />
+  </ConfigFormGroup>
+  <HStack spacing={Spacing[3]} justify="flex-end">
+    <Button variant="basic" onClick={onCancel}>Cancel</Button>
+    <Button variant="primary" onClick={handleSave} isPending={isSaving}>Save</Button>
+  </HStack>
+</Stack>
+```
+
+## Modals
+
+**Always use the `Modal` component — never hand-roll `ModalOverlay`/`ModalContainer` styled divs.**
+
+```tsx
+import { Modal } from '@persona/design-system/components/Modal';
+
+const [isOpen, setIsOpen] = useState(false);
+
+<Modal
+  isOpen={isOpen}
+  onClose={() => setIsOpen(false)}
+  title="Confirm Delete"
+  footer={
+    <>
+      <Button variant="basic" onClick={() => setIsOpen(false)}>Cancel</Button>
+      <Button variant="danger" onClick={handleDelete} isPending={isDeleting}>Delete</Button>
+    </>
+  }
+>
+  <Paragraph>Are you sure you want to delete this rule? This action cannot be undone.</Paragraph>
+</Modal>
+```
+
+## Data Tables
+
+Use **`DataTable`** for data views (pagination, sorting, server-side data). For small, form-adjacent editable tables, use **`TableBox`** — see [COMPONENTS.md — Editable Table (TableBox)](COMPONENTS.md#editable-table-tablebox). Never hand-roll `<table>`.
+
+```tsx
+import DataTable from '@persona/design-system/components/DataTable';
+
+const columns = [
+  'name',
+  {
+    accessor: 'enforcement',
+    header: 'Enforcement',
+    format: {
+      type: 'sticker',
+      config: { colors: { strict: 'danger', lenient: 'caution', disabled: 'basic' } },
+    },
+  },
+  { accessor: 'lastModified', header: 'Last Modified', format: { type: 'datetime' } },
+];
+
+<DataTable
+  columns={columns}
+  data={rules}
+  rowActions={[
+    { label: 'Edit', onClick: (rowId) => handleEdit(rowId) },
+    { label: 'Delete', onClick: (rowId) => setDeleteTarget(rowId) },
+  ]}
+  pagination={{ clientPagination: true, pageSize: 10, pageSizeOptions: [10, 25, 50] }}
+/>
+```
+
+## Status Indicators
+
+### Sticker (Status Labels)
+
+```tsx
+import Sticker from '@persona/design-system/components/Sticker';
+import { CheckCircleIcon } from '@persona/icons/12px'; // 12px for sticker icons
+
+// Semantic variants — match business status to variant:
+// approved/active/verified  → success
+// declined/failed/error     → danger
+// pending/in-review/flagged → caution
+// inactive/archived         → basic
+<Sticker variant="success">Approved</Sticker>
+<Sticker variant="danger">Failed</Sticker>
+<Sticker variant="caution">Pending</Sticker>
+<Sticker variant="basic">Inactive</Sticker>
+
+// Color variants for categorization
+<Sticker variant="purple">New</Sticker>
+<Sticker variant="blue">In Progress</Sticker>
+
+// With icon (use 12px icons)
+<Sticker variant="success" icon={<CheckCircleIcon />}>Verified</Sticker>
+
+// Dismissible
+<Sticker variant="purple" onDismiss={() => handleRemove()}>Removable Tag</Sticker>
+```
+
+### Banner (Alert / Notification)
+
+```tsx
+import Banner from '@persona/design-system/components/Banner';
+import { CircleInfoIcon, CheckCircleIcon, AlertTriangleIcon, XCircleIcon } from '@persona/icons';
+
+<Banner variant="informational"><CircleInfoIcon />This is an informational message.</Banner>
+<Banner variant="success"><CheckCircleIcon />Changes saved successfully!</Banner>
+<Banner variant="warning"><AlertTriangleIcon />Please review before submitting.</Banner>
+<Banner variant="alert"><XCircleIcon />There was an error processing your request.</Banner>
+
+// With dismiss
+<Banner variant="informational" onClose={() => setShowBanner(false)}>
+  <CircleInfoIcon />You can dismiss this message.
+</Banner>
+```
+
+## Layout
+
+### Stack / HStack
+
+```tsx
+import Stack from '@persona/design-system/components/Stack';
+import { HStack } from '@persona/design-system/components/Stack';
+
+// Vertical layout
+<Stack spacing={Spacing[4]}>
+  <Heading size="sm">Section Title</Heading>
+  <Paragraph>Content...</Paragraph>
+</Stack>
+
+// Horizontal layout
+<HStack spacing={Spacing[3]} justify="flex-end">
+  <Button variant="basic">Cancel</Button>
+  <Button variant="primary">Save</Button>
+</HStack>
+
+// Space between header + action
+<HStack spacing={Spacing[4]} justify="space-between" align="center">
+  <Heading size="sm">Policy Rules</Heading>
+  <Button variant="primary" size="sm" prefixIcon={<PlusIcon />}>Add Rule</Button>
+</HStack>
+
+// Wrapping tags/stickers
+<HStack spacing={Spacing[2]} wrap>
+  <Sticker variant="purple">Tag 1</Sticker>
+  <Sticker variant="blue">Tag 2</Sticker>
+</HStack>
+```
+
+### Card with collapsible sections
+
+```tsx
+import { Card } from '@persona/design-system/components/CardV2';
+
+<Card>
+  <Card.Section header="Basic Settings" collapsible={true} defaultCollapsed={false}>
+    <ConfigFormGroup>
+      <TextField label="Name" value={...} onChange={...} />
+    </ConfigFormGroup>
+  </Card.Section>
+  <Card.Section header="Advanced" collapsible={true}>
+    {/* Advanced fields */}
+  </Card.Section>
+</Card>
+```
+
+## Navigation — Tabs
+
+```tsx
+import TabBar, { Tab } from '@persona/design-system/components/TabBar';
+import Badge from '@persona/design-system/components/Badge';
+import { useState } from 'react';
+
+const [selectedTab, setSelectedTab] = useState(0);
+
+<TabBar aria-label="Policy tabs" title="Policy Configuration">
+  <Tab selected={selectedTab === 0} onClick={() => setSelectedTab(0)}>Overview</Tab>
+  <Tab selected={selectedTab === 1} onClick={() => setSelectedTab(1)} badge={<Badge variant="active">5</Badge>}>
+    Pending
+  </Tab>
+  <Tab selected={selectedTab === 2} onClick={() => setSelectedTab(2)} badge={<Badge variant="alert">2</Badge>}>
+    Alerts
+  </Tab>
+</TabBar>
+```
+
+## Text Components
+
+```tsx
+import { Heading, Paragraph, Label } from '@persona/design-system/components/Text';
+
+// Headings
+<Heading size="lg" color="primary">Page Title</Heading>
+<Heading size="md" color="primary">Section Title</Heading>
+<Heading size="sm" color="primary">Subsection</Heading>
+
+// Body text — defaults to color="secondary" (grey); use color="primary" for black
+<Paragraph size="md" color="primary">Black body text</Paragraph>
+<Paragraph size="md">Secondary (grey) body text</Paragraph>
+<Paragraph size="sm" color="tertiary">Helper / caption text</Paragraph>
+
+// Form labels
+<Label size="sm" color="secondary">Field Name</Label>
+```
+
+## Feedback Components
+
+### Spinner
+
+```tsx
+import Spinner from '@persona/design-system/components/Spinner';
+
+// Centered loading state
+<Stack align="center" spacing={Spacing[3]}>
+  <Spinner size="md" srText="Loading policies..." />
+</Stack>
+
+// Inline in button (use isPending prop on Button instead when possible)
+<Button variant="primary" isPending>Saving...</Button>
+```
+
+### Tooltip (standalone, no label)
+
+```tsx
+import Tooltip from '@persona/design-system/components/Tooltip';
+import { HelpCircleIcon } from '@persona/icons';
+
+// Standalone icon trigger (only when there's no adjacent label)
+<Tooltip iconTrigger={<HelpCircleIcon />} side="right">
+  Additional help text appears here.
+</Tooltip>
+```
+
+## Empty States
+
+For tables/lists when there is no data to show:
+
+```tsx
+// Inside a Card section or table container
+<Stack align="center" spacing={Spacing[3]} style={{ padding: Spacing[6] }}>
+  <Paragraph color="secondary">No policy rules yet.</Paragraph>
+  <Button variant="primary" size="sm" prefixIcon={<PlusIcon />}>Add Rule</Button>
+</Stack>
+```
+
+For `ListBox`, pass `emptyText="No items"` prop directly.
+For `Card.Section`, pass `empty={true}` to show the built-in empty state.