@momentum-design/components 0.134.19 → 0.134.21

package/dist/components/badge/badge.component.d.ts

@@ -3,27 +3,23 @@ import { Component } from '../../models';
 import type { BadgeType, IconVariant } from './badge.types';
 declare const Badge_base: import("../../utils/mixins/index.types").Constructor<import("../../utils/mixins/IconNameMixin").IconNameMixinInterface> & typeof Component;
 /**
- * The `mdc-badge` component is a versatile UI element used to
- * display dot, icons, counters, success, warning and error type badge.
- *
- * Supported badge types:
- * - `dot`: Displays a dot notification badge with a blue color.
- * - `icon`: Displays a badge with a specified icon using the `icon-name` attribute.
- * - `counter`: Displays a badge with a counter value. If the counter exceeds the `max-counter`,
- * it shows `maxCounter+`. The maximum value of the counter is 999 and anything above that will be set to `999+`.
- * - `success`: Displays a success badge with a check circle icon and green color.
- * - `warning`: Displays a warning badge with a warning icon and yellow color.
- * - `error`: Displays a error badge with a error legacy icon and red color.
- *
- * For `icon`, `success`, `warning` and `error` types, the `mdc-icon` component is used to render the icon.
- *
- * For the `counter` type, the `mdc-text` component is used to render the counter value.
- *
+ * The badge is a small, non-interactive indicator used to surface a notification, status, or count. It supports six types — `dot`, `icon`, `counter`, `success`, `warning`, and `error` — and can be layered on top of other UI (for example a button) with an optional outline overlay.
+ * 
+ * **When to use**
+ * 
+ * - Use `mdc-badge` to show an unread/notification dot, a numeric counter, or a status indicator next to or on top of another element.
+ * 
+ * **When not to use**
+ * 
+ * - Use `mdc-alertchip` when the indicator must be interactive (focusable, clickable) and behave as a button.
+ * - Use `mdc-staticchip` or `mdc-text` when the status needs richer label content rather than a single icon, dot, or count.
+ * - Use `mdc-presence` when you specifically need to indicate a user's activity/availability state (e.g. active, away, busy, dnd) rather than a generic notification, count, or status.
+ * 
+ * @tagname mdc-badge
+ * 
  * @dependency mdc-icon
  * @dependency mdc-text
- *
- * @tagname mdc-badge
- *
+ * 
  * @cssproperty --mdc-badge-primary-foreground-color - The foreground color of the primary badge.
  * @cssproperty --mdc-badge-primary-background-color - The background color of the primary badge.
  * @cssproperty --mdc-badge-secondary-foreground-color - The foreground color of the secondary badge.
@@ -37,7 +33,7 @@ declare const Badge_base: import("../../utils/mixins/index.types").Constructor<i
  * @cssproperty --mdc-badge-overlay-background-color - The background color of the badge overlay.
  * @cssproperty --mdc-badge-dot-width - The width of the dot badge. Default is 0.75rem (12px).
  * @cssproperty --mdc-badge-dot-height - The height of the dot badge. Default is 0.75rem (12px).
- *
+ * 
  * @csspart badge-dot - The dot notification badge.
  * @csspart badge-icon - The icon badge.
  * @csspart badge-overlay - The overlay badge.

package/dist/components/badge/badge.component.js

@@ -17,27 +17,11 @@ import { TYPE as FONT_TYPE, VALID_TEXT_TAGS } from '../text/text.constants';
 import { DEFAULTS, ICON_NAMES_LIST, ICON_VARIANT, TYPE as BADGE_TYPE } from './badge.constants';
 import styles from './badge.styles';
 /**
- * The `mdc-badge` component is a versatile UI element used to
- * display dot, icons, counters, success, warning and error type badge.
- *
- * Supported badge types:
- * - `dot`: Displays a dot notification badge with a blue color.
- * - `icon`: Displays a badge with a specified icon using the `icon-name` attribute.
- * - `counter`: Displays a badge with a counter value. If the counter exceeds the `max-counter`,
- * it shows `maxCounter+`. The maximum value of the counter is 999 and anything above that will be set to `999+`.
- * - `success`: Displays a success badge with a check circle icon and green color.
- * - `warning`: Displays a warning badge with a warning icon and yellow color.
- * - `error`: Displays a error badge with a error legacy icon and red color.
- *
- * For `icon`, `success`, `warning` and `error` types, the `mdc-icon` component is used to render the icon.
- *
- * For the `counter` type, the `mdc-text` component is used to render the counter value.
+ * @tagname mdc-badge
  *
  * @dependency mdc-icon
  * @dependency mdc-text
  *
- * @tagname mdc-badge
- *
  * @cssproperty --mdc-badge-primary-foreground-color - The foreground color of the primary badge.
  * @cssproperty --mdc-badge-primary-background-color - The background color of the primary badge.
  * @cssproperty --mdc-badge-secondary-foreground-color - The foreground color of the secondary badge.

package/dist/components/banner/banner.component.d.ts

@@ -2,35 +2,35 @@ import type { CSSResult, TemplateResult } from 'lit';
 import { Component } from '../../models';
 import type { BannerVariant } from './banner.types';
 /**
- * `mdc-banner` is a component that allows applications to communicate important messages to users
- * and requires user action to dismiss them. It supports different message types with appropriate styling
- * and icons, and provides flexibility for customization through label, secondary label, icons, and actions.
- *
- * They are designed to be noticeable yet non-intrusive, helping users stay informed without interrupting their workflow.
- *
- * This component supports both structured content via properties and flexible customization via slots:
- * - Use the properties (`label`, `secondaryLabel`, `variant`) for standard banner layouts with automatic icon selection.
- * - Use slots for custom content and complete layout control.
- * - Combine both approaches for maximum flexibility.
- * - Create custom orientations and actions using CSS parts and slots.
- *
+ * The banner is an in-page message used to communicate important information to users. It supports several message variants with appropriate icons and styling, and can be customised through label, secondary label, leading icon, and trailing action slots. Banners are designed to be noticeable yet non-intrusive — visible enough to inform without interrupting the user's workflow.
+ * 
+ * **When to use**
+ * 
+ * - Use `mdc-banner` to surface important contextual information at the top of a page, section, or panel — for example service status, validation summaries, or persistent notices that should remain visible until the user acts on them.
+ * 
+ * **When not to use**
+ * 
+ * - Use `mdc-toast` for short, transient feedback that should auto-dismiss and not occupy layout space.
+ * - Use `mdc-announcementdialog` or `mdc-dialog` when the message must block the rest of the UI until the user responds.
+ * - Use `mdc-alertchip` for a compact, interactive inline status indicator rather than a full-width message bar.
+ * 
+ * @tagname mdc-banner
+ * 
  * @dependency mdc-icon
  * @dependency mdc-text
- *
+ * 
  * @slot content - Complete content override. When used, it replaces all default banner content including icon, label, secondary label, and actions.
  * @slot leading-icon - Custom icon content. Overrides the default variant-based icon.
  * @slot leading-text - Custom text content. Overrides the label and secondaryLabel properties.
  * @slot trailing-actions - Custom action buttons and controls. Use this for dismiss buttons, reset buttons, or any other actions.
- *
- * @tagname mdc-banner
- *
+ * 
  * @csspart leading - The leading section containing the icon and text.
  * @csspart leading-icon - The icon displayed for variants or custom icon slot.
  * @csspart leading-text - The leading section containing label and secondary label text.
  * @csspart trailing - The trailing section containing action buttons and controls.
  * @csspart leading-label - The label text of the banner.
  * @csspart leading-secondary-label - The secondary label text of the banner.
- *
+ * 
  * @cssproperty --mdc-banner-background-color - Background color of the banner.
  * @cssproperty --mdc-banner-border-color - Border color of the banner.
  * @cssproperty --mdc-banner-border-width - Border width of the banner.

package/dist/components/banner/banner.component.js

@@ -15,17 +15,7 @@ import { DEFAULTS } from './banner.constants';
 import styles from './banner.styles';
 import { getIconNameForVariant } from './banner.utils';
 /**
- * `mdc-banner` is a component that allows applications to communicate important messages to users
- * and requires user action to dismiss them. It supports different message types with appropriate styling
- * and icons, and provides flexibility for customization through label, secondary label, icons, and actions.
- *
- * They are designed to be noticeable yet non-intrusive, helping users stay informed without interrupting their workflow.
- *
- * This component supports both structured content via properties and flexible customization via slots:
- * - Use the properties (`label`, `secondaryLabel`, `variant`) for standard banner layouts with automatic icon selection.
- * - Use slots for custom content and complete layout control.
- * - Combine both approaches for maximum flexibility.
- * - Create custom orientations and actions using CSS parts and slots.
+ * @tagname mdc-banner
  *
  * @dependency mdc-icon
  * @dependency mdc-text
@@ -35,8 +25,6 @@ import { getIconNameForVariant } from './banner.utils';
  * @slot leading-text - Custom text content. Overrides the label and secondaryLabel properties.
  * @slot trailing-actions - Custom action buttons and controls. Use this for dismiss buttons, reset buttons, or any other actions.
  *
- * @tagname mdc-banner
- *
  * @csspart leading - The leading section containing the icon and text.
  * @csspart leading-icon - The icon displayed for variants or custom icon slot.
  * @csspart leading-text - The leading section containing label and secondary label text.

package/dist/components/brandvisual/brandvisual.component.d.ts

@@ -2,21 +2,24 @@ import { CSSResult, TemplateResult } from 'lit';
 import { Component } from '../../models';
 import type { BrandVisualNames } from './brandvisual.types';
 /**
- * The `mdc-brandvisual` component is responsible for rendering logos dynamically & ensures they are
- * displayed correctly within applications.
- *
- * Features:
- * - Dynamically loads brandvisuals based on the `name` attribute.
- * - Emits a `load` event when the brandvisual is successfully fetched.
- * - Emits an `error` event when the brandvisual import fails.
- * - Supports accessibility best practices.
- * - Used for brand representation within the design system.
- *
+ * The brandvisual renders brand artwork — logos and wordmarks — from the Momentum `brand-visuals` package. Assets are loaded dynamically by name, so the consumer only references the visual they need and the component handles fetching and inserting the SVG or image at runtime. Successful loads emit a `load` event; failed lookups emit an `error` event so the host application can react.
+ * 
+ * **When to use**
+ * 
+ * - Use `mdc-brandvisual` to render product, company, or partner logos that ship with the Momentum brand library.
+ * - Use it when the logo asset is published in `@momentum-design/brand-visuals` and you want the design system to keep the artwork in sync rather than hard-coding inline SVG.
+ * 
+ * **When not to use**
+ * 
+ * - Use `mdc-icon` for UI iconography (controls, status, decorative glyphs) rather than brand artwork.
+ * - Use `mdc-illustration` for larger illustrative imagery that is not a brand mark.
+ * - Use a plain `<img>` tag when the asset lives outside the Momentum brand library and you do not need the dynamic-loading or event semantics.
+ * 
  * @tagname mdc-brandvisual
- *
+ * 
  * @event load - (React: onLoad) This event is dispatched when the brandvisual has been successfully loaded.
  * @event error - (React: onError) This event is dispatched when the brandvisual fetching has failed.
- *
+ * 
  * @csspart brandvisual - Set styles for the brandvisual svg container
  * @csspart brandvisualImage - Set styles for the brandvisual image container
  */

package/dist/components/brandvisual/brandvisual.component.js

@@ -12,16 +12,6 @@ import { property, state } from 'lit/decorators.js';
 import { Component } from '../../models';
 import styles from './brandvisual.styles';
 /**
- * The `mdc-brandvisual` component is responsible for rendering logos dynamically & ensures they are
- * displayed correctly within applications.
- *
- * Features:
- * - Dynamically loads brandvisuals based on the `name` attribute.
- * - Emits a `load` event when the brandvisual is successfully fetched.
- * - Emits an `error` event when the brandvisual import fails.
- * - Supports accessibility best practices.
- * - Used for brand representation within the design system.
- *
  * @tagname mdc-brandvisual
  *
  * @event load - (React: onLoad) This event is dispatched when the brandvisual has been successfully loaded.

package/dist/components/bullet/bullet.component.d.ts

@@ -2,23 +2,22 @@ import type { CSSResult } from 'lit';
 import { Component } from '../../models';
 import type { Size } from './bullet.types';
 /**
- * The Bullet component displays a small circular visual indicator used to organize and present
- * items in a list format. It provides a simple, consistent way to mark list items or emphasize
- * content points.
- *
- * Bullets are available in three sizes (small, medium, large) to accommodate different layout
- * densities and visual hierarchies.
- *
- * ## When to use
- * Use bullets to create unordered lists, mark navigation items, or provide visual indicators
- * for list content. Choose bullet size based on content importance and layout density.
- *
- * ## Accessibility
- * - Bullets are purely decorative and should be used alongside meaningful text content
- * - Do not rely solely on bullet size or color to convey information
- *
+ * The bullet is a small, non-interactive circular indicator used to mark or separate items in a list-style layout. It provides a consistent visual mark in three sizes (small, medium, large) so consumers can match the bullet to the surrounding content density.
+ * 
+ * **When to use**
+ * 
+ * - Use `mdc-bullet` as a visual marker in custom unordered lists, navigation indicators, or as a separator dot between inline text fragments.
+ * - Pick the size based on layout density and visual emphasis: `small` for compact rows, `medium` for typical body content, `large` when the marker should stand out.
+ * 
+ * **When not to use**
+ * 
+ * - Use a native `<ul>`/`<li>` list when the platform's default bullet styling is sufficient — it carries list semantics for free.
+ * - Use `mdc-badge` (`dot` type) when the indicator should communicate a notification or status rather than mark a list item.
+ * - Use `mdc-presence` when the dot conveys a user's availability state (active, away, busy, dnd).
+ * - Use `mdc-divider` when you need a visible separator between sections rather than a marker for an individual item.
+ * 
  * @tagname mdc-bullet
- *
+ * 
  * @cssproperty --mdc-bullet-background-color - Background color of the bullet.
  * @cssproperty --mdc-bullet-size - Height of the bullet.
  */

package/dist/components/bullet/bullet.component.js

@@ -12,21 +12,6 @@ import { Component } from '../../models';
 import styles from './bullet.styles';
 import { SIZE } from './bullet.constants';
 /**
- * The Bullet component displays a small circular visual indicator used to organize and present
- * items in a list format. It provides a simple, consistent way to mark list items or emphasize
- * content points.
- *
- * Bullets are available in three sizes (small, medium, large) to accommodate different layout
- * densities and visual hierarchies.
- *
- * ## When to use
- * Use bullets to create unordered lists, mark navigation items, or provide visual indicators
- * for list content. Choose bullet size based on content importance and layout density.
- *
- * ## Accessibility
- * - Bullets are purely decorative and should be used alongside meaningful text content
- * - Do not rely solely on bullet size or color to convey information
- *
  * @tagname mdc-bullet
  *
  * @cssproperty --mdc-bullet-background-color - Background color of the bullet.

package/dist/components/button/button.component.d.ts

@@ -5,66 +5,36 @@ import Buttonsimple from '../buttonsimple/buttonsimple.component';
 import type { IconButtonSize, PillButtonSize } from './button.types';
 declare const Button_base: import("../../utils/mixins/index.types").Constructor<import("../../utils/mixins/OverflowMixin").OverflowMixinInterface> & import("../../utils/mixins/index.types").Constructor<import("../../utils/mixins/ButtonComponentMixin").ButtonComponentMixinInterface> & typeof Buttonsimple;
 /**
- * `mdc-button` is a component that can be configured in various ways to suit different use cases.
- *
- * ## Button configuration
- *
- * The appearance of the button depends on combination of multiple attributes.
- *
- * ### Button Types
- *
- * The type of button is inferred based on the presence of slot and/or prefix and postfix icons/slots:
- *
- * - **Pill button**: Contains text value, commonly used for call to action, tags, or filters
- * - **Pill button with icons**: Contains an icon on the left or right side of the button
- * - **Icon button**: Represented by just an icon without any text
- *
- * ### Button Variants:
- *
- * Options for button backgrounds and borders:
- *
- * - **Primary**: Solid background color
- * - **Secondary**: Transparent background with solid border
- * - **Tertiary**: No background or border, text-only appearance
- *
- * ### Button Colors
- *
- * Color options for **Primary** and **Secondary** buttons:
- *
- * - **Default**: For standard actions
- * - **Positive**: For success or confirmation actions
- * - **Negative**: For destructive or error actions
- * - **Accent**: For informational actions
- * - **Promotional**: For promotional actions
- *
- * Color options for **Tertiary** buttons:
- *
- * - **Default**: For standard actions
- * - **Accent**: For informational actions
- * - **Negative**: For destructive or error actions
- *
- * ### Button Sizes
- *
- * Size options for different button configurations in REM:
- *
- * - **Pill button**: 40, 32, 28, 24
- * - **Icon button**: 64, 52, 40, 32, 28, 24
- * - **Tertiary icon button**: 20
- *
- * @dependency mdc-icon
- *
+ * The button triggers user actions such as submitting a form, opening a dialog, or running a command. It supports three layouts — pill (text only), pill with leading/trailing icons, and icon-only — and offers variant, color, and size options so it can scale from a primary call-to-action down to a compact toolbar control.
+ * 
+ * **When to use**
+ * 
+ * - Use `mdc-button` for the primary, secondary, or tertiary actions inside forms, dialogs, toolbars, and content surfaces.
+ * - Use the icon-only layout for compact action targets such as toolbars or table-row controls where space is constrained and the icon's meaning is unambiguous.
+ * - Use the `inverted` flag when placing a primary default button on a dark or inverted surface so the color scheme keeps the required contrast.
+ * 
+ * **When not to use**
+ * 
+ * - Use `mdc-link` when the control navigates to a different URL or in-app route — links should look and behave like links, not buttons.
+ * - Use `mdc-linkbutton` when you need the visual styling of a button but the underlying action is a navigation (renders an `<a>` instead of a `<button>`, so it carries link semantics and browser affordances like open-in-new-tab).
+ * - Use `mdc-toggle` or `mdc-checkbox` for binary on/off state inside forms — they expose the right form-control semantics rather than mimicking state with a toggled button.
+ * - Use `mdc-tab` inside `mdc-tablist` for tabbed navigation rather than a styled button.
+ * - Use `mdc-menuitem` (or a related menu item) when the control lives inside a menu surface.
+ * 
  * @tagname mdc-button
- *
+ * 
+ * @dependency mdc-icon
+ * 
  * @slot - Text label of the button.
  * @slot prefix - Content to be displayed before the text label.
  * @slot postfix - Content to be displayed after the text label.
- *
+ * 
  * @csspart button-text - Text label of the button, passed in default slot
  * @csspart prefix - Content before the text label, passed in `prefix` slot
  * @csspart postfix - Content after the text label, passed in `postfix` slot
  * @csspart prefix-icon - Icon element displayed before the text label when `prefix-icon` attribute is set
  * @csspart postfix-icon - Icon element displayed after the text label when `postfix-icon` attribute is set
- *
+ * 
  * @cssproperty --mdc-button-height - Height for button size
  * @cssproperty --mdc-button-background - Background of the button
  * @cssproperty --mdc-button-border-color - Border color of the button
@@ -72,7 +42,6 @@ declare const Button_base: import("../../utils/mixins/index.types").Constructor<
  * @cssproperty --mdc-button-prefix-icon-size - Size of the prefix icon
  * @cssproperty --mdc-button-postfix-icon-size - Size of the postfix icon
  * @cssproperty --mdc-button-line-height - Line height of the button text
- *
  */
 declare class Button extends Button_base {
     /**

package/dist/components/button/button.component.js

@@ -17,56 +17,10 @@ import { DEFAULTS } from './button.constants';
 import styles from './button.styles';
 import { getIconNameWithoutStyle } from './button.utils';
 /**
- * `mdc-button` is a component that can be configured in various ways to suit different use cases.
- *
- * ## Button configuration
- *
- * The appearance of the button depends on combination of multiple attributes.
- *
- * ### Button Types
- *
- * The type of button is inferred based on the presence of slot and/or prefix and postfix icons/slots:
- *
- * - **Pill button**: Contains text value, commonly used for call to action, tags, or filters
- * - **Pill button with icons**: Contains an icon on the left or right side of the button
- * - **Icon button**: Represented by just an icon without any text
- *
- * ### Button Variants:
- *
- * Options for button backgrounds and borders:
- *
- * - **Primary**: Solid background color
- * - **Secondary**: Transparent background with solid border
- * - **Tertiary**: No background or border, text-only appearance
- *
- * ### Button Colors
- *
- * Color options for **Primary** and **Secondary** buttons:
- *
- * - **Default**: For standard actions
- * - **Positive**: For success or confirmation actions
- * - **Negative**: For destructive or error actions
- * - **Accent**: For informational actions
- * - **Promotional**: For promotional actions
- *
- * Color options for **Tertiary** buttons:
- *
- * - **Default**: For standard actions
- * - **Accent**: For informational actions
- * - **Negative**: For destructive or error actions
- *
- * ### Button Sizes
- *
- * Size options for different button configurations in REM:
- *
- * - **Pill button**: 40, 32, 28, 24
- * - **Icon button**: 64, 52, 40, 32, 28, 24
- * - **Tertiary icon button**: 20
+ * @tagname mdc-button
  *
  * @dependency mdc-icon
  *
- * @tagname mdc-button
- *
  * @slot - Text label of the button.
  * @slot prefix - Content to be displayed before the text label.
  * @slot postfix - Content to be displayed after the text label.

package/dist/components/buttongroup/buttongroup.component.d.ts

@@ -2,31 +2,28 @@ import { CSSResult, PropertyValues } from 'lit';
 import { Component } from '../../models';
 import type { ButtonGroupOrientation, ButtonGroupSize, ButtonGroupVariant } from './buttongroup.types';
 /**
- * `mdc-buttongroup` is a wrapper component that groups multiple buttons together.
- *
- * ## Supported button types
- * - Icon buttons
- * - Pill buttons
- * - Combination of icon and pill buttons
- *
- * ## Features
- * - Horizontal or vertical orientation
- * - Unified size and variant applied to all child buttons
- * - Optional compact mode for reduced height
- * - Supported sizes: 24, 28 (default), 32, 40
- *
- * ## Usage
- * - Only `mdc-button` components are allowed as direct children
- * - The `size` and `variant` set on buttongroup override individual button settings
- *
+ * The buttongroup arranges related `mdc-button` instances into a single segmented control. It applies a shared `size` and `variant` to each slotted button so the group reads as one unit, supports horizontal or vertical layouts, and offers a compact mode for space-constrained surfaces.
+ * 
+ * **When to use**
+ * 
+ * - Use `mdc-buttongroup` to cluster mutually related actions that operate on the same target (for example a toolbar of formatting actions, a zoom in/out pair, or a "select / clear" duo).
+ * - Use it when the visual unification of multiple buttons communicates that they belong together and share styling.
+ * 
+ * **When not to use**
+ * 
+ * - Use a single `mdc-button` when there is only one action to present.
+ * - Use `mdc-tablist` with `mdc-tab` when the controls switch between panels of content — tabs carry the right semantics for that pattern.
+ * - Use `mdc-toggle` or `mdc-radiogroup` when the buttons represent a mutually exclusive selection that should be announced as a single form value.
+ * - Use `mdc-menubar` or `mdc-menupopover` when the actions belong inside a menu surface rather than a persistent toolbar.
+ * 
  * @tagname mdc-buttongroup
- *
+ * 
  * @slot default - This is a default/unnamed slot, which contains the buttons
- *
+ * 
  * @cssproperty --mdc-buttongroup-border-radius - The border radius of the buttongroup
  * @cssproperty --mdc-buttongroup-border-color - The border color of the buttongroup
  * @cssproperty --mdc-buttongroup-divider-color - The color of the divider between buttons within the buttongroup
- *
+ * 
  * @csspart container - The container of the buttongroup.
  */
 declare class ButtonGroup extends Component {

package/dist/components/buttongroup/buttongroup.component.js

@@ -13,23 +13,6 @@ import { Component } from '../../models';
 import { DEFAULTS } from './buttongroup.constants';
 import styles from './buttongroup.styles';
 /**
- * `mdc-buttongroup` is a wrapper component that groups multiple buttons together.
- *
- * ## Supported button types
- * - Icon buttons
- * - Pill buttons
- * - Combination of icon and pill buttons
- *
- * ## Features
- * - Horizontal or vertical orientation
- * - Unified size and variant applied to all child buttons
- * - Optional compact mode for reduced height
- * - Supported sizes: 24, 28 (default), 32, 40
- *
- * ## Usage
- * - Only `mdc-button` components are allowed as direct children
- * - The `size` and `variant` set on buttongroup override individual button settings
- *
  * @tagname mdc-buttongroup
  *
  * @slot default - This is a default/unnamed slot, which contains the buttons

package/dist/components/buttonlink/buttonlink.component.d.ts

@@ -3,32 +3,35 @@ import Linksimple from '../linksimple/linksimple.component';
 import type { IconButtonSize, PillButtonSize } from '../button/button.types';
 declare const ButtonLink_base: import("../../utils/mixins/index.types").Constructor<import("../../utils/mixins/ButtonComponentMixin").ButtonComponentMixinInterface> & typeof Linksimple;
 /**
- * `mdc-buttonlink` combines the functional behavior of `mdc-linksimple` with the visual and structural
- * features of `mdc-button`. This includes support for variants, sizing, and optional
- * prefix and postfix icons.
- *
- * ### Features:
- * - Behaves like a link while visually resembling a button.
- * - Customizable size, color, and variant through attributes.
- * - Supports prefix and postfix icons.
- * - Inherits accessibility and keyboard interaction support from `mdc-linksimple`.
- *
- * @dependency mdc-icon
- *
+ * The buttonlink renders a navigational anchor (`<a>`) styled as a button. It is the right choice when the visual treatment should match a button but the action is navigation — the underlying element carries link semantics, so right-click, middle-click, and "open in new tab" all work as users expect.
+ * 
+ * **When to use**
+ * 
+ * - Use `mdc-buttonlink` when the control navigates to a different URL or in-app route but the design calls for a button's visual weight (primary call-to-action, prominent toolbar entry, etc.).
+ * - Use it when you want native browser link affordances such as `target="_blank"`, `download`, `ping`, or `rel` while keeping the button appearance.
+ * 
+ * **When not to use**
+ * 
+ * - Use `mdc-button` when the control performs an action (submitting a form, opening a dialog, running a command) and does not change the URL.
+ * - Use `mdc-link` when the control is a textual inline or standalone link and does not need to look like a button.
+ * - Use `mdc-linksimple` when you need a minimal, unstyled link primitive without button styling or icon slots.
+ * 
  * @tagname mdc-buttonlink
- *
+ * 
+ * @dependency mdc-icon
+ * 
  * @slot default - The default slot for buttonlink text content.
- *
+ * 
  * @event click - (React: onClick) Fired when the user activates the buttonLink using a mouse or assistive technology.
  * @event keydown - (React: onKeyDown) Fired when the user presses a key while the buttonLink has focus.
  * @event focus - (React: onFocus) Fired when the buttonLink receives keyboard or mouse focus.
  * @event blur - (React: onBlur) Fired when the buttonLink loses keyboard or mouse focus.
- *
+ * 
  * @csspart anchor - The anchor element that wraps the buttonlink content.
  * @csspart prefix-icon - The prefix icon element.
  * @csspart button-text - The slot containing the buttonlink text.
  * @csspart postfix-icon - The postfix icon element.
- *
+ * 
  * @cssproperty --mdc-button-height - Height of the buttonlink
  * @cssproperty --mdc-button-background - Background color of the buttonlink
  * @cssproperty --mdc-button-border-color - Border color of the buttonlink

package/dist/components/buttonlink/buttonlink.component.js

@@ -15,20 +15,10 @@ import { DEFAULTS } from '../button/button.constants';
 import Linksimple from '../linksimple/linksimple.component';
 import styles from './buttonlink.styles';
 /**
- * `mdc-buttonlink` combines the functional behavior of `mdc-linksimple` with the visual and structural
- * features of `mdc-button`. This includes support for variants, sizing, and optional
- * prefix and postfix icons.
- *
- * ### Features:
- * - Behaves like a link while visually resembling a button.
- * - Customizable size, color, and variant through attributes.
- * - Supports prefix and postfix icons.
- * - Inherits accessibility and keyboard interaction support from `mdc-linksimple`.
+ * @tagname mdc-buttonlink
  *
  * @dependency mdc-icon
  *
- * @tagname mdc-buttonlink
- *
  * @slot default - The default slot for buttonlink text content.
  *
  * @event click - (React: onClick) Fired when the user activates the buttonLink using a mouse or assistive technology.