@mediaradar/design-components 0.15.0 → 0.16.1

package/dist/index.d.cts

@@ -229,6 +229,60 @@ interface BadgeProps {
  */
 declare function Badge({ tone, kind, dot, children, className }: BadgeProps): react.JSX.Element;
 
+interface DeltaProps {
+    /** The change itself. Its sign picks the direction; render the absolute value. */
+    value: number;
+    /** What the number is in -- "%" for a percentage, "pts" for share points. */
+    suffix?: string;
+    /**
+     * Adds a direction arrow before the number. For a column of deltas scanned
+     * rather than read, where the arrow is what the eye follows. A single delta
+     * beside a figure does not need one -- the sign already says which way.
+     */
+    arrow?: boolean;
+    /** Appended after the suffix, e.g. "YoY". Keep it to one or two words. */
+    period?: string;
+    className?: string;
+}
+/**
+ * @pattern Delta
+ * @description A change over time -- the +6.2% / -2.1% beside a figure. Green
+ * up, red down, always with an explicit sign.
+ * @props
+ * value: number -- sign picks the direction
+ * suffix?: string -- "%" or "pts"
+ * arrow?: boolean (default false) -- direction arrow, for a column scanned rather than read
+ * period?: string -- e.g. "YoY"
+ * @tokens text-text-success, text-text-danger
+ * @dependencies lucide-react
+ * @behavior Takes the type size of whatever contains it rather than setting
+ * its own, because it is inline text inside a table cell or a card rather
+ * than a box of its own -- a fixed size would fight the density its table
+ * already chose.
+ * @a11y The sign is the point: colour alone cannot carry direction, for
+ * anyone who cannot distinguish the two and for anyone reading it printed or
+ * in greyscale. `+` and `-` are always rendered, so the colour is
+ * reinforcement rather than the only signal. The arrow is decorative and
+ * hidden, since the sign beside it already says the same thing.
+ * @use when showing a change against a previous period beside the figure it
+ * relates to.
+ * @use with `arrow` when deltas run down a column and the reader is scanning
+ * for the ones that moved.
+ * @avoid when the number is not a change -- a share, a total or a rate is
+ * just a number, and colouring it green or red tells the reader something
+ * untrue about it.
+ * @avoid when up is not good. Green-for-up reads as green-for-better, so a
+ * rising cost or a rising error rate needs its own treatment rather than this
+ * one inverted, which nobody will notice.
+ * @usage
+ * ```tsx
+ * <Delta value={6.2} suffix="%" />
+ * <Delta value={-2.1} suffix="%" period="YoY" />
+ * <Delta value={1.4} suffix="pts" arrow />
+ * ```
+ */
+declare function Delta({ value, suffix, arrow, period, className }: DeltaProps): react.JSX.Element;
+
 /**
  * @pattern CheckBox
  * @description Tri-state checkbox rendered as a `<button>` (not a native
@@ -882,7 +936,9 @@ declare function BarChartPlaceholder({ height }: BarChartPlaceholderProps): reac
  * the card, and a stretched `<circle>` would go oval. Same no-results use
  * as `BarChartPlaceholder` -- no real value ever appears, and the shape
  * holds the card's layout steady so nothing jumps when real data arrives.
- * @tokens border-border-strong, bg-subtle, border-border-default, rounded-xs
+ * Paths and points share the `bg-subtle` fill of the axis labels, so the
+ * whole placeholder reads as one tint, the way the bars do.
+ * @tokens bg-subtle, border-border-default, rounded-xs
  * @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.
@@ -909,10 +965,11 @@ declare function LineChartPlaceholder({ height }: LineChartPlaceholderProps): re
  * `BarChartPlaceholder`: an unsatisfiable filter reads as "a chart belongs
  * here" rather than a failed load, with no real value (names, media types,
  * dollar amounts, percentages, series colors) ever appearing.
- * @tokens bg-subtle, border-border-default, rounded-xs
+ * @tokens bg-subtle, bg-surface, rounded-xs
  * @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.
+ * only; the disc's seam count is a fixed shape. Seams are cut in the
+ * card's `bg-surface` color, as `StackedColumnPlaceholder`'s bands are.
  * @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.
@@ -938,12 +995,12 @@ declare function PieChartPlaceholder({ height, legendRows }: PieChartPlaceholder
  * `axis`, a bare stack with no scale (e.g. a share-of-voice column) omits
  * it. Same no-results use as `BarChartPlaceholder` -- no real value ever
  * appears, and the shape holds the card's layout steady.
- * @tokens bg-subtle, border-border-strong, border-border-default, rounded-control
+ * @tokens bg-subtle, bg-surface, border-border-default, rounded-control
  * @behavior Purely presentational -- `role="presentation"` and
- * `aria-hidden="true"` throughout. Band seams use `border-border-strong`
- * rather than the softer `border-border-default` gridline color: on a
- * `bg-subtle` fill the default-strength seam disappears and the stack reads
- * as one undivided block. Legend rows are reversed (bottom-up) when `axis`
+ * `aria-hidden="true"` throughout. Band seams are 1px gaps in the card's
+ * `bg-surface` color rather than a border tone: a `border-border-default`
+ * seam disappears on the `bg-subtle` fill, and `border-border-strong` reads
+ * darker than the rest of the placeholder. 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.
@@ -1409,8 +1466,9 @@ interface PublisherBreakdownListProps {
 declare function PublisherBreakdownList({ rows, defaultVisibleCount, padded, viewAllHref, renderLogo }: PublisherBreakdownListProps): react.JSX.Element;
 
 declare const buttonVariants: (props?: ({
-    variant?: "link" | "danger" | "primary" | "secondary" | "ghost" | null | undefined;
-    size?: "icon" | "sm" | "md" | "lg" | null | undefined;
+    variant?: "link" | "danger" | "primary" | "secondary" | "ghost" | "dangerGhost" | null | undefined;
+    size?: "xs" | "sm" | "md" | null | undefined;
+    iconOnly?: boolean | null | undefined;
 } & class_variance_authority_types.ClassProp) | undefined) => string;
 interface ButtonProps extends ButtonHTMLAttributes<HTMLButtonElement>, VariantProps<typeof buttonVariants> {
     /**
@@ -1433,18 +1491,21 @@ interface ButtonProps extends ButtonHTMLAttributes<HTMLButtonElement>, VariantPr
 }
 /**
  * @pattern Button
- * @description Primary interactive control for actions. Five visual variants
- * (primary, secondary, ghost, danger, link) and four sizes (sm, md, lg, icon).
+ * @description The one control for every clickable action, from the main call
+ * to action on a screen down to a quiet toolbar utility. Six variants
+ * (primary, secondary, ghost, danger, dangerGhost, link) across three sizes
+ * (xs, sm, md), labelled or icon-only.
  * Supports polymorphic rendering via `asChild` (Radix Slot) to apply button
  * styling to a different element, e.g. a router `<Link>`. Also exports the
  * raw `buttonVariants` cva function for consumers composing button styling
  * onto something other than this component.
- * @tokens bg-brand-primaryAction, text-brand-onprimary, bg-surface, text-text-primary, border-border-interactive, hover:bg-subtle, bg-status-danger, text-status-onstatus, text-text-link, rounded-control, duration-(--mr-motion-duration-interactive), ease-interactive
+ * @tokens bg-brand-primaryAction, text-brand-onprimary, bg-surface, text-text-primary, border-border-strong, hover:border-border-interactive, hover:bg-subtle, bg-status-danger, text-status-onstatus, text-text-secondary, hover:text-text-danger, text-text-link, rounded-control, duration-(--mr-motion-duration-interactive), ease-interactive
  * @dependencies class-variance-authority, @radix-ui/react-slot, lucide-react
  * @variant primary - The one primary action on a screen. Solid brand fill.
  * @variant secondary - Any other real action competing for attention (Cancel, Export). Bordered, neutral fill.
  * @variant ghost - Low-emphasis action inside a dense toolbar or row where a border would add visual noise.
- * @variant danger - Destructive/irreversible actions (Delete, Remove). Never pair with `primary` in the same control group.
+ * @variant danger - Filled red. Only for a confirmed destructive action, typically the confirm button in a dialog. Never pair with `primary` in the same control group.
+ * @variant dangerGhost - Neutral at rest, red on hover. For a destructive affordance inline in a row or toolbar -- what the product reaches for far more often than filled danger.
  * @variant link - Reads as inline text, not a control. Use inside body copy or where a full button would overpower the surrounding content.
  * @behavior `disabled` removes pointer events entirely (not just a style
  * change) and dims to 40% opacity. Focus handling is a deliberate exception:
@@ -1461,9 +1522,29 @@ interface ButtonProps extends ButtonHTMLAttributes<HTMLButtonElement>, VariantPr
  * (with `asChild`, the child element's own semantics apply instead).
  * `loading` sets aria-busy, and the spinner is aria-hidden. Icon-only
  * usage needs an aria-label from the caller -- nothing here supplies one.
+ * @use when the user is triggering an action in place -- saving, applying,
+ * confirming, opening a dialog, running an export.
+ * @use when you need a destructive affordance: dangerGhost inline in a row or
+ * toolbar, danger only as the confirm button in a dialog already opened.
+ * @use when an action sits inside a sentence -- variant="link", which drops
+ * the box and the semibold weight so it does not read as emphasis.
+ * @use when the action is icon-only in a dense toolbar -- iconOnly squares the
+ * box at whichever size you picked, so it lines up with labelled buttons
+ * beside it. Supply an aria-label; nothing here does.
+ * @avoid when the control navigates to a different route -- render a real link
+ * via asChild, so middle-click, right-click and open-in-new-tab keep working.
+ * variant="link" styles a button as text; it does not make a button a link.
+ * @avoid when there is already a primary on the screen -- a second primary
+ * means neither reads as the main action. Use secondary or ghost.
+ * @avoid when the control toggles a persistent on/off state -- use CheckBox or
+ * a switch. A button fires; it does not hold a state.
+ * @avoid when you are about to hand-roll a button with raw classes. There is
+ * no case this does not cover, and every copy is a divergence in hover, focus,
+ * disabled and loading behaviour at once.
  * @usage
  * ```tsx
  * <Button variant="primary" size="md">Save changes</Button>
+ * <Button variant="dangerGhost" size="sm" iconOnly aria-label="Remove row"><X size={15} /></Button>
  * <Button variant="secondary" size="sm">Cancel</Button>
  * <Button variant="danger">Delete</Button>
  * <Button variant="primary" loading>Saving…</Button>
@@ -1748,11 +1829,24 @@ interface TagProps {
 }
 /**
  * @pattern Tag
- * @description Canonical descriptive tag — a neutral beige chip (e.g.
- * "Digital", a focus area, a category). Use this for every non-semantic
- * label so tags read the same everywhere. Colored/semantic badges (NEW, ±%
- * deltas, status, counts) are intentionally NOT this component.
- * @tokens bg-subtle, text-text-secondary, rounded-full
+ * @description Canonical descriptive tag -- a neutral chip naming what a
+ * thing IS: a category, a media type, a focus area. Always neutral, never
+ * semantic, never removable.
+ *
+ * The product separates three jobs that most systems collapse into one, by
+ * who authored the label. Badge is the system's view of a thing (status,
+ * count, AI-generated) and its colour means something. Tag is the thing
+ * describing itself, and stays neutral. FilterChipBar is the user describing
+ * what they want to see, and is the only one you can remove.
+ * @use when labelling what something is -- a category, a media type, a focus
+ * area, a property of the row rather than a judgement about it.
+ * @avoid when the colour would mean something. A status, a count, an
+ * AI marker or anything the system decided is a Badge.
+ * @avoid when the user should be able to dismiss it. An applied filter is a
+ * FilterChipBar chip, which belongs to the filter bar rather than to the row.
+ * @avoid when there are more than a handful in a row. Tags are scanned, and a
+ * dozen neutral chips read as texture rather than as information.
+ * @tokens text-micro, bg-subtle, text-text-tertiary, rounded-full
  * @usage
  * ```tsx
  * <Tag>Digital</Tag>
@@ -2014,4 +2108,4 @@ interface FreshnessProps {
  */
 declare function Freshness({ level }: FreshnessProps): react.JSX.Element;
 
-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 };
+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, Delta, type DeltaProps, 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 };

package/dist/index.d.ts

@@ -229,6 +229,60 @@ interface BadgeProps {
  */
 declare function Badge({ tone, kind, dot, children, className }: BadgeProps): react.JSX.Element;
 
+interface DeltaProps {
+    /** The change itself. Its sign picks the direction; render the absolute value. */
+    value: number;
+    /** What the number is in -- "%" for a percentage, "pts" for share points. */
+    suffix?: string;
+    /**
+     * Adds a direction arrow before the number. For a column of deltas scanned
+     * rather than read, where the arrow is what the eye follows. A single delta
+     * beside a figure does not need one -- the sign already says which way.
+     */
+    arrow?: boolean;
+    /** Appended after the suffix, e.g. "YoY". Keep it to one or two words. */
+    period?: string;
+    className?: string;
+}
+/**
+ * @pattern Delta
+ * @description A change over time -- the +6.2% / -2.1% beside a figure. Green
+ * up, red down, always with an explicit sign.
+ * @props
+ * value: number -- sign picks the direction
+ * suffix?: string -- "%" or "pts"
+ * arrow?: boolean (default false) -- direction arrow, for a column scanned rather than read
+ * period?: string -- e.g. "YoY"
+ * @tokens text-text-success, text-text-danger
+ * @dependencies lucide-react
+ * @behavior Takes the type size of whatever contains it rather than setting
+ * its own, because it is inline text inside a table cell or a card rather
+ * than a box of its own -- a fixed size would fight the density its table
+ * already chose.
+ * @a11y The sign is the point: colour alone cannot carry direction, for
+ * anyone who cannot distinguish the two and for anyone reading it printed or
+ * in greyscale. `+` and `-` are always rendered, so the colour is
+ * reinforcement rather than the only signal. The arrow is decorative and
+ * hidden, since the sign beside it already says the same thing.
+ * @use when showing a change against a previous period beside the figure it
+ * relates to.
+ * @use with `arrow` when deltas run down a column and the reader is scanning
+ * for the ones that moved.
+ * @avoid when the number is not a change -- a share, a total or a rate is
+ * just a number, and colouring it green or red tells the reader something
+ * untrue about it.
+ * @avoid when up is not good. Green-for-up reads as green-for-better, so a
+ * rising cost or a rising error rate needs its own treatment rather than this
+ * one inverted, which nobody will notice.
+ * @usage
+ * ```tsx
+ * <Delta value={6.2} suffix="%" />
+ * <Delta value={-2.1} suffix="%" period="YoY" />
+ * <Delta value={1.4} suffix="pts" arrow />
+ * ```
+ */
+declare function Delta({ value, suffix, arrow, period, className }: DeltaProps): react.JSX.Element;
+
 /**
  * @pattern CheckBox
  * @description Tri-state checkbox rendered as a `<button>` (not a native
@@ -882,7 +936,9 @@ declare function BarChartPlaceholder({ height }: BarChartPlaceholderProps): reac
  * the card, and a stretched `<circle>` would go oval. Same no-results use
  * as `BarChartPlaceholder` -- no real value ever appears, and the shape
  * holds the card's layout steady so nothing jumps when real data arrives.
- * @tokens border-border-strong, bg-subtle, border-border-default, rounded-xs
+ * Paths and points share the `bg-subtle` fill of the axis labels, so the
+ * whole placeholder reads as one tint, the way the bars do.
+ * @tokens bg-subtle, border-border-default, rounded-xs
  * @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.
@@ -909,10 +965,11 @@ declare function LineChartPlaceholder({ height }: LineChartPlaceholderProps): re
  * `BarChartPlaceholder`: an unsatisfiable filter reads as "a chart belongs
  * here" rather than a failed load, with no real value (names, media types,
  * dollar amounts, percentages, series colors) ever appearing.
- * @tokens bg-subtle, border-border-default, rounded-xs
+ * @tokens bg-subtle, bg-surface, rounded-xs
  * @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.
+ * only; the disc's seam count is a fixed shape. Seams are cut in the
+ * card's `bg-surface` color, as `StackedColumnPlaceholder`'s bands are.
  * @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.
@@ -938,12 +995,12 @@ declare function PieChartPlaceholder({ height, legendRows }: PieChartPlaceholder
  * `axis`, a bare stack with no scale (e.g. a share-of-voice column) omits
  * it. Same no-results use as `BarChartPlaceholder` -- no real value ever
  * appears, and the shape holds the card's layout steady.
- * @tokens bg-subtle, border-border-strong, border-border-default, rounded-control
+ * @tokens bg-subtle, bg-surface, border-border-default, rounded-control
  * @behavior Purely presentational -- `role="presentation"` and
- * `aria-hidden="true"` throughout. Band seams use `border-border-strong`
- * rather than the softer `border-border-default` gridline color: on a
- * `bg-subtle` fill the default-strength seam disappears and the stack reads
- * as one undivided block. Legend rows are reversed (bottom-up) when `axis`
+ * `aria-hidden="true"` throughout. Band seams are 1px gaps in the card's
+ * `bg-surface` color rather than a border tone: a `border-border-default`
+ * seam disappears on the `bg-subtle` fill, and `border-border-strong` reads
+ * darker than the rest of the placeholder. 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.
@@ -1409,8 +1466,9 @@ interface PublisherBreakdownListProps {
 declare function PublisherBreakdownList({ rows, defaultVisibleCount, padded, viewAllHref, renderLogo }: PublisherBreakdownListProps): react.JSX.Element;
 
 declare const buttonVariants: (props?: ({
-    variant?: "link" | "danger" | "primary" | "secondary" | "ghost" | null | undefined;
-    size?: "icon" | "sm" | "md" | "lg" | null | undefined;
+    variant?: "link" | "danger" | "primary" | "secondary" | "ghost" | "dangerGhost" | null | undefined;
+    size?: "xs" | "sm" | "md" | null | undefined;
+    iconOnly?: boolean | null | undefined;
 } & class_variance_authority_types.ClassProp) | undefined) => string;
 interface ButtonProps extends ButtonHTMLAttributes<HTMLButtonElement>, VariantProps<typeof buttonVariants> {
     /**
@@ -1433,18 +1491,21 @@ interface ButtonProps extends ButtonHTMLAttributes<HTMLButtonElement>, VariantPr
 }
 /**
  * @pattern Button
- * @description Primary interactive control for actions. Five visual variants
- * (primary, secondary, ghost, danger, link) and four sizes (sm, md, lg, icon).
+ * @description The one control for every clickable action, from the main call
+ * to action on a screen down to a quiet toolbar utility. Six variants
+ * (primary, secondary, ghost, danger, dangerGhost, link) across three sizes
+ * (xs, sm, md), labelled or icon-only.
  * Supports polymorphic rendering via `asChild` (Radix Slot) to apply button
  * styling to a different element, e.g. a router `<Link>`. Also exports the
  * raw `buttonVariants` cva function for consumers composing button styling
  * onto something other than this component.
- * @tokens bg-brand-primaryAction, text-brand-onprimary, bg-surface, text-text-primary, border-border-interactive, hover:bg-subtle, bg-status-danger, text-status-onstatus, text-text-link, rounded-control, duration-(--mr-motion-duration-interactive), ease-interactive
+ * @tokens bg-brand-primaryAction, text-brand-onprimary, bg-surface, text-text-primary, border-border-strong, hover:border-border-interactive, hover:bg-subtle, bg-status-danger, text-status-onstatus, text-text-secondary, hover:text-text-danger, text-text-link, rounded-control, duration-(--mr-motion-duration-interactive), ease-interactive
  * @dependencies class-variance-authority, @radix-ui/react-slot, lucide-react
  * @variant primary - The one primary action on a screen. Solid brand fill.
  * @variant secondary - Any other real action competing for attention (Cancel, Export). Bordered, neutral fill.
  * @variant ghost - Low-emphasis action inside a dense toolbar or row where a border would add visual noise.
- * @variant danger - Destructive/irreversible actions (Delete, Remove). Never pair with `primary` in the same control group.
+ * @variant danger - Filled red. Only for a confirmed destructive action, typically the confirm button in a dialog. Never pair with `primary` in the same control group.
+ * @variant dangerGhost - Neutral at rest, red on hover. For a destructive affordance inline in a row or toolbar -- what the product reaches for far more often than filled danger.
  * @variant link - Reads as inline text, not a control. Use inside body copy or where a full button would overpower the surrounding content.
  * @behavior `disabled` removes pointer events entirely (not just a style
  * change) and dims to 40% opacity. Focus handling is a deliberate exception:
@@ -1461,9 +1522,29 @@ interface ButtonProps extends ButtonHTMLAttributes<HTMLButtonElement>, VariantPr
  * (with `asChild`, the child element's own semantics apply instead).
  * `loading` sets aria-busy, and the spinner is aria-hidden. Icon-only
  * usage needs an aria-label from the caller -- nothing here supplies one.
+ * @use when the user is triggering an action in place -- saving, applying,
+ * confirming, opening a dialog, running an export.
+ * @use when you need a destructive affordance: dangerGhost inline in a row or
+ * toolbar, danger only as the confirm button in a dialog already opened.
+ * @use when an action sits inside a sentence -- variant="link", which drops
+ * the box and the semibold weight so it does not read as emphasis.
+ * @use when the action is icon-only in a dense toolbar -- iconOnly squares the
+ * box at whichever size you picked, so it lines up with labelled buttons
+ * beside it. Supply an aria-label; nothing here does.
+ * @avoid when the control navigates to a different route -- render a real link
+ * via asChild, so middle-click, right-click and open-in-new-tab keep working.
+ * variant="link" styles a button as text; it does not make a button a link.
+ * @avoid when there is already a primary on the screen -- a second primary
+ * means neither reads as the main action. Use secondary or ghost.
+ * @avoid when the control toggles a persistent on/off state -- use CheckBox or
+ * a switch. A button fires; it does not hold a state.
+ * @avoid when you are about to hand-roll a button with raw classes. There is
+ * no case this does not cover, and every copy is a divergence in hover, focus,
+ * disabled and loading behaviour at once.
  * @usage
  * ```tsx
  * <Button variant="primary" size="md">Save changes</Button>
+ * <Button variant="dangerGhost" size="sm" iconOnly aria-label="Remove row"><X size={15} /></Button>
  * <Button variant="secondary" size="sm">Cancel</Button>
  * <Button variant="danger">Delete</Button>
  * <Button variant="primary" loading>Saving…</Button>
@@ -1748,11 +1829,24 @@ interface TagProps {
 }
 /**
  * @pattern Tag
- * @description Canonical descriptive tag — a neutral beige chip (e.g.
- * "Digital", a focus area, a category). Use this for every non-semantic
- * label so tags read the same everywhere. Colored/semantic badges (NEW, ±%
- * deltas, status, counts) are intentionally NOT this component.
- * @tokens bg-subtle, text-text-secondary, rounded-full
+ * @description Canonical descriptive tag -- a neutral chip naming what a
+ * thing IS: a category, a media type, a focus area. Always neutral, never
+ * semantic, never removable.
+ *
+ * The product separates three jobs that most systems collapse into one, by
+ * who authored the label. Badge is the system's view of a thing (status,
+ * count, AI-generated) and its colour means something. Tag is the thing
+ * describing itself, and stays neutral. FilterChipBar is the user describing
+ * what they want to see, and is the only one you can remove.
+ * @use when labelling what something is -- a category, a media type, a focus
+ * area, a property of the row rather than a judgement about it.
+ * @avoid when the colour would mean something. A status, a count, an
+ * AI marker or anything the system decided is a Badge.
+ * @avoid when the user should be able to dismiss it. An applied filter is a
+ * FilterChipBar chip, which belongs to the filter bar rather than to the row.
+ * @avoid when there are more than a handful in a row. Tags are scanned, and a
+ * dozen neutral chips read as texture rather than as information.
+ * @tokens text-micro, bg-subtle, text-text-tertiary, rounded-full
  * @usage
  * ```tsx
  * <Tag>Digital</Tag>
@@ -2014,4 +2108,4 @@ interface FreshnessProps {
  */
 declare function Freshness({ level }: FreshnessProps): react.JSX.Element;
 
-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 };
+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, Delta, type DeltaProps, 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 };