@databricks/design-system 2.0.0 → 2.0.2

package/AGENTS.md

@@ -0,0 +1,473 @@
+# 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`.
+
+## 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.
+3. **Always pass `componentId`** — stable, dotted, no PII.
+4. **Never hardcode colors or spacing** — read `theme.*` tokens.
+
+## Setup
+
+Install the package and its peer dependencies:
+
+```bash
+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.
+
+Import the stylesheet once at your app's entry point, wrap the tree in
+`DesignSystemProvider`, and render `ApplyGlobalStyles` inside it:
+
+```tsx
+import '@databricks/design-system/index.css';
+import '@databricks/design-system/fonts/dm-sans.css';
+
+import { ApplyGlobalStyles, DesignSystemProvider } from '@databricks/design-system';
+
+export const App = () => (
+  <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.
+
+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:
+
+```ts
+// css.d.ts
+declare module '*.css';
+```
+
+## Theming
+
+Read every design value off the theme.
+
+```tsx
+import { useDesignSystemTheme } from '@databricks/design-system';
+
+const MyPanel = () => {
+  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,
+      }}
+    />
+  );
+};
+```
+
+- **Spacing** — `theme.spacing`: `xs` (4), `sm` (8), `mid` (12), `md` (16), `lg` (24), `xl` (32).
+  For a gap between two elements use `<Spacer size="md" />`.
+- **Colors** — semantic tokens on `theme.colors`: `textPrimary`, `textSecondary`,
+  `backgroundPrimary`, `border`, `actionPrimaryBackgroundDefault`, and so on. Never a hex value.
+- **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.
+
+## 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.
+
+| 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` |
+
+### 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`) |
+
+## Common components
+
+### Button
+
+`componentId` is required. `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}>
+  Save changes
+</Button>
+
+// Icon-only buttons must carry an accessible label.
+<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.
+
+```tsx
+<Typography.Title level={2}>Section title</Typography.Title>
+<Typography.Paragraph>Body copy.</Typography.Paragraph>
+<Typography.Text bold>Emphasis</Typography.Text>
+<Typography.Text color="secondary" size="sm">Muted helper text</Typography.Text>
+<Typography.Link href="/docs">Learn more</Typography.Link>
+```
+
+### Input and form controls
+
+Give every input a real label, not a `placeholder` alone. Use `validationState`
+(`error | warning | success`) to show state.
+
+```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" />
+
+<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" />
+
+<SimpleSelect componentId="chart.type" value={type} onChange={setType} placeholder="Chart type">
+  <SimpleSelectOption value="bar">Bar</SimpleSelectOption>
+  <SimpleSelectOption value="line">Line</SimpleSelectOption>
+</SimpleSelect>
+```
+
+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`.
+
+```tsx
+<Form componentId="signup.form" onSubmit={handleSubmit(onSubmit)}>
+  <RHFControlledComponents.Input
+    name="email"
+    control={control}
+    componentId="signup.email"
+    rules={{ required: 'Email is required' }}
+  />
+  <Button componentId="signup.submit" htmlType="submit" type="primary">
+    Sign up
+  </Button>
+</Form>
+```
+
+### Modal and DangerModal
+
+`Modal` is controlled by `visible`. Use `DangerModal` for destructive confirmations rather than
+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}
+>
+  This permanently deletes all project data.
+</DangerModal>
+```
+
+### DropdownMenu
+
+Compound API: `Root` / `Trigger` (use `asChild` to wrap your own `Button`) / `Content` / `Item` /
+`Separator` / `CheckboxItem` / `RadioGroup` + `RadioItem` / `Sub`. `componentId` goes on each
+`Item`.
+
+```tsx
+<DropdownMenu.Root>
+  <DropdownMenu.Trigger asChild>
+    <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.Item componentId="row.delete" onClick={remove}>Delete</DropdownMenu.Item>
+  </DropdownMenu.Content>
+</DropdownMenu.Root>
+```
+
+### 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` 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>
+
+// Correct
+<FormUI.Label htmlFor="search">
+  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" />
+</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.
+
+```tsx
+<Table>
+  <TableRow isHeader>
+    <TableHeader componentId="projects.header.name">Name</TableHeader>
+    <TableHeader componentId="projects.header.status">Status</TableHeader>
+  </TableRow>
+  {rows.map((row) => (
+    <TableRow key={row.id}>
+      <TableCell>{row.name}</TableCell>
+      <TableCell>{row.status}</TableCell>
+    </TableRow>
+  ))}
+</Table>
+```
+
+Related exports for richer tables: `TableRowAction`, `TableRowActionHeader`,
+`TableRowSelectCell`, `TableFilterInput`, `TableFilterLayout`, `TableSkeleton`.
+
+### Icons
+
+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
+
+Never hand-roll these. A `<div>` containing "Loading…" text, or a bare centered `Spinner`
+where the content shape is known, is the single most common way agent-written Du Bois UI looks
+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.
+- `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> : …}
+
+// 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." />
+)}
+```
+
+## 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.
+
+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*
+  (`aria-describedby`), not a *name*. Always set `aria-label`.
+- **Real labels on form controls.** A `placeholder` disappears on input and is not reliably
+  announced.
+- **Meaningful text.** Button and link text must describe the action, not "Click here".
+- **Semantic structure.** Landmarks (`nav`, `main`, `section`) and headings via
+  `Typography.Title` with the correct `level`, not a tree of `<div>`s.
+- **No nested interactive controls.** An interactive element must never contain another. This
+  applies inside composites whose items are already interactive: put the action on
+  `DropdownMenu.Item` itself, or use `asChild` to render the item *as* a link. Use
+  `DropdownMenu.CheckboxItem` / `RadioItem` rather than nesting a `Checkbox` in an `Item`.
+
+```tsx
+// Incorrect — button nested inside an already-interactive menu item
+<DropdownMenu.Item componentId="row.rename">
+  <Button componentId="row.rename.btn" onClick={rename}>Rename</Button>
+</DropdownMenu.Item>
+
+// Correct — the item is the control
+<DropdownMenu.Item componentId="row.rename" onClick={rename}>Rename</DropdownMenu.Item>
+```
+
+## Pitfalls
+
+### 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`).
+
+```tsx
+// Incorrect
+<button onClick={save}>Save</button>
+<a href="/docs">Docs</a>
+<h2>Settings</h2>
+
+// Correct
+<Button componentId="save" onClick={save}>Save</Button>
+<Typography.Link href="/docs">Docs</Typography.Link>
+<Typography.Title level={2}>Settings</Typography.Title>
+```
+
+### 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).
+
+```tsx
+// Incorrect
+<Button onClick={save}>Save</Button>
+<Button componentId={crypto.randomUUID()} onClick={save}>Save</Button>
+<Button componentId={`share.${user.email}`} onClick={save}>Save</Button>
+
+// Correct
+<Button componentId="settings.save" onClick={save}>Save</Button>
+```
+
+### Hardcoded colors and spacing
+
+```tsx
+// Incorrect
+<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`,
+  }}
+/>
+```
+
+### Style-overriding a component
+
+Don't reach for `css=`, `style=`, `dangerouslySetAntdProps`, `dangerouslyAppendEmotionCSS`,
+`!important`, or an `as` cast to reshape a component's appearance. Look for a real prop first
+(`type`, `size`, `danger`, `contentPadding`).
+
+```tsx
+// Incorrect — fighting the component
+<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.
+
+### Legacy components
+
+Du Bois ships modern replacements for every `Legacy*` component. Don't introduce new
+`LegacySelect`, `LegacyTable`, `LegacyTooltip`, `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.
+
+```tsx
+// Incorrect
+import { Button } from 'antd';
+import { PlusOutlined } from '@ant-design/icons';
+
+// Correct
+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.
+- **Match density to context** with `size` props rather than cramming default-size components.

package/CHANGELOG.md

@@ -0,0 +1,5 @@
+# Changelog
+
+## 2.0.2 (2026-08-21T20:54:03Z)
+
+- Add changelog

package/README.md

@@ -1,7 +1,9 @@
 # DuBois Design System
 
-DuBois is a shared language for building products at Databricks.
+Component library for Databricks.
 
-We'll be sharing more soon, stay tuned!
+## Using DuBois with a coding agent
 
-https://databricks.com/blog/category/engineering
+This package ships `AGENTS.md` — setup, component selection, theming, accessibility, and the
+pitfalls to avoid. You can include `@node_modules/@databricks/design-system/AGENTS.md` in your project's agent
+instructions.