` of flex rows with hardcoded borders standing in for a table (no `` semantics; use `Table` or `DataTable`) ## Related * [Table](/components/table/) * [DataTable](/components/data-table/) * [Badge](/components/badge/) * [Tag](/components/tag/) * [EmptyState](/components/empty-state/) * [Avatar](/components/avatar/) * [Skeleton](/components/skeleton/) * [Spinner](/components/spinner/) * [ProgressBar](/components/progress-bar/) * [Pagination](/components/pagination/) * [Label](/components/label/) # Feedback > Four mechanisms report outcomes to the user: inline FormControl.Validation, Banner, Toast, and Dialog. Each answers a different combination of four questions: h Four mechanisms report outcomes to the user: inline `FormControl.Validation`, `Banner`, `Toast`, and `Dialog`. Each answers a different combination of four questions: how long the message persists, whether it blocks, what it is about, and who caused it. Pick by those answers, never by how prominent the message should feel. ## The decision table [Section titled “The decision table”](#the-decision-table) | Mechanism | Persists | Blocks | Scope | Initiated by | Use for | | ---------------------------------------- | ------------------------------------------------ | ---------- | ------------------------------------------------- | ------------------------------------------------ | --------------------------------------------------------------------------------- | | `FormControl.Validation variant="error"` | until the field is fixed | no | one field | the user’s input | a field that fails validation | | `Banner` | until the condition clears or the user dismisses | no | a page, section, or form | system state or a server response | form-level and server errors, quota and maintenance notices, a page-level warning | | `Toast` via `useToast` | transient, auto-dismisses (default 5s) | no | the whole app, about an action that just finished | the user’s own action | “Saved”, “Copied”, “Story published”, a background failure with a retry elsewhere | | `Dialog` | until the user decides | yes, modal | one decision | the user’s action, needing confirmation or input | destructive confirmations, unsaved-changes prompts, a short focused form | ## Rules [Section titled “Rules”](#rules) 1. Decide with three questions in order. Is it about one field? Then `FormControl.Validation`. Does the user have to decide something before continuing? Then `Dialog`. Otherwise: does it stay relevant while the user looks at this page? Then `Banner`; if it is about an action that just completed and needs no follow-up, `Toast`. 2. A field error is always inline `FormControl.Validation` on that field. It is never a `Banner`, never a `Toast`, never a `Dialog`. 3. A form-level or server error is a `Banner variant="danger"` above the fields inside the form. It is not dismissible (`onDismiss` is omitted) while the error still needs fixing. 4. A `Toast` confirms success of a completed action. It never carries information the user must act on: an error that blocks the user’s task is a `Banner` or a `FormControl.Validation`, and a decision is a `Dialog`. A danger toast is acceptable only for a background failure that the user can recover from elsewhere. 5. A `Dialog` is used only when the user must decide or supply something before the flow continues. A status message (“Saved”) is never a dialog. A destructive confirmation names the object in its `title` (“Delete article?”) and its confirming button (``). 6. One channel per event. A saved form gets a toast, or a success banner, not both. A failed request gets one banner, not a banner and a toast. 7. `variant` is chosen by meaning: `success` for done, `danger` for failed or destructive, `warning` (`Banner`) for something needing attention, `info` for neutral notices. `Banner variant="danger"` and a danger toast are announced assertively (`role="alert"`); the others politely (`role="status"`). Roles are never overridden. 8. A `Banner` gets `onDismiss` only when the message is non-critical (an announcement, a tip). A dismissed critical banner cannot be recovered by the user. 9. Empty results are not feedback. Zero records is an `EmptyState`; a filter that hides every row keeps the table and speaks through `DataTable` `emptyText`. Neither is a `Banner`. See data-display.md. 10. Loading is not feedback about an outcome. A known layout loads behind `Skeleton`; an indeterminate short wait shows `Spinner` with a `label`; a measurable job shows `ProgressBar` with `aria-label`. See data-display.md. 11. `Tooltip` is a hint about a control, not a feedback channel. It never reports an outcome or an error. 12. Feedback copy states what happened and, for errors, what to do next, in sentence case without exclamation marks: `title="Could not publish"`, body “The image is larger than 10 MB. Choose a smaller file.” See content.md. ## Do / Don’t [Section titled “Do / Don’t”](#do--dont) * ✅ `Enter a valid email address.` (one field, inline) * ✅ `The server rejected the request. Try again in a few minutes.` (form-level, persistent, not dismissible) * ✅ `toast({ variant: 'success', title: 'Story published', message: 'Readers can see it now.' })` (transient confirmation of the user’s own action) * ✅ `

`/`

`. * `accessor` returns the **raw** value used for sorting + filtering; `cell` is only for display (e.g. wrapping a status in a `Tag`). Keep them consistent — sort on the value, not the badge. * Turn on `sortable` per column for click-to-sort (asc → desc → off), and `filterable` for a per-column dropdown built from the column’s distinct values. * Provide a `rowKey` when rows can reorder or the list is large — falling back to the index is fine only for static data. * Use numeric `align="end"` for number columns so they line up. * `emptyText` speaks when a search or filter matches no rows and the table stays on screen. When the collection itself has zero records, render an `EmptyState` instead of the table. * This is **client-side** (filters/sort run over the `data` you pass). For huge or server-paged data, drive `Table.*` yourself and fetch on change. ## Do / Don’t [Section titled “Do / Don’t”](#do--dont) * ✅ `` * ✅ a status column: `{ id: 'status', header: 'CI', filterable: true, cell: r => {r.status} }` * ❌ Building search/filter/sort state around a raw `Table` when DataTable already does it. * ❌ Sorting/filtering on the rendered `cell` output instead of the underlying value. **See also:** `Table` for hand-composed markup, `EmptyState` for an empty collection, `Pagination` for paged data; system guideline `data-display`. ## Examples [Section titled “Examples”](#examples) 2 stories for DataTable — open in Storybook * [Default](https://tenet-ui.pages.dev/storybook/?path=/story/components-datatable--default) `components-datatable--default` * [Search Only](https://tenet-ui.pages.dev/storybook/?path=/story/components-datatable--search-only) `components-datatable--search-only` The full matrix (all args, controls, accessibility panel) is in [Storybook](https://tenet-ui.pages.dev/storybook). ## Props [Section titled “Props”](#props) | Prop | Type | Default | Description | | ------------------- | ----------------------------------------------- | ------------------- | ----------------------------------------------------------------------- | | `columns` \* | `DataTableColumn[]` | — | Column definitions, left to right. | | `data` \* | `Row[]` | — | The rows to render. | | `rowKey` | `(row: Row, index: number) => string \| number` | `index` | Stable React key for a row. Defaults to the row index. | | `searchable` | `boolean` | `true` | Show the global search box. | | `searchPlaceholder` | `string` | `Search…` | Placeholder for the global search box. | | `title` | `ReactNode` | — | Optional surface title (rendered in a `Table.Container`). | | `subtitle` | `ReactNode` | — | Optional surface subtitle. | | `actions` | `ReactNode` | — | Actions rendered at the top-right of the toolbar (e.g. a "New" button). | | `density` | `TableDensity` | `normal` | Row height / cell padding scale. | | `emptyText` | `ReactNode` | `No matching rows.` | Message shown when no rows match the active filters. | | `className` | `string` | — | | \* required ## Related types ### `DataTableColumn` | Member | Type | Default | Description | | ------------ | ------------------------- | ------- | ---------------------------------------------------------------------------------- | | `id` \* | `string` | — | Stable key — also used to read the cell value when `accessor` is omitted. | | `header` \* | `ReactNode` | — | Column heading text. | | `accessor` | `(row: Row) => unknown` | — | Read the raw value for a row. Defaults to `row[id]`. Used for sorting + filtering. | | `cell` | `(row: Row) => ReactNode` | — | Custom cell renderer. Defaults to rendering the accessor value as text. | | `align` | `CellAlign` | — | Cell + header alignment. | | `sortable` | `boolean` | — | Allow clicking the header to sort by this column. | | `filterable` | `boolean` | — | Show a per-column dropdown filter built from the distinct values in the data. | ## Related components * [Table](/components/table/) * [EmptyState](/components/empty-state/) * [Pagination](/components/pagination/) * [Tag](/components/tag/) * [Select](/components/select/) # DatePicker > When to use: picking a single date from a compact field that opens a calendar on demand (forms, filters). For an always-visible month grid, use Calendar directl Status: stableAccessibility reviewedtenet-ui\@0.4.0 Import ```tsx import { DatePicker } from 'tenet-ui'; ``` Source: [src/components/DatePicker/DatePicker.tsx](https://github.com/apurvkhare/tenet-ui/blob/main/src/components/DatePicker/DatePicker.tsx) ## Usage guidelines [Section titled “Usage guidelines”](#usage-guidelines) **When to use:** picking a single date from a compact field that opens a calendar on demand (forms, filters). For an always-visible month grid, use `Calendar` directly (DatePicker wraps it). ## Rules [Section titled “Rules”](#rules) * Give it an accessible name via `FormControl.Label` or `aria-label`. * Control it with `value` + `onChange`, or leave uncontrolled with `defaultValue`. `onChange` hands you a real `Date`. * Constrain with `min` / `max`; the popover calendar disables out-of-range days and stops its nav at the boundary. * For form submission pass `name` — it emits a hidden `yyyy-mm-dd` input. Use `size` / `fullWidth` from the scale (`block` is the deprecated 0.3.0 name and warns) and `invalid` for validation state. * Set `weekStartsOn={1}` and/or `locale` for non-US conventions; the displayed date and the calendar both follow them. * **Never** assemble a text input + hand-built dropdown calendar yourself — the popover focus management, the ARIA grid, and the keyboard model are exactly what this composes for you. ## Do / Don’t [Section titled “Do / Don’t”](#do--dont) * ✅ `` * ✅ in a form: `Start date` * ❌ `` next to a `

` calendar wired by hand — no focus trap-out, no roving grid, no Escape handling. * ❌ Storing the value as a formatted string — keep the `Date`; format only for display. **See also:** `Calendar` (the inline grid it wraps), `FormControl`; system guideline `forms`. ## Examples [Section titled “Examples”](#examples) 4 stories for DatePicker — open in Storybook * [Default](https://tenet-ui.pages.dev/storybook/?path=/story/components-datepicker--default) `components-datepicker--default` * [With Value](https://tenet-ui.pages.dev/storybook/?path=/story/components-datepicker--with-value) `components-datepicker--with-value` * [With Range](https://tenet-ui.pages.dev/storybook/?path=/story/components-datepicker--with-range) `components-datepicker--with-range` * [Disabled](https://tenet-ui.pages.dev/storybook/?path=/story/components-datepicker--disabled) `components-datepicker--disabled` The full matrix (all args, controls, accessibility panel) is in [Storybook](https://tenet-ui.pages.dev/storybook). ## Props [Section titled “Props”](#props) | Prop | Type | Default | Description | | ------------------ | ---------------------------------------------- | ---------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------- | | `value` | `Date \| null` | — | Controlled selected date (null = empty). | | `defaultValue` | `Date \| null` | — | Uncontrolled initial selected date. | | `onChange` | `(date: Date) => void` | — | Called with the chosen date. | | `min` | `Date` | — | Earliest selectable day (inclusive). | | `max` | `Date` | — | Latest selectable day (inclusive). | | `weekStartsOn` | `WeekStart` | `0` | First day of the week: 0 = Sunday (default), 1 = Monday. | | `locale` | `string` | `runtime locale` | BCP-47 locale for the displayed date + calendar. Defaults to the runtime locale. | | `placeholder` | `string` | `Select a date…` | Text shown in the trigger when no date is selected. | | `size` | `'small' \| 'medium' \| 'large'`DatePickerSize | `medium` | Control height / font scale. | | `fullWidth` | `boolean` | — | Stretch the trigger to fill the available width. | | `block`deprecated | `boolean` | — | Stretch the trigger to fill the available width.**Deprecated since 0.4.0.** Use `fullWidth` instead (renamed in 0.4.0). `block` keeps working until 0.5.0. | | `invalid` | `boolean` | `false` | Invalid state (danger border + aria-invalid). | | `disabled` | `boolean` | `false` | Disable the control. | | `required` | `boolean` | `false` | Required (sets aria-required; pairs with FormControl). | | `name` | `string` | — | Form field name — emits a hidden input (yyyy-mm-dd) so the value submits with a form. | | `id` | `string` | — | Id applied to the trigger (FormControl sets this automatically). | | `className` | `string` | — | | | `aria-label` | `string` | — | | | `aria-describedby` | `string` | — | | Deprecated props keep working for one minor release; the replacement is named in the row. ## Related components * [Calendar](/components/calendar/) * [FormControl](/components/form-control/) * [TextInput](/components/text-input/) * [Popover](/components/popover/) # Dialog > When to use: a focused task or confirmation that must interrupt the flow — destructive confirmations, short forms, critical choices. For non-blocking feedback u Status: stableAccessibility reviewedtenet-ui\@0.4.0 Import ```tsx import { Dialog } from 'tenet-ui'; ``` Source: [src/components/Dialog/Dialog.tsx](https://github.com/apurvkhare/tenet-ui/blob/main/src/components/Dialog/Dialog.tsx) ## Usage guidelines [Section titled “Usage guidelines”](#usage-guidelines) **When to use:** a focused task or confirmation that must interrupt the flow — destructive confirmations, short forms, critical choices. For non-blocking feedback use a toast or `Banner`; for lightweight hints use a `Tooltip`. ## Rules [Section titled “Rules”](#rules) * It’s a controlled component: drive `open` and handle `onClose` (Escape, backdrop, and the close button all call it). Render your actions in `footer`. * Always pass a `title` — it’s the dialog’s accessible name. Add a `description` for context; it’s wired as `aria-describedby`. * Focus management is automatic: focus moves in on open, is trapped while open, and is restored to the trigger on close, and body scroll is locked. **Don’t** re-implement this with a `position:fixed` div. * For a destructive confirm, keep the confirming button `variant="danger"` and make the consequence explicit in the body. * Keep dialogs short. If it scrolls a lot or has many steps, it probably wants its own page. ## Do / Don’t [Section titled “Do / Don’t”](#do--dont) * ✅ `` * ❌ A hand-built overlay div — no focus trap, no scroll lock, no Escape, no restore. * ❌ Using a dialog for a transient “Saved!” message — that’s a toast. **See also:** `Popover` for non-modal surfaces, `Banner` and `Toast` for non-blocking messages; system guideline `feedback` has the decision table. ## Examples [Section titled “Examples”](#examples) 1 story for Dialog — open in Storybook * [Default](https://tenet-ui.pages.dev/storybook/?path=/story/components-dialog--default) `components-dialog--default` The full matrix (all args, controls, accessibility panel) is in [Storybook](https://tenet-ui.pages.dev/storybook). ## Props [Section titled “Props”](#props) | Prop | Type | Default | Description | | ----------------- | ------------------------------------------ | -------- | --------------------------------------------------------------------- | | `open` \* | `boolean` | — | Whether the dialog is open. | | `onClose` \* | `() => void` | — | Called when the user requests close (Escape, backdrop, close button). | | `title` \* | `ReactNode` | — | Accessible title — also the visible heading. | | `description` | `ReactNode` | — | Optional supporting description under the title. | | `size` | `'small' \| 'medium' \| 'large'`DialogSize | `medium` | Width from the scale. | | `footer` | `ReactNode` | — | Footer actions (e.g. Cancel / Confirm buttons). | | `closeOnBackdrop` | `boolean` | `true` | Allow closing by clicking the backdrop. | | `children` | `ReactNode` | — | Body content. | | `className` | `string` | — | | \* required ## Related components * [Popover](/components/popover/) * [Button](/components/button/) * [Banner](/components/banner/) * [Toast](/components/toast/) # Divider > When to use: a thin rule that separates content groups — sections of a menu, columns in a toolbar, an "or" between two choices. Status: stableAccessibility reviewedtenet-ui\@0.4.0 Import ```tsx import { Divider } from 'tenet-ui'; ``` Also accepts every prop of `HTMLAttributes`. Source: [src/components/Divider/Divider.tsx](https://github.com/apurvkhare/tenet-ui/blob/main/src/components/Divider/Divider.tsx) ## Usage guidelines [Section titled “Usage guidelines”](#usage-guidelines) **When to use:** a thin rule that separates content groups — sections of a menu, columns in a toolbar, an “or” between two choices. ## Rules [Section titled “Rules”](#rules) * It renders `role="separator"` with the correct `aria-orientation`, so it’s a real separator, not a decorative border. Use it instead of a styled `

` or a bordered `

`. * Use a labelled horizontal divider (“or”) to split alternative actions; keep the label one or two words. * Vertical dividers need a flex parent with a height to stretch against. * Don’t stack dividers to fake spacing — reach for `Stack` gaps for layout and a divider only when a visible rule communicates a boundary. ## Do / Don’t [Section titled “Do / Don’t”](#do--dont) * ✅ `` · `or` * ✅ `AB` * ❌ `

` — off-system thickness/color. ## Examples [Section titled “Examples”](#examples) 3 stories for Divider — open in Storybook * [Horizontal](https://tenet-ui.pages.dev/storybook/?path=/story/components-divider--horizontal) `components-divider--horizontal` * [Labelled](https://tenet-ui.pages.dev/storybook/?path=/story/components-divider--labelled) `components-divider--labelled` * [Vertical](https://tenet-ui.pages.dev/storybook/?path=/story/components-divider--vertical) `components-divider--vertical` The full matrix (all args, controls, accessibility panel) is in [Storybook](https://tenet-ui.pages.dev/storybook). ## Props [Section titled “Props”](#props) | Prop | Type | Default | Description | | ------------- | ---------------------------------------------- | ------------ | ------------------------------------------ | | `orientation` | `'horizontal' \| 'vertical'`DividerOrientation | `horizontal` | Layout direction. | | `children` | `ReactNode` | — | Optional centered label (horizontal only). | ## Related components * [Stack](/components/stack/) * [Menu](/components/menu/) * [Card](/components/card/) # EmptyState > When to use: a table, list, inbox, search or filter that has nothing to show — first run ("No stories yet"), an exhausted filter ("No results for 'budget'"), a Status: stableAccessibility reviewedtenet-ui\@0.4.0 Import ```tsx import { EmptyState } from 'tenet-ui'; ``` Also accepts every prop of `Omit, 'title'>`. Source: [src/components/EmptyState/EmptyState.tsx](https://github.com/apurvkhare/tenet-ui/blob/main/src/components/EmptyState/EmptyState.tsx) ## Usage guidelines [Section titled “Usage guidelines”](#usage-guidelines) **When to use:** a table, list, inbox, search or filter that has nothing to show — first run (“No stories yet”), an exhausted filter (“No results for ‘budget’”), a cleared queue (“You’re all caught up”). For zero records, render it *in place of* the rows, inside the same `Card`/`Table.Container`, so the layout doesn’t jump. For an exhausted search or filter, keep the table and its toolbar on screen and pass a compact `EmptyState` (`headingLevel={4}`, no `size="large"`) as `DataTable` `emptyText`. It is not for errors (use `Banner variant="danger"`) or for loading (use `Skeleton`/`Spinner`). ## Rules [Section titled “Rules”](#rules) * `title` is required and specific: name what is empty and, for filters, echo the query. Avoid “Nothing here” / “Oops”. * `description` explains why and what to do next in one or two sentences; keep it inline content (it renders inside a paragraph). * `action` is the single step that fixes the emptiness — a `Button variant="primary"` (“Create story”, “Clear filters”). `secondaryAction` is optional and quieter (`Button variant="invisible"`, a `Link` to docs). Never two primaries; no action at all is fine when there is nothing the user can do. * `icon` is decorative and is wrapped `aria-hidden` — the title already carries the meaning. Pass an `Icon` or an inline `

` with inline `textAlign` and a `

` skips the type scale, the muted tone and the outline rules this component encodes. ## Do / Don’t [Section titled “Do / Don’t”](#do--dont) * ✅ `Create story} />` * ✅ `Clear filters} headingLevel={4} />` passed as `DataTable` `emptyText`, so the toolbar and active filters stay. * ✅ `} title="You're all caught up" />` as a page’s only content under its `h1`. * ❌ `
Nothing here
` — off-system and unspecific. * ❌ `` — failures are a `Banner`, not an empty state. See also: `DataTable` (`emptyText` for an exhausted filter), `Banner` for failures, `Skeleton` while loading; system guidelines `data-display` (when a collection shows an EmptyState) and `content` (title, description, and action copy). ## Examples [Section titled “Examples”](#examples) 6 stories for EmptyState — open in Storybook * [Default](https://tenet-ui.pages.dev/storybook/?path=/story/components-emptystate--default) `components-emptystate--default` * [Title Only](https://tenet-ui.pages.dev/storybook/?path=/story/components-emptystate--title-only) `components-emptystate--title-only` * [With Icon](https://tenet-ui.pages.dev/storybook/?path=/story/components-emptystate--with-icon) `components-emptystate--with-icon` * [With Actions](https://tenet-ui.pages.dev/storybook/?path=/story/components-emptystate--with-actions) `components-emptystate--with-actions` * [Large](https://tenet-ui.pages.dev/storybook/?path=/story/components-emptystate--large) `components-emptystate--large` * [Search Results](https://tenet-ui.pages.dev/storybook/?path=/story/components-emptystate--search-results) `components-emptystate--search-results` The full matrix (all args, controls, accessibility panel) is in [Storybook](https://tenet-ui.pages.dev/storybook). ## Props [Section titled “Props”](#props) | Prop | Type | Default | Description | | ----------------- | ----------------------------------- | -------- | -------------------------------------------------------------------------------------------------------------------------------------- | | `title` \* | `string` | — | Short, specific headline — say what is empty ("No stories yet"), not just "Nothing here". | | `description` | `ReactNode` | — | One or two sentences: why it is empty and what to do next. Inline content (rendered in a muted `Text`). | | `icon` | `ReactNode` | — | Decorative illustration or icon; wrapped `aria-hidden` — the title carries the meaning. | | `action` | `ReactNode` | — | The primary next step, usually a `Button variant="primary"`. | | `secondaryAction` | `ReactNode` | — | An optional secondary step next to `action` (a default/invisible `Button` or a `Link`). | | `size` | `'medium' \| 'large'`EmptyStateSize | `medium` | Overall scale: `medium` for a region inside a page, `large` for a whole-page/first-run state. | | `headingLevel` | `2 \| 3 \| 4`EmptyStateHeadingLevel | `3` | Semantic heading rank of the title (`h2`/`h3`/`h4`) so it fits the surrounding outline. The visual size follows `size`, not this prop. | \* required ## Related components * [Heading](/components/heading/) * [Text](/components/text/) * [Button](/components/button/) * [DataTable](/components/data-table/) * [Card](/components/card/) * [Banner](/components/banner/) * [Icon](/components/icon/) * [Table](/components/table/) # FormControl > When to use: every labeled form field. FormControl wraps a label, a field, and optional caption/validation, and wires the accessibility for you. Build forms by Status: stableAccessibility reviewedtenet-ui\@0.4.0 Import ```tsx import { FormControl } from 'tenet-ui'; ``` Also accepts every prop of `HTMLAttributes`. Source: [src/components/FormControl/FormControl.tsx](https://github.com/apurvkhare/tenet-ui/blob/main/src/components/FormControl/FormControl.tsx) ## Usage guidelines [Section titled “Usage guidelines”](#usage-guidelines) When to use: every labeled form field. `FormControl` wraps a label, a field, and optional caption/validation, and wires the accessibility for you. Build forms by stacking `FormControl`s in a `Stack`. ## Rules [Section titled “Rules”](#rules) * Wrap text-like fields (`TextInput`, `Textarea`, `Select`) in a `FormControl` with a `FormControl.Label`. The control generates a shared id and sets `htmlFor`, `aria-describedby`, `aria-invalid`, `required`, and `disabled` automatically — don’t wire ids by hand, and never use a placeholder as the label. * Use `FormControl.Caption` for help text and `FormControl.Validation variant="error"` for errors (it also flips the field to invalid). Use `variant="success"` for confirmation. * For booleans use `Checkbox` (with its own `label`); for one-of-many use `RadioGroup` + `Radio` (a `
`/`` group). Don’t put these in a `FormControl`. * Lay out fields with `` (or a `Grid` for side-by-side fields); submit with `

`–`

` to `

Newsroom

Nothing here