@mediaradar/design-components 0.10.0 → 0.12.0

package/dist/index.d.ts

@@ -17,6 +17,9 @@ import { VariantProps } from 'class-variance-authority';
  * not just a decorative hover effect. Both modes close on Escape and on any
  * outside click. The bubble is portaled to document.body and repositions
  * itself to stay clear of the right viewport edge.
+ * @a11y The trigger is a <button> reporting aria-expanded; the bubble is
+ * role="tooltip" and Escape dismisses it. It describes its anchor rather
+ * than naming it, so the anchor still needs its own accessible name.
  * @usage
  * ```tsx
  * <InfoTip text="Trims time periods to data that has finalized across the selected media formats." />
@@ -61,6 +64,10 @@ declare function InfoTip({ text, size, label, trigger }: InfoTipProps): react.JS
  * other close path discards the draft, so the trigger label never previews
  * an unapplied change. The pinned "selected" section persists across
  * searches and collapses when the search is cleared.
+ * @a11y Trigger is a <button> with aria-expanded and aria-haspopup; the menu is
+ * role="dialog", closed on Escape. Option rows are role="checkbox" with
+ * aria-checked, so each row is itself the control -- don't wrap them in
+ * another clickable element.
  * @usage
  * ```tsx
  * <AdvertiserQuickFilter options={advertisers} selected={selected} onChange={setSelected} />
@@ -139,6 +146,78 @@ interface AdvertiserSearchPromptProps {
 }
 declare function AdvertiserSearchPrompt({ label }: AdvertiserSearchPromptProps): react.JSX.Element;
 
+/**
+ * Fill and ink. `tone` answers "what kind of thing is this", never "what
+ * colour do I want" -- a caller reaching for `danger` because red looks good
+ * is the start of the drift this component replaces.
+ */
+type BadgeTone = "neutral" | "brand" | "success" | "warning" | "danger" | "ai" | "overlay";
+/**
+ * Shape and case. Orthogonal to tone: any tone can be any kind, which is what
+ * keeps this two small props instead of one list of every combination the
+ * product happens to use today.
+ */
+type BadgeKind = "label" | "count" | "eyebrow";
+interface BadgeProps {
+    /** What kind of thing this marks. Not a colour choice. */
+    tone?: BadgeTone;
+    /** Shape and case. `count` for a number, `eyebrow` for a category label. */
+    kind?: BadgeKind;
+    /** Text, or an icon plus text. Keep it to a few words -- a badge annotates, it does not explain. */
+    children: ReactNode;
+    className?: string;
+}
+/**
+ * @pattern Badge
+ * @description The one small label that annotates something else: a count on
+ * a filter, a status, a category, an AI marker, a flag over artwork. Two
+ * props -- `tone` (what kind of thing) and `kind` (shape and case) -- which
+ * between them cover every badge treatment in the product.
+ * @props
+ * tone?: 'neutral' | 'brand' | 'success' | 'warning' | 'danger' | 'ai' | 'overlay' (default 'neutral')
+ * kind?: 'label' | 'count' | 'eyebrow' (default 'label')
+ * children: ReactNode
+ * @tokens text-micro, rounded-full, bg-subtle, bg-brand-primarySoft,
+ * bg-status-success/15, bg-status-warning/30, bg-status-danger/15, bg-scrim,
+ * text-text-secondary, text-brand-primaryAction, text-text-success,
+ * text-text-warning, text-text-danger, text-ai-ontint, text-brand-onprimary,
+ * border-transparent
+ * @behavior Not interactive and carries no role: a badge is a label on
+ * something else, so it is read as part of that thing rather than announced
+ * separately. Anything clickable is a Button or a filter chip, not a Badge.
+ * Every badge is one size -- the `micro` step (11px) -- because a badge
+ * that competes with the content it annotates has stopped being a badge.
+ * @variant neutral - Default. A category, a count of something unremarkable, a quiet flag.
+ * @variant brand - This item is special in a way the product cares about -- primary, selected, yours.
+ * @variant success - A finished or healthy state. Never just "green because it is good news".
+ * @variant warning - Needs attention but is not broken. Partial data, an approaching limit.
+ * @variant danger - Failed, expired, or over a hard limit. Not merely "important".
+ * @variant ai - Generated or AI-assisted content, so the reader knows where it came from.
+ * @variant overlay - Sits on top of an image or video still, where no theme surface exists behind it.
+ * @use when you need to annotate something else -- a status on a row, a count
+ * on a filter tab, a category on a card, a flag over a thumbnail.
+ * @use when the label is a few words at most and the reader does not need to
+ * act on it.
+ * @avoid when the thing is clickable -- use Button, or a filter chip. A badge
+ * has no role, no focus state and no hit target, so making one clickable
+ * hides the action from keyboard and screen-reader users entirely.
+ * @avoid when the text is a sentence, or needs to wrap. A badge that wraps
+ * has become a callout; use one.
+ * @avoid when you are choosing the tone by colour rather than by meaning. A
+ * red badge that does not mean failure teaches readers to ignore red.
+ * @avoid when several sit in a row and all say something different -- that is
+ * a definition list wearing badges, and reads as noise.
+ * @usage
+ * ```tsx
+ * <Badge>Financial Services</Badge>
+ * <Badge tone="brand" kind="count">{selected.length}</Badge>
+ * <Badge tone="warning">Partial month</Badge>
+ * <Badge kind="eyebrow" tone="neutral">Saved view</Badge>
+ * <Badge tone="brand"><Check size={11} aria-hidden="true" />Primary</Badge>
+ * ```
+ */
+declare function Badge({ tone, kind, children, className }: BadgeProps): react.JSX.Element;
+
 /**
  * @pattern CheckBox
  * @description Tri-state checkbox rendered as a `<button>` (not a native
@@ -159,6 +238,13 @@ declare function AdvertiserSearchPrompt({ label }: AdvertiserSearchPromptProps):
  * `stopPropagation` before firing `onChange` by default, so nesting this
  * inside a row that toggles on its own click can't fire the toggle twice;
  * pass `stopPropagation={false}` where the row should also see the click.
+ * @a11y The <button> itself carries role="checkbox" and aria-checked ("mixed"
+ * when indeterminate), so it IS the control -- never nest it inside
+ * another button or a row that is itself clickable. `ariaLabel` is
+ * required because the box renders no text. Where the whole row should be
+ * the control, use CheckBoxBox inside your own <button role="checkbox">
+ * instead: a <button> inside a <button> is invalid markup, and a <div
+ * onClick> wrapper is not keyboard-reachable at all.
  * @usage
  * ```tsx
  * <CheckBox checked={selected} ariaLabel="Select row" onChange={toggle} />
@@ -221,6 +307,10 @@ declare function CheckBox({ checked, indeterminate, onChange, ariaLabel, disable
  * the control has no correct option: nesting the interactive `CheckBox`
  * produces a button inside a button, and dropping to a `<div>` with a click
  * handler loses keyboard access entirely.
+ * @a11y Presentational only: aria-hidden, no focus stop, no click handling. The
+ * ancestor owns role="checkbox", aria-checked, the accessible name and the
+ * click. Use it exactly when that ancestor is itself the control; use
+ * CheckBox when the box is the control.
  * @usage
  * ```tsx
  * <button type="button" role="checkbox" aria-checked={on} onClick={toggle}>
@@ -257,6 +347,9 @@ declare function CheckBoxBox({ checked, indeterminate, disabled, className }: Ch
  * values, so a previous unsaved edit never lingers into the next open. Only
  * the Apply button commits -- Cancel, Escape, and outside-click all discard
  * the draft silently.
+ * @a11y Trigger is a <button> with aria-expanded and an aria-label from the
+ * caption; the panel is role="dialog" and Escape closes it. Focus is not
+ * moved into the panel, so it is reached by tabbing.
  * @usage
  * ```tsx
  * <DateRangeFilter caption="Date Range" defaultValue="Rolling 6 months" onChange={setRange} />
@@ -327,6 +420,11 @@ declare function DateRangeFilter({ caption, defaultValue, value: controlledValue
  * The text input carries an `aria-label` derived from `placeholder` — the
  * wrapping `<label>` has no visible text content (just an icon and the
  * input), so it grants the input no accessible name on its own.
+ * @a11y The <input> takes its accessible name from `ariaLabel`. The match-mode
+ * popover is a radio group (role="radio" + aria-checked) and its trigger
+ * reports aria-expanded. Escape closes the popover only, leaving focus in
+ * the field -- a consumer nesting this inside another dismissible layer
+ * must sequence the two dismissals itself.
  * @usage
  * ```tsx
  * <SearchBar value={query} onChange={setQuery} />
@@ -390,6 +488,9 @@ declare function SearchBar({ placeholder, value, onChange, variant, matchValue,
  * anchor rather than a framework router Link — this package has no router
  * peer dependency, and the two consuming apps disagree on one (react-router-dom
  * vs next/link); a plain anchor is the one thing that works unmodified in both.
+ * @a11y Rail items are buttons and take their accessible name from `ariaLabel`,
+ * since several render icon-only. Without it they announce as unnamed
+ * buttons.
  * @usage
  * ```tsx
  * <SectionRail title="Sports" subtitle="Your tracked leagues" viewAllLabel="View all" viewAllHref="/sports">
@@ -432,6 +533,10 @@ declare function SectionRail({ title, titleSerif, subtitle, viewAllLabel, viewAl
  * invalid HTML that breaks click targeting (confirmed against how
  * mr-clientapps-insights-studio's own equivalent, `ChipOption`, already
  * avoids exactly this by rendering its InfoTip as a sibling, not a child).
+ * @a11y Trigger is a <button> with aria-expanded and aria-haspopup; the menu is
+ * role="listbox" with role="option" rows carrying aria-selected. Escape
+ * closes it. Use the listbox semantics as given -- adding a second role to
+ * the wrapper breaks the option/listbox relationship.
  * @usage
  * ```tsx
  * <DataScopeFilter value={finalOnly} onChange={setFinalOnly} />
@@ -467,6 +572,11 @@ declare function DataScopeFilter({ value, onChange, align }: DataScopeFilterProp
  * `onChange` ever fires, so nothing would ever get selected. Selecting an
  * option commits immediately and closes -- there's no separate draft/Apply
  * step; Escape and outside-click just close without side effects.
+ * @a11y Trigger is a <button>; the popover is role="listbox" with role="option"
+ * rows carrying aria-selected. The trigger owns the accessible name via
+ * the caption. The popover is not a focus trap and does not move focus on
+ * open, so keyboard users tab into it; a consumer rendering it inside
+ * another dismissible layer has to sequence the two dismissals itself.
  * @usage
  * ```tsx
  * <SelectFilter caption="Rank" value={rankFilter} onChange={setRankFilter} options={['All', 'VP / Director', 'Manager', 'Coordinator']} />
@@ -598,6 +708,10 @@ declare const QUIET_ACTION_CLASS = "rounded-control text-[13px] font-medium text
  * recovery buttons (e.g. "Switch workspace") after the two named ones, for
  * empty states whose fix isn't about filters at all -- primary gets the
  * filled treatment, everything else the quiet one.
+ * @a11y The optional action is a real <button> with visible text as its
+ * accessible name; the illustration is aria-hidden. Nothing here announces
+ * automatically, so a consumer replacing results should manage its own
+ * live region if the change needs announcing.
  * @usage
  * ```tsx
  * <NoResultsEmptyState hasFilters={hasFilters} onClearFilters={clearFilters} onEditFilters={openFilterTray} />
@@ -689,6 +803,8 @@ interface SummaryGroup {
  * increase, including one added to an already-open or already
  * manually-collapsed nonempty group, silently undoing the user's own
  * collapse. Sub-groups render indented beneath their parent's own items.
+ * @a11y The card's toggle is a button reporting aria-expanded, with an aria-
+ * label since it renders icon-only. Decorative marks are aria-hidden.
  * @usage
  * ```tsx
  * <WorkspaceSelectedCard groups={[{ id: 'advertisers', label: 'Advertisers', items: selected, onRemove: removeOne, onRemoveAll: clearAll }]} />
@@ -731,6 +847,9 @@ declare function WorkspaceSelectedCard({ groups, testIdPrefix }: WorkspaceSelect
  * `aria-hidden="true"` throughout, since none of the boxes carry real
  * content for assistive tech to announce. The bar count and profile are a
  * fixed shape, not driven by `height`.
+ * @a11y role="presentation" with aria-hidden marks: a visual stand-in with no
+ * data, deliberately invisible to assistive tech. Don't add a caption
+ * expecting it to be announced.
  * @usage
  * ```tsx
  * <BarChartPlaceholder />
@@ -756,6 +875,9 @@ declare function BarChartPlaceholder({ height }: BarChartPlaceholderProps): reac
  * @behavior Purely presentational -- `role="presentation"` and
  * `aria-hidden="true"` throughout (inherited from `AxisFrame`). The series
  * count and shapes are fixed; `height` is the only variable.
+ * @a11y role="presentation" with aria-hidden marks: a visual stand-in with no
+ * data, deliberately invisible to assistive tech. Don't add a caption
+ * expecting it to be announced.
  * @usage
  * ```tsx
  * <LineChartPlaceholder />
@@ -780,6 +902,9 @@ declare function LineChartPlaceholder({ height }: LineChartPlaceholderProps): re
  * @behavior Purely presentational -- `role="presentation"` and
  * `aria-hidden="true"` throughout. `legendRows` controls the blank legend
  * only; the disc's seam count is a fixed shape.
+ * @a11y role="presentation" with aria-hidden marks: it is a visual stand-in with
+ * no data, deliberately invisible to assistive tech. Don't add a caption
+ * expecting it to be announced.
  * @usage
  * ```tsx
  * <PieChartPlaceholder />
@@ -809,6 +934,8 @@ declare function PieChartPlaceholder({ height, legendRows }: PieChartPlaceholder
  * `bg-subtle` fill the default-strength seam disappears and the stack reads
  * as one undivided block. Legend rows are reversed (bottom-up) when `axis`
  * is off, matching a bare stack's usual bottom-anchored reading order.
+ * @a11y role="presentation" with aria-hidden marks: a visual stand-in with no
+ * data, deliberately invisible to assistive tech.
  * @usage
  * ```tsx
  * <StackedColumnPlaceholder />
@@ -858,6 +985,10 @@ declare function StackedColumnPlaceholder({ height, width, legendRows, axis, }:
  * right-aligned to the anchor's right edge -- both meant for `anchorRef`
  * anchors near the viewport's right edge, where a centred box would run
  * off-screen or read awkwardly beside a narrow icon.
+ * @a11y Renders role="tooltip" and is wired to its anchor by aria-describedby,
+ * so the anchor must exist and keep a stable id. It describes rather than
+ * labels: it is announced in addition to the anchor's own name, not
+ * instead of it, so never put the only label for a control in here.
  * @usage
  * ```tsx
  * <Tooltip label="Full advertiser name" whenTruncated>
@@ -959,6 +1090,10 @@ declare function AdvertiserNoResults({ query, hint, }: AdvertiserNoResultsProps)
  * between "Select all" and "Deselect" based on `allSelected`.
  * @tokens rounded-control, text-text-link, hover:bg-subtle
  * @dependencies lucide-react
+ * @a11y A plain <button>, not a checkbox -- it performs a bulk action rather
+ * than holding a checked state, so it deliberately carries no
+ * role="checkbox" or aria-checked. Its icon is aria-hidden and the visible
+ * text is the accessible name.
  * @usage
  * ```tsx
  * {results.length > 5 && (
@@ -992,6 +1127,9 @@ declare function SelectAllVisible({ count, allSelected, onToggle, testIdPrefix }
  * need. Self-hides at `count === 0` so a caller can render it unconditionally.
  * @tokens rounded-control, text-text-tertiary, hover:text-text-primary
  * @dependencies lucide-react
+ * @a11y The disclosure header is a button reporting aria-expanded, and the
+ * chevron is aria-hidden. It is a disclosure, not a selection control --
+ * the rows inside own their own semantics.
  * @usage
  * ```tsx
  * <SelectedSection count={selected.length} open={open} onToggle={() => setOpen((o) => !o)}>
@@ -1147,6 +1285,10 @@ interface SelectionPickerProps<T extends PickerRow> {
  * with both an `onChange` and the row's own `onClick` -- `CheckBox` stops
  * click propagation before firing `onChange`, which is exactly what lets it
  * sit inside a row that toggles on its own click without double-firing.
+ * @a11y Search is an <input>; result rows and the account-list menu
+ * (role="menu") are buttons. Escape closes the menu. Loading, empty and
+ * error states announce through role="status", so a consumer should NOT
+ * wrap this in its own live region -- that would double-announce.
  * @usage
  * ```tsx
  * <SelectionPicker
@@ -1234,6 +1376,9 @@ interface PublisherBreakdownListProps {
  * the kind of forked-with-extra-indirection outcome this package's README
  * calls out as not actually shared. Per that guidance, this component stays
  * the flat-list case only; mr-clientapps' accordion stays where it is, un-migrated.
+ * @a11y Rows are buttons. One row manages tabIndex directly and a row tooltip
+ * uses role="tooltip", dismissed on Escape. The tooltip describes rather
+ * than names, so never put a row's only label in it.
  * @usage
  * ```tsx
  * <PublisherBreakdownList rows={publishers} defaultVisibleCount={10} />
@@ -1242,7 +1387,7 @@ interface PublisherBreakdownListProps {
 declare function PublisherBreakdownList({ rows, defaultVisibleCount, padded, viewAllHref, renderLogo }: PublisherBreakdownListProps): react.JSX.Element;
 
 declare const buttonVariants: (props?: ({
-    variant?: "link" | "primary" | "secondary" | "ghost" | "danger" | null | undefined;
+    variant?: "link" | "danger" | "primary" | "secondary" | "ghost" | null | undefined;
     size?: "icon" | "sm" | "md" | "lg" | null | undefined;
 } & class_variance_authority_types.ClassProp) | undefined) => string;
 interface ButtonProps extends ButtonHTMLAttributes<HTMLButtonElement>, VariantProps<typeof buttonVariants> {
@@ -1275,6 +1420,9 @@ interface ButtonProps extends ButtonHTMLAttributes<HTMLButtonElement>, VariantPr
  * and relies on its per-variant hover/brightness treatment instead. `loading`
  * implies `disabled` (and sets `aria-busy`), since a control mid-submit
  * shouldn't accept another click.
+ * @a11y Renders a native <button>, so it keeps native keyboard behaviour.
+ * `loading` sets aria-busy, and the spinner is aria-hidden. Icon-only
+ * usage needs an aria-label from the caller -- nothing here supplies one.
  * @usage
  * ```tsx
  * <Button variant="primary" size="md">Save changes</Button>
@@ -1300,6 +1448,9 @@ interface FilterDropdownFooterProps {
  * visible. Shared by the Media/Advertiser/Date/Group By/Time Increment quick
  * filters on Sports Dashboard, Publisher Intel, and Opportunities.
  * @tokens border-border-default
+ * @a11y Clear and Apply are real Buttons with visible text as their accessible
+ * names, in that DOM order. It adds no roles or live regions of its own --
+ * the menu that contains it owns dismissal and focus.
  * @usage
  * ```tsx
  * <FilterDropdownFooter onApply={handleApply} onClear={handleClear} />
@@ -1343,12 +1494,16 @@ interface NameListModalProps {
  * checkboxes under it. Shared by the Account Lists table and the list detail
  * page so create/rename look identical; `fieldLabel`/`placeholder` relabel it
  * for dialogs that name something other than a list.
- * @tokens rounded-card, border-border-default, bg-surface, shadow-overlay, text-text-primary, text-text-secondary, rounded-control, bg-input, focus:border-brand-primaryAction
+ * @tokens bg-scrim, rounded-card, border-border-default, bg-surface, shadow-overlay, text-text-primary, text-text-secondary, rounded-control, bg-input, focus:border-brand-primaryAction
  * @behavior Escape closes the dialog via `onCancel`, same as clicking the
  * scrim backdrop. Submit is disabled until the name is non-empty (trimmed).
  * When `options` are given they render as CheckBox rows below the field, and
  * their state comes back as `onSubmit`'s second argument -- a handler that
  * only takes the name stays valid.
+ * @a11y role="dialog" with aria-modal, labelled by its title. The name field
+ * takes focus on open and Escape closes via onCancel. Focus is NOT trapped
+ * and NOT restored to the opener on close -- confirmed in the source -- so
+ * a consumer that needs either must supply it around this component.
  * @usage
  * ```tsx
  * <NameListModal title="Rename list" initialName={list.name} submitLabel="Save" onCancel={close} onSubmit={rename} />
@@ -1379,10 +1534,6 @@ interface ChipContentProps {
  * @description Shared foundation for filter-bar chip triggers — pairs
  * `chipTriggerClass` with `ChipContent` for the caption/value/icon layout, so
  * every dropdown chip across the app matches.
- * @props
- * caption: string -- small uppercase label above the value
- * value: ReactNode -- the current selection, shown below the caption
- * icon?: ReactNode -- optional leading icon rendered before the caption/value stack
  * @tokens rounded-control, bg-input, border-border-default, border-border-strong, text-text-secondary, text-text-tertiary, text-text-primary, hover:bg-subtle, focus-visible:outline-border-focus, hover:text-text-primary
  * @behavior `chipTriggerClass` takes a `ChipVariant`: `box` (default, the
  * boxed two-line chip on the default border) or `inline` (same fill, darker
@@ -1392,6 +1543,9 @@ interface ChipContentProps {
  * treatment every dropdown trigger depends on — open/close, Escape, and
  * outside-click dismissal all live in each consumer, not here. A new dropdown
  * built on `chipTriggerClass` has to implement its own dismissal handling.
+ * @a11y `chipTriggerClass` supplies only the shared focus-visible outline.
+ * Roles, aria-expanded and dismissal all belong to the consumer's own
+ * trigger -- this styles a control, it does not make one.
  * @usage
  * ```tsx
  * <button className={chipTriggerClass("box")}>
@@ -1429,6 +1583,9 @@ interface FilterChipBarProps<T extends ChipLike> {
  * @behavior A parked chip (key in `parkedKeys`) renders with no fill and a
  * dashed edge instead of the solid applied style, and its hover tooltip
  * reads "Not in this workspace" instead of the filter's group label.
+ * @a11y Each chip's remove control is a button with its own aria-label naming
+ * what it clears; the chip's icon is aria-hidden. An overflow tooltip uses
+ * role="tooltip", which describes rather than labels.
  * @usage
  * ```tsx
  * <FilterChipBar chips={activeChips} onRemove={removeChip} onClearAll={clearAll} />
@@ -1482,6 +1639,9 @@ interface SortButtonProps<K extends string> {
  * standard three-state cycle — sort, reverse, then unsorted. `disabled` keeps
  * the column's inherited header color rather than dimming it — the column
  * isn't unavailable, there's just no data under it.
+ * @a11y Renders a <button> and sets aria-sort on it. Intended for a table header
+ * cell -- put it inside the <th> rather than replacing it, so the sort
+ * state stays associated with the column for screen readers.
  * @usage
  * ```tsx
  * const [sort, setSort] = useState<SortState<'spend'>>(null)
@@ -1503,6 +1663,9 @@ interface PagerProps {
  * ellipsis gaps. Shared by My Exports and Account Matcher.
  * @tokens rounded-control, text-text-secondary, bg-brand-primaryAction, text-brand-onprimary, hover:bg-subtle, hover:text-text-primary, text-text-tertiary
  * @dependencies lucide-react
+ * @a11y Page controls are buttons with their own aria-labels, and the current
+ * page is marked with aria-current. Don't relabel them with visible text
+ * alone -- the labels are what a screen reader announces.
  * @usage
  * ```tsx
  * <Pager page={page} totalPages={totalPages} onPage={setPage} />
@@ -1571,6 +1734,10 @@ declare function Tag({ children, className }: TagProps): react.JSX.Element;
  * Changing the per-page count reports it and leaves the host to reset to page
  * 1. With one page of results the pager still renders, so the bar's height
  * and the range readout don't come and go as filters narrow.
+ * @a11y A <nav aria-label="Pagination"> wrapping <button> controls, each with
+ * its own aria-label (Previous/Next/Last). The chevron icons are aria-
+ * hidden, so the labels are the only accessible names -- don't override
+ * them with visible text alone.
  * @usage
  * ```tsx
  * <TablePagination
@@ -1655,6 +1822,10 @@ interface MultiSelectGroup {
  * selection floor by silently ignoring any toggle that would drop below it —
  * there's no error state, the click just does nothing. Group parents are
  * tri-state and toggle all of their children in one action.
+ * @a11y Trigger is a <button> with aria-expanded; the menu is role="dialog" and
+ * Escape closes it. Option rows carry their own checkbox semantics. Focus
+ * is not moved into the menu on open, so keyboard users tab into it in DOM
+ * order.
  * @usage
  * ```tsx
  * <MultiSelectFilter caption="Media" options={mediaOptions} selected={selected} onChange={setSelected} />
@@ -1755,6 +1926,10 @@ interface ToggleProps {
  * need (usually label left, switch pushed right).
  * @variant md - Settings panels and modals, where the switch is the row's subject.
  * @variant sm - Dense rows next to 13px body text, where the md track overpowers its own label.
+ * @a11y The <button> carries role="switch" and aria-checked, so it is the
+ * control -- don't nest it in another interactive element. `label`
+ * supplies the accessible name; without it the switch is announced
+ * unlabelled.
  * @usage
  * ```tsx
  * <Toggle checked={enabled} onChange={setEnabled} label="Email news alerts" />
@@ -1790,6 +1965,9 @@ interface FreshnessProps {
  * timestamps stops reading as a wall of identical text. Color carries the
  * urgency signal at a glance.
  * @tokens bg-status-success, bg-status-warning, bg-text-tertiary
+ * @a11y role="img" with an aria-label per level, so the dot has a text
+ * alternative rather than announcing as decoration. The label is the only
+ * thing a screen reader gets -- the colour carries no meaning on its own.
  * @usage
  * ```tsx
  * <Freshness level="fresh" />
@@ -1797,4 +1975,4 @@ interface FreshnessProps {
  */
 declare function Freshness({ level }: FreshnessProps): react.JSX.Element;
 
-export { AISpark, type AISparkProps, AdvertiserNoResults, type AdvertiserNoResultsProps, AdvertiserQuickFilter, type AdvertiserQuickFilterProps, AdvertiserSearchPrompt, type AdvertiserSearchPromptProps, BarChartPlaceholder, type BarChartPlaceholderProps, Button, type ButtonProps, Card, type CardProps, CheckBox, CheckBoxBox, type CheckBoxBoxProps, type CheckBoxProps, ChipContent, type ChipContentProps, type ChipVariant, DEFAULT_SEARCH_MATCH, DataScopeFilter, type DataScopeFilterProps, type DateGranularity, DateRangeFilter, type DateRangeFilterProps, DateRangePicker, type DateRangePickerProps, FilterChipBar, type FilterChipBarProps, FilterDropdownFooter, type FilterDropdownFooterProps, Freshness, type FreshnessLevel, type FreshnessProps, InfoTip, type InfoTipProps, LineChartPlaceholder, type LineChartPlaceholderProps, MultiSelectFilter, type MultiSelectFilterProps, type MultiSelectGroup, NO_RESULTS_BODY, NO_RESULTS_TITLE, NameListModal, type NameListModalProps, type NoResultsAction, NoResultsEmptyState, type NoResultsEmptyStateProps, PRIMARY_ACTION_CLASS, Pager, type PagerProps, type PickerColumn, type PickerFilter, type PickerRow, PieChartPlaceholder, type PieChartPlaceholderProps, type PubBreak, PublisherBreakdownList, type PublisherBreakdownListProps, QUIET_ACTION_CLASS, SearchBar, type SearchBarProps, type SearchBarVariant, type SearchMatchMode, type SearchMatchValue, SectionRail, type SectionRailProps, SelectAllVisible, type SelectAllVisibleProps, SelectFilter, type SelectFilterProps, SelectedSection, type SelectedSectionProps, SelectionPicker, type SelectionPickerAccountList, type SelectionPickerProps, SortButton, type SortButtonProps, type SortDir, type SortState, StackedColumnPlaceholder, type StackedColumnPlaceholderProps, type SummaryGroup, type SummaryGroupItemValue, TablePagination, type TablePaginationProps, Tag, type TagProps, Toggle, type ToggleProps, Tooltip, type TooltipProps, WorkspaceAvatar, type WorkspaceAvatarProps, WorkspaceSelectedCard, type WorkspaceSelectedCardProps, buttonVariants, chipTriggerClass, cycleSort, noResultsBody, resolveRange, sortProp };
+export { AISpark, type AISparkProps, AdvertiserNoResults, type AdvertiserNoResultsProps, AdvertiserQuickFilter, type AdvertiserQuickFilterProps, AdvertiserSearchPrompt, type AdvertiserSearchPromptProps, Badge, type BadgeKind, type BadgeProps, type BadgeTone, BarChartPlaceholder, type BarChartPlaceholderProps, Button, type ButtonProps, Card, type CardProps, CheckBox, CheckBoxBox, type CheckBoxBoxProps, type CheckBoxProps, ChipContent, type ChipContentProps, type ChipVariant, DEFAULT_SEARCH_MATCH, DataScopeFilter, type DataScopeFilterProps, type DateGranularity, DateRangeFilter, type DateRangeFilterProps, DateRangePicker, type DateRangePickerProps, FilterChipBar, type FilterChipBarProps, FilterDropdownFooter, type FilterDropdownFooterProps, Freshness, type FreshnessLevel, type FreshnessProps, InfoTip, type InfoTipProps, LineChartPlaceholder, type LineChartPlaceholderProps, MultiSelectFilter, type MultiSelectFilterProps, type MultiSelectGroup, NO_RESULTS_BODY, NO_RESULTS_TITLE, NameListModal, type NameListModalProps, type NoResultsAction, NoResultsEmptyState, type NoResultsEmptyStateProps, PRIMARY_ACTION_CLASS, Pager, type PagerProps, type PickerColumn, type PickerFilter, type PickerRow, PieChartPlaceholder, type PieChartPlaceholderProps, type PubBreak, PublisherBreakdownList, type PublisherBreakdownListProps, QUIET_ACTION_CLASS, SearchBar, type SearchBarProps, type SearchBarVariant, type SearchMatchMode, type SearchMatchValue, SectionRail, type SectionRailProps, SelectAllVisible, type SelectAllVisibleProps, SelectFilter, type SelectFilterProps, SelectedSection, type SelectedSectionProps, SelectionPicker, type SelectionPickerAccountList, type SelectionPickerProps, SortButton, type SortButtonProps, type SortDir, type SortState, StackedColumnPlaceholder, type StackedColumnPlaceholderProps, type SummaryGroup, type SummaryGroupItemValue, TablePagination, type TablePaginationProps, Tag, type TagProps, Toggle, type ToggleProps, Tooltip, type TooltipProps, WorkspaceAvatar, type WorkspaceAvatarProps, WorkspaceSelectedCard, type WorkspaceSelectedCardProps, buttonVariants, chipTriggerClass, cycleSort, noResultsBody, resolveRange, sortProp };