@momentum-design/components 0.129.13 → 0.129.15

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

@@ -1,23 +1,27 @@
 import { CSSResult } from 'lit';
 import { Component } from '../../models';
 /**
- * The `mdc-appheader` component provides a structured and accessible app header layout.
- * It consists of three primary sections: leading, center, and trailing.
+ * The `mdc-appheader` component provides a structured and accessible app header layout with three sections: leading, center, and trailing.
  *
- * - The **leading section** typically holds a **brand logo**, **brand name** or **menu icon**.
- * - The **center section** can contain a **search bar**, **icons** or action controls.
- * - The **trailing section** generally includes a **profile avatar**, **additional icons** or **action controls**.
+ * ## Layout sections
+ * - **Leading** - Typically holds brand logo, brand name, or menu icon
+ * - **Center** - Can contain search bar, icons, navigation links, or action controls
+ * - **Trailing** - Generally includes profile avatar, icons, settings, or additional action controls
+ *
+ * Each section automatically handles flex alignment: leading aligns left, center aligns center, trailing aligns right.
  *
  * @tagname mdc-appheader
  *
- * @slot leading - Slot for the leading section (e.g., brand logo, brand name).
- * @slot center - Slot for the center section (e.g., search bar, icons).
- * @slot trailing - Slot for the trailing section (e.g., profile avatar, icons).
+ * @slot leading - Content for the leading section (left-aligned).
+ * @slot center - Content for the center section (center-aligned).
+ * @slot trailing - Content for the trailing section (right-aligned).
+ *
+ * @cssproperty --mdc-appheader-height - Height of the app header. Default is 4rem (64px).
  *
- * @csspart container - The main container for styling the header.
- * @csspart leading-section - The leading section of the header.
- * @csspart center-section - The center section of the header.
- * @csspart trailing-section - The trailing section of the header.
+ * @csspart container - The main header container.
+ * @csspart leading-section - The leading section wrapper (left side).
+ * @csspart center-section - The center section wrapper (middle).
+ * @csspart trailing-section - The trailing section wrapper (right side).
  */
 declare class Appheader extends Component {
     /**

package/dist/components/appheader/appheader.component.js

@@ -2,23 +2,27 @@ import { html } from 'lit';
 import { Component } from '../../models';
 import styles from './appheader.styles';
 /**
- * The `mdc-appheader` component provides a structured and accessible app header layout.
- * It consists of three primary sections: leading, center, and trailing.
+ * The `mdc-appheader` component provides a structured and accessible app header layout with three sections: leading, center, and trailing.
  *
- * - The **leading section** typically holds a **brand logo**, **brand name** or **menu icon**.
- * - The **center section** can contain a **search bar**, **icons** or action controls.
- * - The **trailing section** generally includes a **profile avatar**, **additional icons** or **action controls**.
+ * ## Layout sections
+ * - **Leading** - Typically holds brand logo, brand name, or menu icon
+ * - **Center** - Can contain search bar, icons, navigation links, or action controls
+ * - **Trailing** - Generally includes profile avatar, icons, settings, or additional action controls
+ *
+ * Each section automatically handles flex alignment: leading aligns left, center aligns center, trailing aligns right.
  *
  * @tagname mdc-appheader
  *
- * @slot leading - Slot for the leading section (e.g., brand logo, brand name).
- * @slot center - Slot for the center section (e.g., search bar, icons).
- * @slot trailing - Slot for the trailing section (e.g., profile avatar, icons).
+ * @slot leading - Content for the leading section (left-aligned).
+ * @slot center - Content for the center section (center-aligned).
+ * @slot trailing - Content for the trailing section (right-aligned).
+ *
+ * @cssproperty --mdc-appheader-height - Height of the app header. Default is 4rem (64px).
  *
- * @csspart container - The main container for styling the header.
- * @csspart leading-section - The leading section of the header.
- * @csspart center-section - The center section of the header.
- * @csspart trailing-section - The trailing section of the header.
+ * @csspart container - The main header container.
+ * @csspart leading-section - The leading section wrapper (left side).
+ * @csspart center-section - The center section wrapper (middle).
+ * @csspart trailing-section - The trailing section wrapper (right side).
  */
 class Appheader extends Component {
     /**

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

@@ -3,24 +3,31 @@ import { CSSResult } from 'lit';
 import { Component } from '../../models';
 declare const Avatar_base: import("../../utils/mixins/index.types").Constructor<import("../../utils/mixins/AvatarComponentMixin").AvatarComponentMixinInterface> & import("../../utils/mixins/index.types").Constructor<import("../../utils/mixins/IconNameMixin").IconNameMixinInterface> & typeof Component;
 /**
- * The `mdc-avatar` component is used to represent a person or a space.
- * An avatar can be an icon, initials, counter and photo.
+ * The `mdc-avatar` component represents a person or a space. It displays as a photo, initials, icon, or counter.
  *
- * To set the photo of an avatar,
- * you need to set "src" attribute.
+ * ## Display Priority
  *
- * While the avatar image is loading, as a placeholder,
- * we will show the initials text.
- * If the initials are not specified then,
- * we will show `user-regular` icon as a placeholder.
+ * When multiple attributes are provided, the component determines what to display based on this priority:
+ * 1. **Photo** (`src`) - Takes highest priority
+ *    - While loading: Shows `initials` as placeholder if provided (instant), otherwise shows icon (requires loading)
+ *    - After loading: Shows the photo
+ *    - On error: Placeholder remains visible (initials or icon)
+ * 2. **Icon** (`icon-name`) - Takes priority if no `src` is provided
+ *    - Shows custom icon if `icon-name` is set (requires icon library to load)
+ *    - **Note:** If both `icon-name` and `initials` are provided (without `src`), icon takes precedence and initials are ignored.
+ *      This means users may see a delay while the icon loads, even though initials render instantly.
+ *    - Defaults to `user-regular` icon if no other content is available
+ * 3. **Initials** (`initials`) - Displayed only if no `src` or `icon-name` is provided
+ *    - Shows first two characters, converted to uppercase
+ *    - Renders instantly (no loading required)
+ * 4. **Counter** (`counter`) - Displayed only if none of the above are provided
+ *    - Shows numeric value (max 99+)
+ *    - Negative values display as 0
  *
- * By default, if there are no attributes specified,
- * then the default avatar will be an icon with `user-regular` name.
- *
- * The avatar component is non clickable and non interactive/focusable component.
- * If the avatar is typing, then the loading indicator will be displayed.
- * If the counter type avatar is set to a negative number, then we will display 0.
- * The presence indicator will be hidden when the counter property is set.
+ * ## Behavior
+ * - Non-interactive and non-focusable component (use `mdc-avatarbutton` for clickable avatars)
+ * - Shows loading indicator overlay when `is-typing` is true (displays on top of existing content)
+ * - Presence indicator hidden when counter is set or when typing
  *
  * @dependency mdc-icon
  * @dependency mdc-presence

package/dist/components/avatar/avatar.component.js

@@ -17,24 +17,31 @@ import { AVATAR_TYPE, DEFAULTS, MAX_COUNTER } from './avatar.constants';
 import styles from './avatar.styles';
 import { getAvatarIconSize, getAvatarTextFontSize, getPresenceSize } from './avatar.utils';
 /**
- * The `mdc-avatar` component is used to represent a person or a space.
- * An avatar can be an icon, initials, counter and photo.
+ * The `mdc-avatar` component represents a person or a space. It displays as a photo, initials, icon, or counter.
  *
- * To set the photo of an avatar,
- * you need to set "src" attribute.
+ * ## Display Priority
  *
- * While the avatar image is loading, as a placeholder,
- * we will show the initials text.
- * If the initials are not specified then,
- * we will show `user-regular` icon as a placeholder.
+ * When multiple attributes are provided, the component determines what to display based on this priority:
+ * 1. **Photo** (`src`) - Takes highest priority
+ *    - While loading: Shows `initials` as placeholder if provided (instant), otherwise shows icon (requires loading)
+ *    - After loading: Shows the photo
+ *    - On error: Placeholder remains visible (initials or icon)
+ * 2. **Icon** (`icon-name`) - Takes priority if no `src` is provided
+ *    - Shows custom icon if `icon-name` is set (requires icon library to load)
+ *    - **Note:** If both `icon-name` and `initials` are provided (without `src`), icon takes precedence and initials are ignored.
+ *      This means users may see a delay while the icon loads, even though initials render instantly.
+ *    - Defaults to `user-regular` icon if no other content is available
+ * 3. **Initials** (`initials`) - Displayed only if no `src` or `icon-name` is provided
+ *    - Shows first two characters, converted to uppercase
+ *    - Renders instantly (no loading required)
+ * 4. **Counter** (`counter`) - Displayed only if none of the above are provided
+ *    - Shows numeric value (max 99+)
+ *    - Negative values display as 0
  *
- * By default, if there are no attributes specified,
- * then the default avatar will be an icon with `user-regular` name.
- *
- * The avatar component is non clickable and non interactive/focusable component.
- * If the avatar is typing, then the loading indicator will be displayed.
- * If the counter type avatar is set to a negative number, then we will display 0.
- * The presence indicator will be hidden when the counter property is set.
+ * ## Behavior
+ * - Non-interactive and non-focusable component (use `mdc-avatarbutton` for clickable avatars)
+ * - Shows loading indicator overlay when `is-typing` is true (displays on top of existing content)
+ * - Presence indicator hidden when counter is set or when typing
  *
  * @dependency mdc-icon
  * @dependency mdc-presence

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

@@ -3,25 +3,27 @@ import { CSSResult } from 'lit';
 import Buttonsimple from '../buttonsimple/buttonsimple.component';
 declare const AvatarButton_base: import("../../utils/mixins/index.types").Constructor<import("../../utils/mixins/AvatarComponentMixin").AvatarComponentMixinInterface> & import("../../utils/mixins/index.types").Constructor<import("../../utils/mixins/IconNameMixin").IconNameMixinInterface> & typeof Buttonsimple;
 /**
- * The `mdc-avatarbutton` component is an interactable version of the `mdc-avatar` component.
+ * The `mdc-avatarbutton` component is an interactive, clickable version of `mdc-avatar`.
+ * It wraps the avatar component in a button, making it focusable and actionable.
  *
- * This component is made by extending `buttonsimple` class.
- * The button component acts as a wrapper for the avatar component.
+ * This component extends `buttonsimple` and includes all avatar display features (photo, initials, icon, counter, presence).
+ * Use CSS parts to customize the avatar's appearance inside the button.
  *
- * To override styles of the avatar inside, use the specified css parts.
+ * ## Accessibility
+ * - Always provide an `aria-label` attribute to describe the button's purpose
  *
  * @dependency mdc-avatar
  *
- * @event click - (React: onClick) This event is dispatched when the avatarbutton is clicked.
- * @event keydown - (React: onKeyDown) This event is dispatched when a key is pressed down on the avatarbutton.
- * @event keyup - (React: onKeyUp) This event is dispatched when a key is released on the avatarbutton.
- * @event focus - (React: onFocus) This event is dispatched when the avatarbutton receives focus.
+ * @event click - (React: onClick) Dispatched when the avatar button is clicked.
+ * @event keydown - (React: onKeyDown) Dispatched when a key is pressed on the avatar button.
+ * @event keyup - (React: onKeyUp) Dispatched when a key is released on the avatar button.
+ * @event focus - (React: onFocus) Dispatched when the avatar button receives focus.
  *
  * @tagname mdc-avatarbutton
  *
- * @cssproperty --mdc-avatarbutton-overlay-background-color-rest - Background color of the overlay in rest state
- * @cssproperty --mdc-avatarbutton-overlay-background-color-hover - Background color of the overlay in hover state
- * @cssproperty --mdc-avatarbutton-overlay-background-color-active - Background color of the overlay in active state
+ * @cssproperty --mdc-avatarbutton-overlay-background-color-rest - Background color of the overlay in rest state.
+ * @cssproperty --mdc-avatarbutton-overlay-background-color-hover - Background color of the overlay in hover state.
+ * @cssproperty --mdc-avatarbutton-overlay-background-color-active - Background color of the overlay in active state.
  *
  * @csspart overlay - The overlay part of the avatar button.
  * @csspart content - The main content of the avatar.

package/dist/components/avatarbutton/avatarbutton.component.js

@@ -18,25 +18,27 @@ import { DEFAULTS as BUTTON_DEFAULTS } from '../button/button.constants';
 import Buttonsimple from '../buttonsimple/buttonsimple.component';
 import styles from './avatarbutton.styles';
 /**
- * The `mdc-avatarbutton` component is an interactable version of the `mdc-avatar` component.
+ * The `mdc-avatarbutton` component is an interactive, clickable version of `mdc-avatar`.
+ * It wraps the avatar component in a button, making it focusable and actionable.
  *
- * This component is made by extending `buttonsimple` class.
- * The button component acts as a wrapper for the avatar component.
+ * This component extends `buttonsimple` and includes all avatar display features (photo, initials, icon, counter, presence).
+ * Use CSS parts to customize the avatar's appearance inside the button.
  *
- * To override styles of the avatar inside, use the specified css parts.
+ * ## Accessibility
+ * - Always provide an `aria-label` attribute to describe the button's purpose
  *
  * @dependency mdc-avatar
  *
- * @event click - (React: onClick) This event is dispatched when the avatarbutton is clicked.
- * @event keydown - (React: onKeyDown) This event is dispatched when a key is pressed down on the avatarbutton.
- * @event keyup - (React: onKeyUp) This event is dispatched when a key is released on the avatarbutton.
- * @event focus - (React: onFocus) This event is dispatched when the avatarbutton receives focus.
+ * @event click - (React: onClick) Dispatched when the avatar button is clicked.
+ * @event keydown - (React: onKeyDown) Dispatched when a key is pressed on the avatar button.
+ * @event keyup - (React: onKeyUp) Dispatched when a key is released on the avatar button.
+ * @event focus - (React: onFocus) Dispatched when the avatar button receives focus.
  *
  * @tagname mdc-avatarbutton
  *
- * @cssproperty --mdc-avatarbutton-overlay-background-color-rest - Background color of the overlay in rest state
- * @cssproperty --mdc-avatarbutton-overlay-background-color-hover - Background color of the overlay in hover state
- * @cssproperty --mdc-avatarbutton-overlay-background-color-active - Background color of the overlay in active state
+ * @cssproperty --mdc-avatarbutton-overlay-background-color-rest - Background color of the overlay in rest state.
+ * @cssproperty --mdc-avatarbutton-overlay-background-color-hover - Background color of the overlay in hover state.
+ * @cssproperty --mdc-avatarbutton-overlay-background-color-active - Background color of the overlay in active state.
  *
  * @csspart overlay - The overlay part of the avatar button.
  * @csspart content - The main content of the avatar.

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

@@ -14,9 +14,12 @@ import type { Size } from './bullet.types';
  */
 declare class Bullet extends Component {
     /**
-     * Size of the bullet
+     * Specifies the size of the bullet visual indicator.
+     *
+     * - `small` (default): 0.25rem (4px) - Compact bullet for dense layouts
+     * - `medium`: 0.5rem (8px) - Standard bullet for most use cases
+     * - `large`: 1rem (16px) - Prominent bullet for emphasis
      *
-     * Possible values: 'small', 'medium', 'large'
      * @default small
      */
     size: Size;

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

@@ -26,9 +26,12 @@ class Bullet extends Component {
     constructor() {
         super(...arguments);
         /**
-         * Size of the bullet
+         * Specifies the size of the bullet visual indicator.
+         *
+         * - `small` (default): 0.25rem (4px) - Compact bullet for dense layouts
+         * - `medium`: 0.5rem (8px) - Standard bullet for most use cases
+         * - `large`: 1rem (16px) - Prominent bullet for emphasis
          *
-         * Possible values: 'small', 'medium', 'large'
          * @default small
          */
         this.size = SIZE.SMALL;

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

@@ -7,28 +7,43 @@ declare const Button_base: import("../../utils/mixins/index.types").Constructor<
 /**
  * `mdc-button` is a component that can be configured in various ways to suit different use cases.
  *
- * Button Variants:
- * - **Primary**: Solid background color.
- * - **Secondary**: Transparent background with a solid border.
- * - **Tertiary**: No background or border, appears as plain text but retains all button functionalities.
- *
- * Button Colors:
- * - **Positive**: Green color.
- * - **Negative**: Red color.
- * - **Accent**: Blue color.
- * - **Promotional**: Purple color.
- * - **Default**: White color.
- *
- * Button Sizes (in REM units):
- * - **Pill button**: 40, 32, 28, 24.
- * - **Icon button**: 64, 52, 40, 32, 28, 24.
- * - **Tertiary icon button**: 20.
- *
- * Button Types:
- * - **Pill button**: A button that contains text value. Commonly used for call to action, tags, or filters.
- * - **Pill button with icons**: A button containing an icon either on the left or right side of the button.
- * - **Icon button**: A button represented by just an icon without any text.
- * The type of button is inferred based on the presence of slot and/or prefix and postfix icons/slots.
+ * ## 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
+ *
+ * ### 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
  *
@@ -41,6 +56,8 @@ declare const Button_base: import("../../utils/mixins/index.types").Constructor<
  * @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
@@ -52,18 +69,37 @@ declare const Button_base: import("../../utils/mixins/index.types").Constructor<
  */
 declare class Button extends Button_base {
     /**
-     * Button sizing is based on the button type.
-     * - **Pill button**: 40, 32, 28, 24.
-     * - **Icon button**: 64, 52, 40, 32, 28, 24.
-     * - Tertiary icon button can also be 20.
+     * Specifies the size of the button in pixels. Available sizes depend on the button type:
+     *
+     * **Pill button** (with text):
+     * - `40`: Large size (2.5rem)
+     * - `32`: Default size (2rem)
+     * - `28`: Medium size (1.75rem)
+     * - `24`: Small size (1.5rem)
+     *
+     * **Icon button** (icon only):
+     * - `64`: Extra large (4rem)
+     * - `52`: Large (3.25rem)
+     * - `40`: Medium-large (2.5rem)
+     * - `32`: Default (2rem)
+     * - `28`: Medium (1.75rem)
+     * - `24`: Small (1.5rem)
+     * - `20`: Extra small (1.25rem) - Only available for tertiary variant
+     *
      * @default 32
      */
     size: PillButtonSize | IconButtonSize;
     /**
-     * The button color can be inverted by setting the inverted attribute to true.
+     * Inverts the button's color scheme for use on dark backgrounds.
+     * When enabled, the button adapts its colors to maintain proper contrast on inverted surfaces.
+     *
+     * **Requirements:**
+     * - Only works with `variant="primary"`
+     * - Only works with `color="default"`
+     * - Button must not be in `active` state
+     *
+     * **Use case:** Place buttons on dark-colored backgrounds or inverted theme sections.
      *
-     * Only applies when variant is set to `primary`, color is set to `default`
-     * and button is not `active`.
      * @default false
      */
     inverted: boolean;

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

@@ -18,28 +18,43 @@ import { getIconNameWithoutStyle } from './button.utils';
 /**
  * `mdc-button` is a component that can be configured in various ways to suit different use cases.
  *
- * Button Variants:
- * - **Primary**: Solid background color.
- * - **Secondary**: Transparent background with a solid border.
- * - **Tertiary**: No background or border, appears as plain text but retains all button functionalities.
- *
- * Button Colors:
- * - **Positive**: Green color.
- * - **Negative**: Red color.
- * - **Accent**: Blue color.
- * - **Promotional**: Purple color.
- * - **Default**: White color.
- *
- * Button Sizes (in REM units):
- * - **Pill button**: 40, 32, 28, 24.
- * - **Icon button**: 64, 52, 40, 32, 28, 24.
- * - **Tertiary icon button**: 20.
- *
- * Button Types:
- * - **Pill button**: A button that contains text value. Commonly used for call to action, tags, or filters.
- * - **Pill button with icons**: A button containing an icon either on the left or right side of the button.
- * - **Icon button**: A button represented by just an icon without any text.
- * The type of button is inferred based on the presence of slot and/or prefix and postfix icons/slots.
+ * ## 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
+ *
+ * ### 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
  *
@@ -52,6 +67,8 @@ import { getIconNameWithoutStyle } from './button.utils';
  * @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
@@ -65,18 +82,37 @@ class Button extends ButtonComponentMixin(Buttonsimple) {
     constructor() {
         super(...arguments);
         /**
-         * Button sizing is based on the button type.
-         * - **Pill button**: 40, 32, 28, 24.
-         * - **Icon button**: 64, 52, 40, 32, 28, 24.
-         * - Tertiary icon button can also be 20.
+         * Specifies the size of the button in pixels. Available sizes depend on the button type:
+         *
+         * **Pill button** (with text):
+         * - `40`: Large size (2.5rem)
+         * - `32`: Default size (2rem)
+         * - `28`: Medium size (1.75rem)
+         * - `24`: Small size (1.5rem)
+         *
+         * **Icon button** (icon only):
+         * - `64`: Extra large (4rem)
+         * - `52`: Large (3.25rem)
+         * - `40`: Medium-large (2.5rem)
+         * - `32`: Default (2rem)
+         * - `28`: Medium (1.75rem)
+         * - `24`: Small (1.5rem)
+         * - `20`: Extra small (1.25rem) - Only available for tertiary variant
+         *
          * @default 32
          */
         this.size = DEFAULTS.SIZE;
         /**
-         * The button color can be inverted by setting the inverted attribute to true.
+         * Inverts the button's color scheme for use on dark backgrounds.
+         * When enabled, the button adapts its colors to maintain proper contrast on inverted surfaces.
+         *
+         * **Requirements:**
+         * - Only works with `variant="primary"`
+         * - Only works with `color="default"`
+         * - Button must not be in `active` state
+         *
+         * **Use case:** Place buttons on dark-colored backgrounds or inverted theme sections.
          *
-         * Only applies when variant is set to `primary`, color is set to `default`
-         * and button is not `active`.
          * @default false
          */
         this.inverted = DEFAULTS.INVERTED;

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

@@ -2,24 +2,22 @@ import { CSSResult, PropertyValues } from 'lit';
 import { Component } from '../../models';
 import type { ButtonGroupOrientation, ButtonGroupSize, ButtonGroupVariant } from './buttongroup.types';
 /**
- * buttongroup component, is a wrapper to group multiple buttons.
- * It can support icon buttons, combination of icon and pill buttons, and text buttons.
- * Button group can be positioned in horizontal orientation and vertical orientation.
+ * `mdc-buttongroup` is a wrapper component that groups multiple buttons together.
  *
- * The sizes of buttons within the button group can be set using the `size` attribute on the button group,
- * which will apply the size to all buttons within the group.
+ * ## Supported button types
+ * - Icon buttons
+ * - Pill buttons
+ * - Combination of icon and pill buttons
  *
- * Buttons of sizes 24, 28, 32, and 40 are only supported inside a button group. Default size is 28.
+ * ## 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
  *
- * The variant of buttons within the button group can be set using the `variant` attribute on the button group,
- * which will apply the variant to all buttons within the group. Default variant is `primary`.
- *
- * All buttons are placed horizontally by default. To change the orientation to vertical, set the `orientation` attribute to `vertical`.
- *
- * Things to note:
- * - Button group will allow only `mdc-button` components as its direct children.
- * - Button group will set the `size` and `variant` attributes on the buttons within it,
- *   so any `size` or `variant` set directly on any button will be overridden.
+ * ## Usage
+ * - Only `mdc-button` components are allowed as direct children
+ * - The `size` and `variant` set on buttongroup override individual button settings
  *
  * @tagname mdc-buttongroup
  *
@@ -33,23 +31,30 @@ import type { ButtonGroupOrientation, ButtonGroupSize, ButtonGroupVariant } from
  */
 declare class ButtonGroup extends Component {
     /**
-     * Orientation of the buttongroup.
+     * Layout direction of the buttons within the group.
+     * - `horizontal`: Buttons are arranged side by side (default)
+     * - `vertical`: Buttons are stacked vertically
      * @default 'horizontal'
      */
     orientation: ButtonGroupOrientation;
     /**
-     * Variant of the buttons within the buttongroup.
+     * Visual style variant applied to all buttons in the group.
+     * - `primary`: Solid background color
+     * - `secondary`: Transparent background with solid border
+     * - `tertiary`: No background or border, text-only appearance
      * @default 'primary'
      */
     variant: ButtonGroupVariant;
     /**
-     * Size of the buttons within the buttongroup.
-     * @default '28'
+     * Size applied to all buttons in the group.
+     * Available sizes: 24, 28, 32, 40
+     * @default 28
      */
     size: ButtonGroupSize;
     /**
-     * When this is true, the buttons within the buttongroup will be compact.
-     * i.e. Irrespective of the size of the buttons, they will have a height of 24px.
+     * Enables compact mode with reduced height.
+     * When true, all buttons have a fixed height of 24px regardless of their size setting.
+     * Useful for space-constrained layouts.
      * @default false
      */
     compact: boolean;