@maxio-com/react-ui-components 9.15.0 → 9.16.1

package/dist/skills/maxio-react/references/components-forms-textfield.md

@@ -0,0 +1,253 @@
+# TextField
+
+## Usage Guidelines
+
+### Overview
+
+TextField lets users enter or edit a short, single-line text value in a form. Provide a visible label whenever possible, and pair helper or validation messaging with the field so users understand the expected value.
+
+#### When to Use
+
+- Use when users need to enter a short free-form value.
+- Use when browser input behavior should match the expected value, such as `email`, `url`, `tel`, `search`, or `password`.
+- Use with helper text when users need a format hint, example, or constraint before they type.
+- Use with leading or trailing content for simple visual context, units, prefixes, suffixes, or a small field-level action.
+
+#### When Not to Use
+
+- Do not use for long-form or multi-line writing. Use a textarea pattern instead.
+- Do not use when users must choose from a known list. Use Select for short lists or ComboBox when filtering helps.
+- Do not use placeholder text as the only label. Provide a visible `label` whenever possible.
+- Do not use for actions or navigation. Use Button, IconButton, or Link instead.
+
+### Variants
+
+| Variants | Purpose                                       | Usage notes                                                |
+| :------- | :-------------------------------------------- | :--------------------------------------------------------- |
+| `sm`     | Compact field for dense interfaces.           | Use where form density is high and labels remain readable. |
+| `md`     | Default field size.                           | Use for most forms.                                        |
+| `lg`     | Larger field for prominent form rows.         | Use sparingly when the field needs more visual emphasis.   |
+| `xl`     | Field with integrated label and helper/error. | Use when the field needs a stronger contained treatment.   |
+
+### Behavior
+
+- **Mouse and touch**: Users can place the cursor in the field, select text, and activate any nested trailing or leading action independently.
+- **Keyboard**: Users tab to the input, type or edit the value, and use native text editing shortcuts.
+- **Focus management**: Focus lands on the native input. Leading or trailing actions that are interactive should have their own accessible name and keyboard behavior.
+- **Controlled state**: Use `value` and `onChange` when product state owns the value. Use `defaultValue` for simple uncontrolled form fields.
+- **Validation**: Show validation after users submit, blur the field, or otherwise finish interacting. Avoid showing errors before users have a chance to enter a value.
+
+### Accessibility
+
+- Provide a visible `label` whenever possible. Use `aria-label` or `aria-labelledby` only when a visible label is not available.
+- Use `description` for helper text and `errorMessage` for validation feedback.
+- Pair invalid values with `isInvalid` and an actionable `errorMessage`.
+- Use native text-like `type` values so browsers can expose the right keyboard, autocomplete, and validation behavior.
+- Keep disabled fields out of the editing flow only when users cannot act on them. Use read-only fields when the value should remain focusable or copyable.
+- Do not rely on color alone to communicate validation, disabled, or read-only state.
+
+### Content
+
+- Write labels as short nouns, such as "Customer name", "Email address", or "Invoice prefix".
+- Use placeholder text for examples, not instructions that replace the label.
+- Use helper text for constraints that prevent errors, such as expected format, length, or source of the value.
+- Write error messages that name the problem and recovery step, such as "Enter a valid email address."
+- Mark optional fields only when the form otherwise implies fields are required.
+
+### Related
+
+- **[TextInput](deprecated-textinput.md)**: deprecated predecessor. Use TextField for new React usage.
+- **[Select](components-forms-select.md)**: use when users choose from a shorter closed list.
+- **[ComboBox](components-forms-combobox.md)**: use when users choose from a list and typing should filter options.
+- **[IconButton](components-buttons-iconbutton.md)**: use for compact actions inside trailing or leading content.
+
+## React
+
+```tsx
+import { TextField } from '@maxio-com/react-ui-components';
+```
+
+### State Management
+
+Use controlled state when product logic needs to validate, transform, save, or share the current value.
+
+#### Controlled
+
+```tsx
+const [value, setValue] = React.useState('');
+
+<TextField label="Customer name" value={value} onChange={setValue} />;
+```
+
+#### Uncontrolled
+
+```tsx
+<TextField label="Customer name" defaultValue="Acme Co." />
+```
+
+## Imports
+
+```tsx
+import { Body, Grid, Icon, IconButton, TextField } from "@maxio-com/react-ui-components";
+```
+
+## Prop Types
+
+### TextField
+
+| Prop | Type | Required | Default | Description | Source |
+| --- | --- | --- | --- | --- | --- |
+| `className` | `string` | no | - | Additional class name for the text field container | TextFieldProps |
+| `description` | `string` | no | - | Description for the text field. It will not be visible if there is an error message. | TextFieldProps |
+| `errorMessage` | `string` | no | - | Error message for the text field | TextFieldProps |
+| `fullWidth` | `boolean` | no | - | Ensures the input spans the full width of its parent | TextFieldProps |
+| `label` | `string` | no | - | Label for the text field | TextFieldProps |
+| `leadingElement` | `ReactNode` | no | `null` | Leading element for the text field | TextFieldProps |
+| `placeholder` | `string` | no | - | Temporary text that occupies the text field when it is empty. | TextFieldProps |
+| `size` | `"sm" \| "md" \| "lg" \| "xl"` | no | `md` | Size of the text field | TextFieldProps |
+| `trailingElement` | `ReactNode` | no | `null` | Trailing element for the text field | TextFieldProps |
+| `type` | `"search" \| "text" \| "tel" \| "url" \| "email" \| "password"` | no | - | The type of text-like input to render. | TextFieldProps |
+
+## Stories
+
+### Default
+
+Provide a visible label and use placeholder text only as an example of the expected value. Use controlled state when product logic needs to validate, transform, save, or share the current value; use defaultValue when the field can be read from a form submit or ref.
+
+```tsx
+const Default = () => <TextField
+    label="Customer name"
+    placeholder="Acme Co."
+    onChange={action('onChange')} />;
+```
+
+### With Description
+
+Use description text for helper content that users need before typing, such as expected format, length, or source of the value.
+
+```tsx
+const WithDescription = () => <TextField
+    label="Invoice prefix"
+    placeholder="INV"
+    description="Use 2-5 letters that identify this invoice series."
+    onChange={action('onChange')} />;
+```
+
+### With Icon
+
+Use an icon when the field benefits from compact visual context. Keep the icon decorative unless it is exposed through an interactive element.
+
+```tsx
+const WithIcon = () => <TextField
+    label="Signature"
+    placeholder="John Hancock"
+    onChange={action('onChange')}
+    leadingElement={<Icon variant="signature" />} />;
+```
+
+### With Text
+
+Use leading or trailing text for compact units, prefixes, suffixes, or other field-level context.
+
+```tsx
+const WithText = () => <TextField
+    label="Price"
+    placeholder="1.00"
+    onChange={action('onChange')}
+    leadingElement={<Body size="sm">€</Body>}
+    trailingElement={<Body size="sm">EUR</Body>} />;
+```
+
+### Validation
+
+Use errorMessage with isInvalid so assistive technology receives invalid state and users get actionable validation feedback.
+
+```tsx
+const Validation = () => <TextField
+    label="Email address"
+    placeholder="billing@example.com"
+    type="email"
+    isInvalid
+    errorMessage="Enter a valid email address."
+    onChange={action('onChange')} />;
+```
+
+### Disabled
+
+Use disabled fields when the value is unavailable and users cannot act on it in the current context.
+
+```tsx
+const Disabled = () => <TextField label="Billing contact" placeholder="Select an account first" isDisabled />;
+```
+
+### Read Only
+
+Use read-only fields when the value should remain selectable and readable but cannot be edited.
+
+```tsx
+const ReadOnly = () => <TextField label="Account ID" value="acct_12345" isReadOnly />;
+```
+
+### Sizes
+
+Use size to match the density and prominence of the surrounding form. Use md for most forms, sm in dense interfaces, lg for prominent form rows, and xl when the label and helper or error text should feel integrated with the field.
+
+```tsx
+const Sizes = (args) => (
+  <Grid gap={4}>
+    {(['sm', 'md', 'lg', 'xl'] as const).map((size) => (
+      <TextField key={size} {...args} size={size} />
+    ))}
+  </Grid>
+);
+```
+
+### Full Width
+
+Use fullWidth in stacked forms and responsive layouts where the field should fill the available parent width.
+
+```tsx
+const FullWidth = () => <TextField
+    label="Legal business name"
+    placeholder="Acme Corporation"
+    fullWidth
+    onChange={action('onChange')} />;
+```
+
+### With Leading Element
+
+Use an interactive leading element when the field needs a compact action inside the input. Match the IconButton size to the input size.
+
+```tsx
+const WithLeadingElement = () => <TextField
+    label="Date"
+    placeholder="mm/dd/yyyy"
+    onChange={action('onChange')}
+    leadingElement={
+      <IconButton
+        icon={<Icon variant="calendar" />}
+        variant="ghost"
+        size="sm"
+        aria-label="Select a date"
+      />
+    } />;
+```
+
+### With Trailing Element
+
+Use an interactive trailing element when the field needs a compact action inside the input. Give the action its own accessible name.
+
+```tsx
+const WithTrailingElement = () => <TextField
+    label="Password"
+    type="password"
+    onChange={action('onChange')}
+    trailingElement={
+      <IconButton
+        icon={<Icon variant="eye" />}
+        variant="ghost"
+        size="sm"
+        aria-label="Show password"
+      />
+    } />;
+```

package/dist/skills/maxio-react/references/components-grid.md

@@ -0,0 +1,140 @@
+# Grid
+
+## Usage Guidelines
+
+### Overview
+
+Grid is a layout primitive for arranging child content across rows and columns. Use it for two-dimensional layouts, and apply placement props to child Grid items when content needs to span or start and end on specific tracks.
+
+#### When to Use
+
+- Use Grid for two-dimensional layouts that need explicit rows and columns.
+- Use Grid when children need to span, start, or end on specific row or column tracks.
+- Use Grid to apply consistent gaps and alignment across a structured content area.
+
+#### When Not to Use
+
+- Do not use Grid for simple one-dimensional rows or stacks. Use Flex instead.
+- Do not use Grid placement props to change the meaningful reading order of content.
+- Do not use Grid as a replacement for semantic structure such as lists, tables, fieldsets, or navigation landmarks.
+
+### Layout Properties
+
+Choose explicit tracks for the container first, then add child placement only when an item needs to break out of the default flow.
+
+| Property                                         | Purpose                                | Usage notes                                                                                  |
+| :----------------------------------------------- | :------------------------------------- | :------------------------------------------------------------------------------------------- |
+| `templateColumns`, `templateRows`                | Defines explicit grid tracks.          | Use numbered tracks for predictable layouts, `none` to remove explicit tracks, or `subgrid`. |
+| `gap`, `gapX`, `gapY`                            | Sets spacing between items.            | Prefer gap utilities over child margins for consistent spacing.                              |
+| `autoColumns`, `autoRows`                        | Sizes automatically created tracks.    | Use when child placement creates implicit rows or columns.                                   |
+| `column`, `row`                                  | Sets how many tracks a child spans.    | Apply to child Grid items, not the parent container.                                         |
+| `columnStart`, `columnEnd`, `rowStart`, `rowEnd` | Places a child on specific grid lines. | Use start and end together when an item needs precise placement.                             |
+| `alignItems`, `justifyContent`                   | Aligns items inside their grid areas.  | Use for item alignment, not for changing source order or semantic grouping.                  |
+| `inline`                                         | Uses an inline-level grid container.   | Use only when the grid should participate in surrounding inline flow.                        |
+
+### Accessibility
+
+- Grid uses a `div` by default and does not add interactive behavior or ARIA semantics.
+- Preserve meaningful DOM order even when visual placement changes the rendered order.
+- Use semantic elements inside Grid when the content is a list, form group, navigation area, table-like data, or status region.
+- Avoid using visual placement alone to communicate relationships that need headings, labels, text, or programmatic structure.
+- Keep focus order logical when interactive children span tracks or move across responsive layouts.
+
+### Related
+
+- **[Flex](components-flex.md)**: use for one-dimensional rows, stacks, wrapping groups, and proportional item sizing.
+
+## React
+
+```tsx
+import { Grid } from '@maxio-com/react-ui-components';
+```
+
+## Imports
+
+```tsx
+import { Grid } from "@maxio-com/react-ui-components";
+```
+
+## Prop Types
+
+### Grid
+
+| Prop | Type | Required | Default | Description | Source |
+| --- | --- | --- | --- | --- | --- |
+| `alignItems` | `"center" \| "start" \| "end" \| "baseline" \| "stretch"` | no | - | Apply to child Grid components. Controls how item is positioned vertically. | TypeLiteral |
+| `autoColumns` | `"auto" \| "max" \| "min" \| "fr"` | no | - | Sets the size of columns that do not have a specified size. | TypeLiteral |
+| `autoRows` | `"auto" \| "max" \| "min" \| "fr"` | no | - | Sets the size of rows that do not have a specified size. | TypeLiteral |
+| `column` | `"auto" \| "full" \| 1 \| 2 \| 3 \| 4 \| 5 \| 6 \| 7 \| 8 \| 9 \| 10 \| 11 \| 12 \| 13` | no | - | Apply to child Grid components. Sets the number of columns the item spans. Values can be overridden by `columnStart` and `columnEnd`. | TypeLiteral |
+| `columnEnd` | `"auto" \| 1 \| 2 \| 3 \| 4 \| 5 \| 6 \| 7 \| 8 \| 9 \| 10 \| 11 \| 12 \| 13` | no | - | Apply to child Grid components. Sets the item's ending column. Needs `columnStart` to span multiple columns. | TypeLiteral |
+| `columnStart` | `"auto" \| 1 \| 2 \| 3 \| 4 \| 5 \| 6 \| 7 \| 8 \| 9 \| 10 \| 11 \| 12 \| 13` | no | - | Apply to child Grid components. Sets the item's starting column. | TypeLiteral |
+| `gap` | `0 \| 1 \| "px" \| 0.5 \| 1.5 \| 2 \| 2.5 \| 3 \| 3.5 \| 4 \| 5 \| 6 \| 7 \| 8 \| 9 \| 10 \| 11 \| 12 \| 14 \| 16 \| 20 \| 24 \| 28 \| 32 \| 36 \| 40 \| 44 \| 48 \| 52 \| 56 \| 60 \| 64 \| 72 \| 80 \| 96` | no | - | Controls the vertical and horizontal space between grid items. Can be overridden by `gapX` and `gapY`. | TypeLiteral |
+| `gapX` | `0 \| 1 \| "px" \| 0.5 \| 1.5 \| 2 \| 2.5 \| 3 \| 3.5 \| 4 \| 5 \| 6 \| 7 \| 8 \| 9 \| 10 \| 11 \| 12 \| 14 \| 16 \| 20 \| 24 \| 28 \| 32 \| 36 \| 40 \| 44 \| 48 \| 52 \| 56 \| 60 \| 64 \| 72 \| 80 \| 96` | no | - | Controls the horizontal space between grid items. | TypeLiteral |
+| `gapY` | `0 \| 1 \| "px" \| 0.5 \| 1.5 \| 2 \| 2.5 \| 3 \| 3.5 \| 4 \| 5 \| 6 \| 7 \| 8 \| 9 \| 10 \| 11 \| 12 \| 14 \| 16 \| 20 \| 24 \| 28 \| 32 \| 36 \| 40 \| 44 \| 48 \| 52 \| 56 \| 60 \| 64 \| 72 \| 80 \| 96` | no | - | Controls the vertical space between grid items. | TypeLiteral |
+| `inline` | `boolean` | no | - | Changes grid from block element to inline element. | TypeLiteral |
+| `justifyContent` | `"center" \| "start" \| "end" \| "stretch" \| "normal" \| "between" \| "around" \| "evenly"` | no | - | Apply to child Grid components. Controls how grid item is positioned horizontally. | TypeLiteral |
+| `row` | `"auto" \| "full" \| 1 \| 2 \| 3 \| 4 \| 5 \| 6 \| 7 \| 8 \| 9 \| 10 \| 11 \| 12 \| 13` | no | - | Apply to child Grid components. Sets the number of rows the item spans. Values can be overridden by `rowStart` and `rowEnd`. | TypeLiteral |
+| `rowEnd` | `"auto" \| 1 \| 2 \| 3 \| 4 \| 5 \| 6 \| 7 \| 8 \| 9 \| 10 \| 11 \| 12 \| 13` | no | - | Apply to child Grid components. Sets the item's ending row. Needs `rowStart` to span multiple columns. | TypeLiteral |
+| `rowStart` | `"auto" \| 1 \| 2 \| 3 \| 4 \| 5 \| 6 \| 7 \| 8 \| 9 \| 10 \| 11 \| 12 \| 13` | no | - | Apply to child Grid components. Sets the item's starting row. | TypeLiteral |
+| `templateColumns` | `"none" \| 1 \| 2 \| 3 \| 4 \| 5 \| 6 \| 7 \| 8 \| 9 \| 10 \| 11 \| 12 \| "subgrid"` | no | - | Sets number of columns in the grid. | TypeLiteral |
+| `templateRows` | `"none" \| 1 \| 2 \| 3 \| 4 \| 5 \| 6 \| 7 \| 8 \| 9 \| 10 \| 11 \| 12 \| "subgrid"` | no | - | Sets number of rows in the grid. | TypeLiteral |
+
+## Stories
+
+### Grid
+
+Use Grid for two-dimensional layouts that need explicit rows, columns, consistent gaps, or child item placement across tracks.
+
+```tsx
+const Default = (props) => {
+  /* Disabling eslint rule to allow destructuring of props. Since these props are meant only 
+  for controlling the span and position of child Grid components, they are destructured here to avoid 
+  passing them to the parent Grid component in the Storybook example. */
+
+  const {
+    column,
+    columnStart,
+    columnEnd,
+    row,
+    rowStart,
+    rowEnd,
+    justifyContent,
+    alignItems,
+    ...restProps
+  } = props;
+
+  const gridItemProps = {
+    justifyContent,
+    alignItems,
+    style: gridItemStyles,
+  };
+
+  return (
+    <Grid {...restProps} className="maxio-body-sm">
+      <Grid
+        key="1"
+        style={{
+          ...gridItemStyles,
+          backgroundColor: '#0042FF',
+          color: 'white',
+        }}
+        justifyContent={justifyContent}
+        alignItems={alignItems}
+        column={column}
+        columnStart={columnStart}
+        columnEnd={columnEnd}
+        row={row}
+        rowStart={rowStart}
+        rowEnd={rowEnd}
+      >
+        1
+      </Grid>
+      {gridItemsArray.map((_, index) => (
+        <Grid key={index + 2} {...gridItemProps}>
+          {index + 2}
+        </Grid>
+      ))}
+    </Grid>
+  );
+};
+```

package/dist/skills/maxio-react/references/components-icon.md

@@ -0,0 +1,169 @@
+# Icon
+
+## Usage Guidelines
+
+### Overview
+
+Icon renders Maxio custom icons, approved brand icons, and supported Font Awesome fallback icons. Use icons as decorative or supporting visual cues alongside text; use IconButton when the icon itself performs an action.
+
+#### When to Use
+
+- Use Icon to reinforce nearby labels, statuses, navigation items, or actions with a compact visual cue.
+- Use Maxio kit icons before reaching for Font Awesome fallback icons.
+- Use approved brand icons when a third-party product or integration needs recognizable brand treatment.
+- Use Icon inside components that already provide semantics, such as Button, IconButton, Link, Tag, or TextField.
+
+#### When Not to Use
+
+- Do not use Icon as the only label for an action. Use IconButton for icon-only controls so the accessible name is explicit.
+- Do not use Icon for illustration, empty states, logos, or larger brand marks. Use the appropriate image or logo treatment instead.
+- Do not override brand or duotone brand colors.
+- Do not rely on icon shape or color alone to communicate status, severity, or required action.
+
+### Variants
+
+Choose the icon source before choosing size or color.
+
+| Variants         | Purpose                                      | Usage notes                                                                            |
+| :--------------- | :------------------------------------------- | :------------------------------------------------------------------------------------- |
+| Maxio kit        | Product UI symbols maintained by Maxio.      | Use first for common interface actions, statuses, and navigation.                      |
+| Brand            | Approved single-color brand icons.           | Use only for the represented brand or integration. Brand colors are built in.          |
+| Duotone brand    | Approved two-tone brand icons.               | Use only for represented brands that need duotone treatment. Do not override colors.   |
+| Font Awesome     | Supported fallback icons outside the kit.    | Use only when no Maxio kit icon fits. Confirm the icon is available in the loaded kit. |
+| Semantic color   | Maxio icon color modifiers.                  | Use for status or emphasis on non-brand icons, and pair meaning with text.             |
+| `xs`, `md`, `lg` | Font Awesome size utilities exposed by Icon. | Match surrounding component density and avoid oversized standalone icons.              |
+
+### Behavior
+
+- Icon is static visual content and does not add interaction by itself.
+- Pair Icon with Button, IconButton, Link, or another interactive component when the surrounding pattern is interactive.
+- The `color` prop adds a Maxio semantic color modifier to Maxio kit and Font Awesome fallback icons, but not to brand icons.
+- The `variant` prop determines the Font Awesome class family: kit, duotone kit, or sharp regular fallback.
+
+### Accessibility
+
+- Treat icons as decorative when nearby visible text already communicates the same meaning.
+- Provide visible text, a label, or surrounding semantic markup for the meaning the icon supports.
+- Use IconButton instead of Icon when the icon alone triggers an action.
+- Do not rely on icon color alone to communicate status or severity.
+- Avoid standalone meaningful icons unless the surrounding component supplies an accessible name or description.
+
+### Related
+
+- **[IconButton](components-buttons-iconbutton.md)**: use for icon-only actions.
+- **[Button](components-buttons-button.md)**: use for actions with visible labels and optional leading or trailing icons.
+- **[Link](components-link.md)**: use for navigation with optional supporting icons.
+- **[Logo](components-logo.md)**: use for Maxio brand marks.
+
+## React
+
+```tsx
+import { Icon } from '@maxio-com/react-ui-components';
+```
+
+### Available Icons
+
+### Custom Maxio Icons
+
+Use the Maxio custom icon set first for product UI. These icons render with the Font Awesome kit family.
+
+```tsx
+<Icon variant="address-card" />
+```
+
+### Brand Icons
+
+Brand icons render with their designated brand colors. Do not pass semantic color for brand icons.
+
+```tsx
+<Icon variant="dropbox" />
+```
+
+### Duotone Brand Icons
+
+Duotone brand icons render with the `fa-kit-duotone` family and approved two-color treatment. Do not override duotone brand colors.
+
+```tsx
+<Icon variant="avalara" />
+```
+
+### Font Awesome Fallback Icons
+
+If the Maxio kit does not include an appropriate icon, use a supported Font Awesome fallback icon. Fallback icons render with `fa-sharp`, `fa-regular`, and `fa-<icon-name>` classes.
+
+```tsx
+<Icon variant="life-ring" />
+```
+
+## Imports
+
+```tsx
+import { Icon } from "@maxio-com/react-ui-components";
+```
+
+## Prop Types
+
+### Icon
+
+| Prop | Type | Required | Default | Description | Source |
+| --- | --- | --- | --- | --- | --- |
+| `className` | `string` | no | - | Class name for the main container | TypeLiteral |
+| `color` | `string` | no | - | The icon color | TypeLiteral |
+| `size` | `"md" \| "lg" \| "xs"` | no | - | The icon size | TypeLiteral |
+| `variant` | `string` | yes | - | The icon variant | TypeLiteral |
+
+## Stories
+
+### Custom Maxio Icon
+
+Use a Maxio kit icon when a small visual cue reinforces nearby text, status, or navigation. Keep the icon decorative unless surrounding text supplies the accessible meaning.
+
+```tsx
+const Default = () => <Icon variant="home" size="md" color="primary" />;
+```
+
+### Colored
+
+Use semantic color when an icon needs to match nearby status, tone, or visual emphasis. Do not use color as the only way to communicate meaning.
+
+```tsx
+const Colored = () => <Icon variant="info-circle-fill" size="md" color="info" />;
+```
+
+### Brand Icon
+
+Use approved brand icons with their built-in brand colors. The color prop is intentionally ignored for brand icons.
+
+```tsx
+const BrandIcon = () => <Icon variant={BRAND_ICONS[1]} size="md" />;
+```
+
+### Duotone Brand Icon
+
+Use duotone brand icons only for brands that have an approved duotone asset. Keep the generated `fa-kit-duotone` class so Font Awesome renders both tones.
+
+```tsx
+const DuotoneBrandIcon = () => <Icon variant={BRAND_ICONS_DUOTONE[0]} size="md" />;
+```
+
+### Font Awesome Icon
+
+Use a supported Font Awesome fallback icon only when the Maxio kit does not include an appropriate icon.
+
+```tsx
+const FontAwesomeIcon = () => <Icon variant={NON_KIT_ICONS_LIST[2]} size="md" color="secondary" />;
+```
+
+### Sizes
+
+Use size to match the density of the surrounding UI. Most product interfaces should use the default surrounding component size rather than oversized icons.
+
+```tsx
+const Sizes = (args) => (
+  <div style={{ display: 'flex', alignItems: 'center', gap: '1rem' }}>
+    {(['xs', 'md', 'lg'] as const).map((size) => (
+      <Icon key={size} {...args} size={size} />
+    ))}
+  </div>
+);
+```