@databricks/design-system 2.0.5 → 2.0.7

package/AGENTS.md

@@ -1,16 +1,39 @@
 # Using Du Bois (`@databricks/design-system`)
 
-Du Bois is Databricks' React component library. This file is guidance for coding agents
-building UI with it. Everything it describes is available from the published package; all
-components are named exports from `@databricks/design-system`.
+Du Bois is Databricks' React component library. This file is guidance for coding agents building UI
+with it. Everything it describes is available from the published package; all components are named
+exports from `@databricks/design-system`.
 
 ## If you remember only four things
 
 1. **Use an existing component** — don't hand-build a widget the library already has.
-2. **Prefer the composite** — `InfoTooltip`, `DangerModal`, `DropdownMenu`, not primitives glued together.
+2. **Prefer the composite** — `InfoTooltip`, `DangerModal`, `DropdownMenu`, not primitives glued
+   together.
 3. **Always pass `componentId`** — stable, dotted, no PII.
 4. **Never hardcode colors or spacing** — read `theme.*` tokens.
 
+## Step-by-step workflows
+
+This package ships task-oriented workflows under
+`node_modules/@databricks/design-system/design-guidance/`. Point your coding agent at the relevant
+file when you want a repeatable procedure rather than the quick reference below. Start from
+`design-guidance/docs/README.md`, then open the workflow for your task:
+
+| Task                         | Workflow                          |
+|------------------------------|-----------------------------------|
+| Select a component           | `skills/dbui-pick-component.md`   |
+| Select an icon               | `skills/dbui-pick-icon.md`        |
+| Implement a screen           | `skills/dbui-build-screen.md`     |
+| Check an implementation      | `skills/dbui-validate.md`         |
+| Review a design (all checks) | `skills/dbui-review.md`           |
+| Review copy / voice          | `skills/dbui-check-voice.md`      |
+| Review UX behavior           | `skills/dbui-check-guidelines.md` |
+| Review design intent         | `skills/dbui-check-principles.md` |
+| Review platform fit          | `skills/dbui-check-ecosystem.md`  |
+
+Reference docs sit alongside them: `docs/tokens.md` (finding theme tokens as a consumer),
+`docs/voice.md` (product copy), and `docs/review-contract.md`.
+
 ## Setup
 
 Install the package and its peer dependencies:
@@ -19,8 +42,8 @@ Install the package and its peer dependencies:
 npm install @databricks/design-system @emotion/react react react-dom moment
 ```
 
-`moment` is required by the date components. `@jest/globals` is an additional peer dependency
-if you use the `test-utils` entry point.
+`moment` is required by the date components. `@jest/globals` is an additional peer dependency if you
+use the `test-utils` entry point.
 
 Import the stylesheet once at your app's entry point, wrap the tree in
 `DesignSystemProvider`, and render `ApplyGlobalStyles` inside it:
@@ -29,27 +52,55 @@ Import the stylesheet once at your app's entry point, wrap the tree in
 import '@databricks/design-system/index.css';
 import '@databricks/design-system/fonts/dm-sans.css';
 
-import { ApplyGlobalStyles, DesignSystemProvider } from '@databricks/design-system';
+import {ApplyGlobalStyles, DesignSystemProvider} from '@databricks/design-system';
 
 export const App = () => (
-  <DesignSystemProvider>
-    <ApplyGlobalStyles />
-    <YourApp />
-  </DesignSystemProvider>
+    <DesignSystemProvider>
+      <ApplyGlobalStyles/>
+      <YourApp/>
+    </DesignSystemProvider>
 );
 ```
 
-Without `DesignSystemProvider` the theme context is missing and `useDesignSystemTheme()`
-throws. For dark mode, also import `@databricks/design-system/index-dark.css` and pass
-`isDarkMode` to the provider.
+Without `DesignSystemProvider` the theme context is missing and `useDesignSystemTheme()` throws.
+
+`ApplyGlobalStyles` sets the body background and text color but **not** `font-family` (`Typography`
+sets only color and size), so text falls back to the browser serif until you point `body` at the
+`--db-font-family` token `index.css` defines (DM Sans; correct in both themes):
+
+```css
+body {
+  font-family: var(--db-font-family);
+}
+```
+
+For dark mode, also import `@databricks/design-system/index-dark.css` and set `isDarkMode` on a
+`DesignSystemThemeProvider` wrapping `DesignSystemProvider` — the provider has no `isDarkMode` prop
+of its own (it reads theme context), so setting it there is a type error that stays light:
+
+```tsx
+import {
+  ApplyGlobalStyles,
+  DesignSystemProvider,
+  DesignSystemThemeProvider
+} from '@databricks/design-system';
+
+export const App = () => (
+    <DesignSystemThemeProvider isDarkMode>
+      <DesignSystemProvider>
+        <ApplyGlobalStyles/>
+        <YourApp/>
+      </DesignSystemProvider>
+    </DesignSystemThemeProvider>
+);
+```
 
 Styling uses the Emotion `css` prop, so configure Emotion's JSX runtime — set
 `jsxImportSource: '@emotion/react'` in your TypeScript or Babel config, or add
 `/** @jsxImportSource @emotion/react */` per file.
 
 The CSS entry points have no type declarations, so TypeScript rejects those side-effect imports
-unless your project declares them. Add this once rather than suppressing the error at each
-import:
+unless your project declares them. Add this once rather than suppressing the error at each import:
 
 ```ts
 // css.d.ts
@@ -61,19 +112,19 @@ declare module '*.css';
 Read every design value off the theme.
 
 ```tsx
-import { useDesignSystemTheme } from '@databricks/design-system';
+import {useDesignSystemTheme} from '@databricks/design-system';
 
 const MyPanel = () => {
-  const { theme } = useDesignSystemTheme();
+  const {theme} = useDesignSystemTheme();
   return (
-    <div
-      css={{
-        padding: theme.spacing.md, // 16 — never write 16
-        color: theme.colors.textPrimary,
-        backgroundColor: theme.colors.backgroundPrimary,
-        borderRadius: theme.borders.borderRadiusSm,
-      }}
-    />
+      <div
+          css={{
+            padding: theme.spacing.md, // 16 — never write 16
+            color: theme.colors.textPrimary,
+            backgroundColor: theme.colors.backgroundPrimary,
+            borderRadius: theme.borders.borderRadiusSm,
+          }}
+      />
   );
 };
 ```
@@ -85,73 +136,93 @@ const MyPanel = () => {
 - **Radius** — `theme.borders.borderRadius*`. **Shadows** — `theme.shadows.{xs,sm,md,lg,xl}`.
 - **Motion** — `theme.animation.transitionDuration` (170ms).
 
-Every semantic token has a correct dark-mode value, so using tokens is what makes dark mode
-work for free.
-
-## Picking a component
-
-| Need | Use |
-| --- | --- |
-| Action / navigation | `Button` (with `type`, `danger`), `Typography.Link` for navigation |
-| Button + menu | `SplitButton` (primary action + menu) or `DropdownMenu` |
-| Text & headings | `Typography.Title` / `.Text` / `.Paragraph` / `.Link` / `.Hint` |
-| Text input | `Input`, `Input.TextArea`, `Input.Password` |
-| Boolean | `Checkbox` (multi-select / terms), `Switch` (instant setting toggle) |
-| One of a small set | `Radio.Group`, or `SimpleSelect` for a dropdown |
-| One of many / searchable | `DialogCombobox` (searchable list), `TypeaheadCombobox` (autocomplete) |
-| Container / summary | `Card` |
-| Sectioned content | `Tabs` |
-| Dialog | `Modal`; `DangerModal` for destructive confirmation |
-| Contextual help | `Tooltip` (wraps any control), `InfoTooltip` (info icon + tooltip) |
-| Menu of actions | `DropdownMenu` |
-| Inline message / callout | `Alert` (field/section); `Banner` for page-level with a CTA |
-| Toast | `SnackBar` + `useSnackBar` |
-| Loading / empty | `Spinner`, `Skeleton` variants, `LoadingState`; `Empty` for no-data |
-| Page layout | `PageWrapper`, `Header`, `Sidebar`, `Grid.Row` / `Grid.Col` |
-| Tabular data | `Table` + `TableRow` / `TableHeader` / `TableCell` |
-| Form | `Form` + `FormUI.*`; `RHFControlledComponents.*` with React Hook Form |
-| Icon | Any `<XxxIcon />` (standalone component) |
-| Spacing between elements | `<Spacer size="…" />`, or `theme.spacing.*` in `css` |
-
-The library has roughly 90 components. For anything not listed, check the bundled type
-declarations (`dist-types/index.d.ts`) before building something custom — the export list is
-the authoritative catalog, and prop types are the authoritative API.
+Every semantic token has a correct dark-mode value, so using tokens is what makes dark mode work for
+free.
+
+## Available components
+
+| Need                                    | Use                                                                         |
+|-----------------------------------------|-----------------------------------------------------------------------------|
+| Action / navigation                     | `Button` (with `type`, `danger`), `Typography.Link` for navigation          |
+| Button + menu                           | `SplitButton` (primary action + menu) or `DropdownMenu`                     |
+| Grouped controls bar                    | `Toolbar` (buttons, toggles, and menus as one bar)                          |
+| Text & headings                         | `Typography.Title` / `.Text` / `.Paragraph` / `.Link` / `.Hint`             |
+| Text input                              | `Input`, `Input.TextArea`, `Input.Password`                                 |
+| Boolean                                 | `Checkbox` (multi-select / terms), `Switch` (instant setting toggle)        |
+| Toggle a view on/off                    | `ToggleButton` (binary filter with an immediately visible result)           |
+| One of a small set                      | `Radio.Group`, or `SimpleSelect` for a dropdown                             |
+| One of a small set (rich cards)         | `RadioTile` (option cards, inside a `Radio.Group`)                          |
+| One of 4+ options                       | `Select` (dropdown built on `DialogCombobox`)                               |
+| One of many / searchable                | `DialogCombobox` (searchable list), `TypeaheadComboboxV2` (autocomplete)    |
+| Selectable option list (building block) | `Listbox` (optionally filterable)                                           |
+| Filter a list / switch related views    | `SegmentedControl` (filter), `PillControl` (related page areas)             |
+| Value from a range                      | `Slider` (single, range, or stepped)                                        |
+| Date / time                             | `DatePicker` (single, range, optional time)                                 |
+| Container / summary                     | `Card`                                                                      |
+| Asset preview + actions                 | `PreviewCard` (image plus related actions)                                  |
+| User or entity avatar                   | `Avatar`                                                                    |
+| Label / category / status chip          | `Tag` (colored, optionally closable)                                        |
+| Compute resource status                 | `ResourceStatusIndicator`                                                   |
+| Progress of a task                      | `Progress` (determinate bar)                                                |
+| Multi-step task / wizard                | `Stepper`                                                                   |
+| Sectioned content                       | `Tabs`                                                                      |
+| Dialog                                  | `Modal`; `DangerModal` for destructive confirmation                         |
+| Contextual help                         | `Tooltip` (wraps any control), `InfoTooltip` (info icon + tooltip)          |
+| Menu of actions                         | `DropdownMenu`                                                              |
+| Inline message / callout                | `Alert` (field/section); `Banner` for page-level with a CTA                 |
+| Toast                                   | `SnackBar` + `useSnackBar`                                                  |
+| Passive in-app notification             | `Notification` (upper-right, auto-dismiss; use `Alert` if action is needed) |
+| Loading / empty                         | `Spinner`, `Skeleton` variants, `LoadingState`; `Empty` for no-data         |
+| Page layout                             | `PageWrapper`, `Header`, `Sidebar`, `Grid.Row` / `Grid.Col`                 |
+| Breadcrumb trail                        | `Breadcrumb`                                                                |
+| Routed nav tabs                         | `NavigationMenu` (wrap your router's `Link` in `NavigationMenu.Item`)       |
+| Pagination                              | `Pagination` (page-based or cursor-based)                                   |
+| Tabular data                            | `Table` + `TableRow` / `TableHeader` / `TableCell`                          |
+| Nested hierarchy                        | `Tree` (navigable), `TreeGrid` (hierarchical rows with columns)             |
+| Collapse a long list of items           | `Overflow` (shows a few, folds the rest into `+N`)                          |
+| Form                                    | `Form` + `FormUI.*`; `RHFControlledComponents.*` with React Hook Form       |
+| Icon                                    | Any `<XxxIcon />` (standalone component)                                    |
+| Spacing between elements                | `<Spacer size="…" />`, or `theme.spacing.*` in `css`                        |
+
+The library has roughly 90 components. For anything not listed, check the bundled type declarations
+(`dist-types/index.d.ts`) before building something custom — the export list is the authoritative
+catalog, and prop types are the authoritative API.
 
 ## Use the composite
 
-When you are about to combine primitives, stop. A purpose-built composite usually exists and
-handles state, accessibility, and theming for you.
+When you are about to combine primitives, stop. A purpose-built composite usually exists and handles
+state, accessibility, and theming for you.
 
-| About to build… | Use instead |
-| --- | --- |
-| `Tooltip` wrapping an info icon | `InfoTooltip` |
-| `Modal` with a destructive confirm button | `DangerModal` |
-| `Button` + chevron + dropdown | `SplitButton` or `DropdownMenu` |
-| `Popover` + `<ul>`/`<li>` action list | `DropdownMenu` |
-| `Input` + autocomplete list | `TypeaheadCombobox` |
-| `Input` + selectable dropdown | `DialogCombobox` or `SimpleSelect` |
-| Manually managed open/close for a section | `Accordion` |
-| A row of buttons acting as a single choice | `SegmentedControlGroup` |
+| About to build…                            | Use instead                        |
+|--------------------------------------------|------------------------------------|
+| `Tooltip` wrapping an info icon            | `InfoTooltip`                      |
+| `Modal` with a destructive confirm button  | `DangerModal`                      |
+| `Button` + chevron + dropdown              | `SplitButton` or `DropdownMenu`    |
+| `Popover` + `<ul>`/`<li>` action list      | `DropdownMenu`                     |
+| `Input` + autocomplete list                | `TypeaheadComboboxV2`              |
+| `Input` + selectable dropdown              | `DialogCombobox` or `SimpleSelect` |
+| Manually managed open/close for a section  | `Accordion`                        |
+| A row of buttons acting as a single choice | `SegmentedControlGroup`            |
 
 ### Picking an overlay
 
-| Trigger / intent | Use |
-| --- | --- |
-| Short label on hover/focus | `Tooltip` |
-| Info icon + its tooltip | `InfoTooltip` |
-| Info icon + rich clickable content | `InfoPopover` |
-| Click for custom transient content | `Popover` |
-| Hover for a rich preview card | `HoverCard` |
-| A list of actions | `DropdownMenu` (or `ContextMenu` on right-click) |
-| Blocking dialog | `Modal` / `DangerModal` |
-| Side panel | `Drawer` (`Drawer.Root` / `.Trigger` / `.Content`) |
+| Trigger / intent                   | Use                                                |
+|------------------------------------|----------------------------------------------------|
+| Short label on hover/focus         | `Tooltip`                                          |
+| Info icon + its tooltip            | `InfoTooltip`                                      |
+| Info icon + rich clickable content | `InfoPopover`                                      |
+| Click for custom transient content | `Popover`                                          |
+| Hover for a rich preview card      | `HoverCard`                                        |
+| A list of actions                  | `DropdownMenu` (or `ContextMenu` on right-click)   |
+| Blocking dialog                    | `Modal` / `DangerModal`                            |
+| Side panel                         | `Drawer` (`Drawer.Root` / `.Trigger` / `.Content`) |
 
 ## Common components
 
 ### Button
 
-`componentId` is required. `type` is `primary | tertiary | link` (omit for the default);
-`danger` for destructive; `size="small"` for compact.
+`type` is `primary | tertiary | link` (omit for the default); `danger` for destructive;
+`size="small"` for compact.
 
 ```tsx
 <Button componentId="settings.save" type="primary" onClick={handleSave}>
@@ -159,13 +230,13 @@ handles state, accessibility, and theming for you.
 </Button>
 
 // Icon-only buttons must carry an accessible label.
-<Button componentId="row.delete" icon={<TrashIcon />} aria-label="Delete row" danger />
+<Button componentId="row.delete" icon={<TrashIcon/>} aria-label="Delete row" danger/>
 ```
 
 ### Typography
 
-Never render bare `<h1>`–`<h4>`, `<p>`, or `<a>` for content, so that sizing, color tokens, and
-link behavior come from the system.
+Never render bare `<h1>`–`<h4>`, `<p>`, or `<a>` for content, so that sizing, color tokens, and link
+behavior come from the system.
 
 ```tsx
 <Typography.Title level={2}>Section title</Typography.Title>
@@ -182,14 +253,15 @@ Give every input a real label, not a `placeholder` alone. Use `validationState`
 
 ```tsx
 <FormUI.Label htmlFor="email">Email</FormUI.Label>
-<Input id="email" componentId="signup.email" type="email" />
-<FormUI.Message message="Enter a valid email" type="error" />
+<Input id="email" componentId="signup.email" type="email"/>
+<FormUI.Message message="Enter a valid email" type="error"/>
 
 <Checkbox componentId="terms.accept" isChecked={agreed} onChange={setAgreed}>
   I agree to the terms
 </Checkbox>
 
-<Switch componentId="settings.notifications" checked={enabled} onChange={setEnabled} label="Email notifications" />
+<Switch componentId="settings.notifications" checked={enabled} onChange={setEnabled}
+        label="Email notifications"/>
 
 <SimpleSelect componentId="chart.type" value={type} onChange={setType} placeholder="Chart type">
   <SimpleSelectOption value="bar">Bar</SimpleSelectOption>
@@ -200,15 +272,15 @@ Give every input a real label, not a `placeholder` alone. Use `validationState`
 With React Hook Form, use `RHFControlledComponents.*` — each takes `name` + `control` + `rules`
 plus the underlying component's props. Available: `Input`, `PasswordInput`, `TextArea`,
 `Select`, `Checkbox`, `CheckboxGroup`, `Radio`, `RadioGroup`, `Switch`, `DialogCombobox`,
-`TypeaheadCombobox`, `MultiSelectTypeaheadCombobox`.
+`TypeaheadComboboxV2`, `MultiSelectTypeaheadComboboxV2`.
 
 ```tsx
 <Form componentId="signup.form" onSubmit={handleSubmit(onSubmit)}>
   <RHFControlledComponents.Input
-    name="email"
-    control={control}
-    componentId="signup.email"
-    rules={{ required: 'Email is required' }}
+      name="email"
+      control={control}
+      componentId="signup.email"
+      rules={{required: 'Email is required'}}
   />
   <Button componentId="signup.submit" htmlType="submit" type="primary">
     Sign up
@@ -223,12 +295,12 @@ restyling a `Modal`. Both need a `title` for their accessible name.
 
 ```tsx
 <DangerModal
-  componentId="delete.modal"
-  visible={open}
-  title="Delete project"
-  okText="Delete"
-  onOk={handleDelete}
-  onCancel={close}
+    componentId="delete.modal"
+    visible={open}
+    title="Delete project"
+    okText="Delete"
+    onOk={handleDelete}
+    onCancel={close}
 >
   This permanently deletes all project data.
 </DangerModal>
@@ -243,11 +315,11 @@ Compound API: `Root` / `Trigger` (use `asChild` to wrap your own `Button`) / `Co
 ```tsx
 <DropdownMenu.Root>
   <DropdownMenu.Trigger asChild>
-    <Button componentId="row.menu" icon={<OverflowIcon />} aria-label="More actions" />
+    <Button componentId="row.menu" icon={<OverflowIcon/>} aria-label="More actions"/>
   </DropdownMenu.Trigger>
   <DropdownMenu.Content>
     <DropdownMenu.Item componentId="row.edit" onClick={edit}>Edit</DropdownMenu.Item>
-    <DropdownMenu.Separator />
+    <DropdownMenu.Separator/>
     <DropdownMenu.Item componentId="row.delete" onClick={remove}>Delete</DropdownMenu.Item>
   </DropdownMenu.Content>
 </DropdownMenu.Root>
@@ -255,33 +327,31 @@ Compound API: `Root` / `Trigger` (use `asChild` to wrap your own `Button`) / `Co
 
 ### Tooltip and InfoTooltip
 
-`Tooltip` wraps a control and describes it. For a standalone info affordance next to a label,
-use `InfoTooltip` — it bundles the icon, the tooltip, accessibility, and theming. Never compose
+`Tooltip` wraps a control and describes it. For a standalone info affordance next to a label, use
+`InfoTooltip` — it bundles the icon, the tooltip, accessibility, and theming. Never compose
 `Tooltip` around an `InfoIcon` yourself.
 
-Both take a required `componentId`.
-
 ```tsx
 // Incorrect — hand-rolled info affordance
-<Tooltip componentId="search.info" content="Searches project names only."><InfoIcon /></Tooltip>
+<Tooltip componentId="search.info" content="Searches project names only."><InfoIcon/></Tooltip>
 
 // Correct
 <FormUI.Label htmlFor="search">
-  Search <InfoTooltip componentId="search.info" content="Searches project names only." />
+  Search <InfoTooltip componentId="search.info" content="Searches project names only."/>
 </FormUI.Label>
 
 // Tooltip is for describing a control you already have
 <Tooltip componentId="refresh.tooltip" content="Refresh data">
-  <Button componentId="refresh" icon={<RefreshIcon />} aria-label="Refresh" />
+  <Button componentId="refresh" icon={<RefreshIcon/>} aria-label="Refresh"/>
 </Tooltip>
 ```
 
 ### Table
 
 Compose `Table` from the flat exports `TableRow`, `TableHeader`, and `TableCell`. These are
-individual named exports, not a namespace — there is no `TableUI.*`, and no separate head or
-body wrapper. Mark the header row with `isHeader`, and give each `TableHeader` a
-`componentId`. `LegacyTable` is deprecated.
+individual named exports, not a namespace — there is no `TableUI.*`, and no separate head or body
+wrapper. Mark the header row with `isHeader`, and give each `TableHeader` a
+`componentId`.
 
 ```tsx
 <Table>
@@ -290,10 +360,10 @@ body wrapper. Mark the header row with `isHeader`, and give each `TableHeader` a
     <TableHeader componentId="projects.header.status">Status</TableHeader>
   </TableRow>
   {rows.map((row) => (
-    <TableRow key={row.id}>
-      <TableCell>{row.name}</TableCell>
-      <TableCell>{row.status}</TableCell>
-    </TableRow>
+      <TableRow key={row.id}>
+        <TableCell>{row.name}</TableCell>
+        <TableCell>{row.status}</TableCell>
+      </TableRow>
   ))}
 </Table>
 ```
@@ -303,8 +373,8 @@ Related exports for richer tables: `TableRowAction`, `TableRowActionHeader`,
 
 ### Icons
 
-Icons are standalone components — `<PlusIcon />`, `<TrashIcon />`. They take no `componentId`.
-Never use the legacy `<Icon component={PlusIcon} />` form, and import icons only from
+Icons are standalone components — `<PlusIcon />`, `<TrashIcon />`. They take no `componentId`. Never
+use the legacy `<Icon component={PlusIcon} />` form, and import icons only from
 `@databricks/design-system`.
 
 ### Loading and empty states
@@ -314,36 +384,40 @@ where the content shape is known, is the single most common way agent-written Du
 unfinished.
 
 - `Skeleton` variants (`TitleSkeleton`, `ParagraphSkeleton`, `TableSkeleton`,
-  `GenericSkeleton`) — use one shaped like the content it replaces, so there is no layout jump
-  when data arrives. This is the default choice for a loading branch.
+  `GenericSkeleton`) — use one shaped like the content it replaces, so there is no layout jump when
+  data arrives. This is the default choice for a loading branch.
 - `Spinner` — only when the content shape is unknown. Pass `label` for its accessible name.
 - `Empty` — needs `title` and `description`; add a `button` for the next step.
 
 ```tsx
 // Incorrect — hand-rolled loading text
-{isLoading ? <div css={{ textAlign: 'center' }}><Typography.Text>Loading…</Typography.Text></div> : …}
+{
+  isLoading ? <div css={{textAlign: 'center'}}><Typography.Text>Loading…</Typography.Text></div> : …
+}
 
 // Correct — a skeleton shaped like the table it replaces
-{isLoading ? (
-  <TableSkeleton lines={5} />
-) : rows.length ? (
-  <Table>…</Table>
-) : (
-  <Empty title="No dashboards" description="Create one to get started." />
-)}
+{
+  isLoading ? (
+      <TableSkeleton lines={5}/>
+  ) : rows.length ? (
+      <Table>…</Table>
+  ) : (
+      <Empty title="No dashboards" description="Create one to get started."/>
+  )
+}
 ```
 
 ## Accessibility
 
-Du Bois components target WCAG 2.2 and handle roles and semantics, focus management (dialogs
-trap and restore focus; overlays handle Escape and outside-click), keyboard interaction,
-focus-visible outlines, and token contrast in both themes. The corollary: replacing a component
-with raw HTML or overriding its structure means taking all of that on yourself.
+Du Bois components target WCAG 2.2 and handle roles and semantics, focus management (dialogs trap
+and restore focus; overlays handle Escape and outside-click), keyboard interaction, focus-visible
+outlines, and token contrast in both themes. The corollary: replacing a component with raw HTML or
+overriding its structure means taking all of that on yourself.
 
 You must supply:
 
-- **Accessible labels on icon-only controls.** An icon-only `Button` has no accessible name.
-  A wrapping `Tooltip` is not a substitute — it contributes a *description*
+- **Accessible labels on icon-only controls.** An icon-only `Button` has no accessible name. A
+  wrapping `Tooltip` is not a substitute — it contributes a *description*
   (`aria-describedby`), not a *name*. Always set `aria-label`.
 - **Real labels on form controls.** A `placeholder` disappears on input and is not reliably
   announced.
@@ -369,8 +443,8 @@ You must supply:
 
 ### Raw HTML where a component exists
 
-Use Du Bois components for interactive controls and styled text. Use semantic HTML for
-structure and layout (`div`, `span`, `section`, `ul`/`li`).
+Use Du Bois components for interactive controls and styled text. Use semantic HTML for structure and
+layout (`div`, `span`, `section`, `ul`/`li`).
 
 ```tsx
 // Incorrect
@@ -386,8 +460,8 @@ structure and layout (`div`, `span`, `section`, `ul`/`li`).
 
 ### Missing or bad `componentId`
 
-Required on most interactive components, for analytics. Supply a stable, human-readable dotted
-path. Never a uuid, and never PII (emails, resource names, user input).
+Required on most interactive components, for analytics. Supply a stable, human-readable dotted path.
+Never a uuid, and never PII (emails, resource names, user input).
 
 ```tsx
 // Incorrect
@@ -403,15 +477,15 @@ path. Never a uuid, and never PII (emails, resource names, user input).
 
 ```tsx
 // Incorrect
-<div css={{ color: '#64727D', marginTop: 8, padding: '4px 12px' }} />
+<div css={{color: '#64727D', marginTop: 8, padding: '4px 12px'}}/>
 
 // Correct
 <div
-  css={{
-    color: theme.colors.textSecondary,
-    marginTop: theme.spacing.sm,
-    padding: `${theme.spacing.xs}px ${theme.spacing.mid}px`,
-  }}
+    css={{
+      color: theme.colors.textSecondary,
+      marginTop: theme.spacing.sm,
+      padding: `${theme.spacing.xs}px ${theme.spacing.mid}px`,
+    }}
 />
 ```
 
@@ -423,51 +497,50 @@ Don't reach for `css=`, `style=`, `dangerouslySetAntdProps`, `dangerouslyAppendE
 
 ```tsx
 // Incorrect — fighting the component
-<Button componentId="x" css={{ backgroundColor: '#1B5E20', border: 'none' }}>Save</Button>
+<Button componentId="x" css={{backgroundColor: '#1B5E20', border: 'none'}}>Save</Button>
 
 // Correct — use the intended prop
 <Button componentId="x" type="primary">Save</Button>
 ```
 
-`className` for *layout* (margin, max-width, grid placement) is fine. `className` or `css` to
-change a component's *colors or typography* is not.
+`className` for *layout* (margin, max-width, grid placement) is fine. `className` or `css` to change
+a component's *colors or typography* is not.
 
 ### Legacy components
 
 Du Bois ships modern replacements for every `Legacy*` component. Don't introduce new
-`LegacySelect`, `LegacyTable`, `LegacyTooltip`, `LegacyPopover`, or `LegacyForm` imports.
+`LegacySelect`, `LegacyTable`, `LegacyPopover`, or `LegacyForm` imports.
 `Layout` (`Layout.Header` / `.Sider` / `.Content`) is likewise deprecated — use `PageWrapper` +
 `Header`.
 
 ### Direct AntD imports
 
-Du Bois is built on AntD internally. Never import AntD or `@ant-design/icons` directly — it
-bypasses theming and breaks on version bumps.
+Du Bois is built on AntD internally. Never import AntD or `@ant-design/icons` directly — it bypasses
+theming and breaks on version bumps.
 
 ```tsx
 // Incorrect
-import { Button } from 'antd';
-import { PlusOutlined } from '@ant-design/icons';
+import {Button} from 'antd';
+import {PlusOutlined} from '@ant-design/icons';
 
 // Correct
-import { Button, PlusIcon } from '@databricks/design-system';
+import {Button, PlusIcon} from '@databricks/design-system';
 ```
 
 ## Making it look good
 
-Polish comes from restraint and consistency, not decoration. Gradients, glass effects, heavy
-shadows, and custom accent colors make an enterprise data product look worse. If you are
-tempted to hand-write a color, shadow, radius, or spacing value to make something "pop," that
-is the signal you are leaving the system.
-
-- **Use the scales.** Reuse a few spacing steps for rhythm rather than mixing `13px` and
-  `15px`. Establish hierarchy with `Typography.Title` levels and `Text` sizes, never a hand-set
-  `fontSize`. Body text reads best at 45–90 characters per line.
-- **Let components own elevation.** Card, Popover, Modal, and Dropdown apply their own shadow.
-  Setting `boxShadow` by hand is almost always wrong.
-- **Let semantic tokens carry state.** Prefer a component's own prop (`type="primary"`,
-  `danger`) over reaching for a raw token — the component wires the full hover/press/disabled
-  set. Never let color be the only signal for meaning; pair it with an icon, label, or weight.
-- **Build the states everyone skips.** Loading (shape-matched skeletons), empty (`Empty` with a
-  next step), and hover/focus/active/disabled are what separate polished UI from unpolished.
+Polish is restraint, not decoration. Gradients, glass effects, heavy shadows, and custom accent
+colors make an enterprise data product look worse; hand-writing a color, shadow, radius, or spacing
+value to make something "pop" is the signal you are leaving the system.
+
+- **Use the scales.** Reuse a few spacing steps rather than mixing `13px` and `15px`; set hierarchy
+  with `Typography.Title` levels and `Text` sizes, never a hand-set `fontSize`. Body text reads best
+  at 45–90 characters per line.
+- **Let components own elevation.** Card, Popover, Modal, and Dropdown apply their own shadow —
+  hand-set `boxShadow` is almost always wrong.
+- **Let semantic tokens carry state.** Prefer a component's own prop (`type="primary"`, `danger`)
+  over a raw token; it wires the full hover/press/disabled set. Never let color be the only signal —
+  pair it with an icon, label, or weight.
+- **Build the states everyone skips** — loading (shape-matched skeletons), empty (`Empty` with a
+  next step), hover/focus/active/disabled.
 - **Match density to context** with `size` props rather than cramming default-size components.