@boostdev/design-system-components 1.2.8 → 2.1.0

package/dist/native/index.cjs

@@ -2139,6 +2139,7 @@ function Button({
   iconStart,
   iconEnd,
   disabled = false,
+  isIconOnly = false,
   onPress,
   accessibilityLabel,
   style
@@ -2151,9 +2152,11 @@ function Button({
   const isOutline = variant === "outline" || variant === "ghost";
   const containerStyle = {
     height,
-    paddingHorizontal: px,
+    paddingHorizontal: isIconOnly ? import_native.spacing.xs : px,
     borderRadius: radius,
     opacity: disabled ? 0.4 : 1,
+    // Icon-only: square with equal xs padding on both axes.
+    ...isIconOnly && { aspectRatio: 1, paddingVertical: import_native.spacing.xs },
     ...variant === "default" && { backgroundColor: primaryColor },
     ...isOutline && {
       backgroundColor: "transparent",
@@ -2173,7 +2176,7 @@ function Button({
       style: ({ pressed }) => [styles24.pressable, containerStyle, pressed && { opacity: 0.75 }, style],
       children: [
         iconStart && /* @__PURE__ */ (0, import_jsx_runtime27.jsx)(import_react_native27.View, { importantForAccessibility: "no-hide-descendants", accessibilityElementsHidden: true, children: iconStart }),
-        children && /* @__PURE__ */ (0, import_jsx_runtime27.jsx)(import_react_native27.Text, { style: [styles24.label, { fontSize, color: textColor }], children }),
+        children && (isIconOnly ? children : /* @__PURE__ */ (0, import_jsx_runtime27.jsx)(import_react_native27.Text, { style: [styles24.label, { fontSize, color: textColor }], children })),
         iconEnd && /* @__PURE__ */ (0, import_jsx_runtime27.jsx)(import_react_native27.View, { importantForAccessibility: "no-hide-descendants", children: iconEnd })
       ]
     }

package/dist/native/index.d.cts

@@ -293,11 +293,13 @@ interface ButtonProps {
     iconStart?: ReactNode;
     iconEnd?: ReactNode;
     disabled?: boolean;
+    /** Forces a 1:1 aspect ratio with minimal padding for icon-only buttons. Requires `accessibilityLabel`. */
+    isIconOnly?: boolean;
     onPress?: () => void;
     accessibilityLabel?: string;
     style?: StyleProp<ViewStyle>;
 }
-declare function Button({ children, variant, size, iconStart, iconEnd, disabled, onPress, accessibilityLabel, style, }: Readonly<ButtonProps>): react_jsx_runtime.JSX.Element;
+declare function Button({ children, variant, size, iconStart, iconEnd, disabled, isIconOnly, onPress, accessibilityLabel, style, }: Readonly<ButtonProps>): react_jsx_runtime.JSX.Element;
 
 interface RatingProps {
     value: number;

package/dist/native/index.d.ts

@@ -293,11 +293,13 @@ interface ButtonProps {
     iconStart?: ReactNode;
     iconEnd?: ReactNode;
     disabled?: boolean;
+    /** Forces a 1:1 aspect ratio with minimal padding for icon-only buttons. Requires `accessibilityLabel`. */
+    isIconOnly?: boolean;
     onPress?: () => void;
     accessibilityLabel?: string;
     style?: StyleProp<ViewStyle>;
 }
-declare function Button({ children, variant, size, iconStart, iconEnd, disabled, onPress, accessibilityLabel, style, }: Readonly<ButtonProps>): react_jsx_runtime.JSX.Element;
+declare function Button({ children, variant, size, iconStart, iconEnd, disabled, isIconOnly, onPress, accessibilityLabel, style, }: Readonly<ButtonProps>): react_jsx_runtime.JSX.Element;
 
 interface RatingProps {
     value: number;

package/dist/native/index.js

@@ -2087,6 +2087,7 @@ function Button({
   iconStart,
   iconEnd,
   disabled = false,
+  isIconOnly = false,
   onPress,
   accessibilityLabel,
   style
@@ -2099,9 +2100,11 @@ function Button({
   const isOutline = variant === "outline" || variant === "ghost";
   const containerStyle = {
     height,
-    paddingHorizontal: px,
+    paddingHorizontal: isIconOnly ? spacing.xs : px,
     borderRadius: radius,
     opacity: disabled ? 0.4 : 1,
+    // Icon-only: square with equal xs padding on both axes.
+    ...isIconOnly && { aspectRatio: 1, paddingVertical: spacing.xs },
     ...variant === "default" && { backgroundColor: primaryColor },
     ...isOutline && {
       backgroundColor: "transparent",
@@ -2121,7 +2124,7 @@ function Button({
       style: ({ pressed }) => [styles24.pressable, containerStyle, pressed && { opacity: 0.75 }, style],
       children: [
         iconStart && /* @__PURE__ */ jsx27(View22, { importantForAccessibility: "no-hide-descendants", accessibilityElementsHidden: true, children: iconStart }),
-        children && /* @__PURE__ */ jsx27(Text20, { style: [styles24.label, { fontSize, color: textColor }], children }),
+        children && (isIconOnly ? children : /* @__PURE__ */ jsx27(Text20, { style: [styles24.label, { fontSize, color: textColor }], children })),
         iconEnd && /* @__PURE__ */ jsx27(View22, { importantForAccessibility: "no-hide-descendants", children: iconEnd })
       ]
     }

package/dist/web-components/{chunk-DZRSJGPB.js → chunk-3S42DZ7W.js}

@@ -30,7 +30,7 @@ var bdcCss = `
     initial-value: 0 0 0 0 transparent;
   }
 
-  @layer component {
+  @layer boostdev.component {
     :root {
       --bdc-outline_border: none;
 

package/dist/web-components/{chunk-3REOIRDW.js → chunk-N3TN6WCH.js}

@@ -90,6 +90,23 @@ var BdsButton = class extends i2 {
       animation: pulse 3s infinite;
     }
 
+    /* Icon-only: square (1:1), equal xs padding on both axes — composes with
+       any variant/size. box-sizing: border-box keeps the outer box at
+       --button_height; without it, all: unset reverts to content-box and
+       padding-block would stretch the button past its declared height.
+       Slotted child fills the content area (button height minus the two
+       padding sides) so SVG icons scale with button size. */
+    .button.is-icon-only {
+      aspect-ratio: 1;
+      box-sizing: border-box;
+      padding: var(--bds-space_xs);
+    }
+
+    :host([is-icon-only]) ::slotted(*) {
+      inline-size: 100%;
+      block-size: 100%;
+    }
+
     /* SVG icon colour */
     .button svg {
       --icon__stroke: currentcolor;
@@ -117,6 +134,12 @@ var BdsButton = class extends i2 {
       transition: var(--bds-animation_transition);
     }
 
+    /* Icon-only: zero out icon slot margins so icon centres */
+    .button.is-icon-only .icon-start.has-content,
+    .button.is-icon-only .icon-end.has-content {
+      margin-inline: 0;
+    }
+
     /* Hover icon animation */
     @media (hover: hover) and (pointer: fine) {
       .button:hover .icon-start svg,
@@ -164,6 +187,7 @@ var BdsButton = class extends i2 {
     target: { type: String },
     rel: { type: String },
     hasPulse: { type: Boolean, attribute: "has-pulse", reflect: true },
+    isIconOnly: { type: Boolean, attribute: "is-icon-only", reflect: true },
     type: { type: String },
     ariaLabel: { type: String, attribute: "aria-label" },
     // Internal state
@@ -176,6 +200,7 @@ var BdsButton = class extends i2 {
     this.size = "medium";
     this.disabled = false;
     this.hasPulse = false;
+    this.isIconOnly = false;
     this.type = "button";
     this.ariaLabel = null;
     this._iconStartFilled = false;
@@ -191,7 +216,7 @@ var BdsButton = class extends i2 {
     }
   }
   get _classes() {
-    return `button ${this.variant} ${this.size}${this.hasPulse ? " has-pulse" : ""}`;
+    return `button ${this.variant} ${this.size}${this.hasPulse ? " has-pulse" : ""}${this.isIconOnly ? " is-icon-only" : ""}`;
   }
   _handleAnchorClick(e) {
     if (this.disabled) {

package/dist/web-components/globals.js

@@ -1 +1 @@
-import "./chunk-DZRSJGPB.js";
+import "./chunk-3S42DZ7W.js";

package/dist/web-components/index.js

@@ -69,7 +69,7 @@ import {
 } from "./chunk-UFFCKVZE.js";
 import {
   BdsButton
-} from "./chunk-3REOIRDW.js";
+} from "./chunk-N3TN6WCH.js";
 import {
   BdsCollapsible
 } from "./chunk-6I2DBFQ7.js";
@@ -101,7 +101,7 @@ import {
   BdsSectionHeader
 } from "./chunk-Y4MAXTMA.js";
 import "./chunk-QPOKHLMQ.js";
-import "./chunk-DZRSJGPB.js";
+import "./chunk-3S42DZ7W.js";
 import {
   BdsAlert
 } from "./chunk-BX3IPVOB.js";

package/dist/web-components/interaction/bds-button.d.ts

@@ -14,6 +14,7 @@ type ButtonSize = 'small' | 'medium' | 'large';
  *   target    — forwarded to <a> when href is set
  *   rel       — forwarded to <a> when href is set
  *   has-pulse — boolean, enables the pulse ring animation
+ *   is-icon-only — boolean, forces a 1:1 aspect ratio with minimal xs padding (requires aria-label)
  *   type      — "button" (default) | "submit" | "reset"
  *
  * Slots:
@@ -59,6 +60,11 @@ declare class BdsButton extends LitElement {
             attribute: string;
             reflect: boolean;
         };
+        isIconOnly: {
+            type: BooleanConstructor;
+            attribute: string;
+            reflect: boolean;
+        };
         type: {
             type: StringConstructor;
         };
@@ -80,6 +86,7 @@ declare class BdsButton extends LitElement {
     target: string | undefined;
     rel: string | undefined;
     hasPulse: boolean;
+    isIconOnly: boolean;
     type: 'button' | 'submit' | 'reset';
     ariaLabel: string | null;
     private _iconStartFilled;

package/dist/web-components/interaction/bds-button.js

@@ -1,6 +1,6 @@
 import {
   BdsButton
-} from "../chunk-3REOIRDW.js";
+} from "../chunk-N3TN6WCH.js";
 import "../chunk-LGEZYFUU.js";
 export {
   BdsButton

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@boostdev/design-system-components",
-  "version": "1.2.8",
+  "version": "2.1.0",
   "description": "BoostDev React component library: accessible, token-driven components built on @boostdev/design-system-foundation",
   "keywords": [
     "React",
@@ -284,7 +284,7 @@
     "changelog:unreleased": "pnpm exec git-cliff --unreleased"
   },
   "devDependencies": {
-    "@boostdev/design-system-foundation": "^1.0.6",
+    "@boostdev/design-system-foundation": "^2.0.0",
     "@modelcontextprotocol/sdk": "^1.27.0",
     "@storybook/addon-docs": "8.6.14",
     "@storybook/addon-essentials": "^8.6.14",
@@ -319,7 +319,7 @@
     "zod": "^4.3.6"
   },
   "peerDependencies": {
-    "@boostdev/design-system-foundation": ">=1.0.6",
+    "@boostdev/design-system-foundation": ">=2.0.0",
     "react": ">=18",
     "react-dom": ">=18",
     "react-native": ">=0.70"

package/src/components/interaction/Button/Button.mdx

@@ -1,4 +1,4 @@
-import { Meta, Canvas, ArgTypes } from '@storybook/blocks';
+import { Meta, Canvas, ArgTypes, Controls } from '@storybook/blocks';
 import * as Stories from './Button.stories';
 
 <Meta of={Stories} />
@@ -7,52 +7,94 @@ import * as Stories from './Button.stories';
 
 Primary interactive element for triggering actions. Renders as `<button>` or `<a>` depending on whether `href` is provided.
 
+## Playground
+
+Use the Controls panel below to try every prop live. `iconStart` and `iconEnd` are backed by a small set of example icons — in your app, pass any `ReactNode` (SVG, icon component, emoji, etc.).
+
+<Canvas of={Stories.Playground} />
+<Controls of={Stories.Playground} />
+
 ## When to use
-- The main action on a page or dialog (`default`)
-- Secondary or ghost actions (`ghost`)
+- The main action on a page or dialog (`variant="default"`)
+- Secondary or less emphatic actions (`variant="outline"`)
 - Navigation that should look like an action (`href` → renders as `<a>`)
 
-> **Form actions:** When using buttons in a form (submit, reset, cancel), always wrap them in a `ButtonContainer` component. This provides consistent spacing, alignment, and responsive layout for form actions. Use `variant="flow"` for step navigation or `variant="card"` for single-form submissions.
+> **Form actions:** When using buttons in a form (submit, reset, cancel), always wrap them in a `ButtonContainer` component. It provides consistent spacing, alignment, and responsive layout. Use `variant="flow"` for step navigation or `variant="card"` for single-form submissions.
 
 ## When not to use
-- Navigation to another page when it reads naturally as a link — use `Link` instead
-- When the action is purely icon-based without a label — ensure `aria-label` is set
+- Navigation to another page when it reads naturally as a link — use `Link` instead.
+- A purely icon-based action without a label — allowed, but always set `aria-label` **and** prefer `isIconOnly` so the shape reflects the intent.
 
-## Examples
+## Variants
 
-### All variants & sizes
-<Canvas of={Stories.AllVariants} />
+Two visual styles:
+
+- **`default`** — filled with `--button_color`, text in `--button_on-color`. Hover inverts: background becomes page surface, text becomes `--bdc_color`-on-background. Use for primary actions.
+- **`outline`** — transparent background, border and text both use `--button_color--on-bg` (a text-safe variant of the identity colour). Hover fills with `--button_color`. Use for secondary actions. `'ghost'` remains as a deprecated alias.
 
-### Default
 <Canvas of={Stories.Default} />
+<Canvas of={Stories.Outline} />
+
+## Sizes
 
-### Ghost
-<Canvas of={Stories.Ghost} />
+Size controls both height and horizontal padding. `large` also bumps font-size to the h3 scale.
 
-### Sizes
 <Canvas of={Stories.Small} />
 <Canvas of={Stories.Medium} />
 <Canvas of={Stories.Large} />
 
-### As a link
+## All variants × sizes
+
+<Canvas of={Stories.AllVariants} />
+
+## Icons
+
+Pass any `ReactNode` to `iconStart` or `iconEnd`. Icons inherit the button's `currentColor`, so they work on both filled and outline variants automatically.
+
+<Canvas of={Stories.WithIconStart} />
+<Canvas of={Stories.WithIconEnd} />
+<Canvas of={Stories.WithBothIcons} />
+
+### Icon-only (1:1 aspect ratio)
+
+Set `isIconOnly` to render a square button with equal `xs` padding on both axes — composable with any `variant`. The icon sits centred; the button's height (from `size`) determines both width and height. Always pair with `aria-label` — there's no visible text for assistive tech to read.
+
+<Canvas of={Stories.IconOnly} />
+<Canvas of={Stories.IconOnlyOutline} />
+<Canvas of={Stories.AllIconOnly} />
+
+## Rendered as a link
+
+Provide `href` to render as an `<a>` with button styling. `disabled` on a link sets `aria-disabled="true"` and removes it from the tab order (the `href` is also dropped so the link is non-navigable while disabled).
+
 <Canvas of={Stories.AsLink} />
 
-### With icons
-<Canvas of={Stories.WithIcons} />
+## Pulse (CTA emphasis)
+
+`hasPulse` adds a subtle scale-and-glow animation for call-to-action emphasis. Respects `prefers-reduced-motion`.
 
-### Pulse (CTA emphasis)
 <Canvas of={Stories.WithPulse} />
 
-### Disabled
+## Disabled
+
 <Canvas of={Stories.Disabled} />
 
+## HTML attribute forwarding
+
+`Button` spreads all unrecognised props onto the underlying element (`<button>` when `href` is absent, `<a>` when `href` is provided). Every standard HTML attribute for the target element is accepted as a prop, including:
+
+- **Form-related (on `<button>`)**: `type` (default `"button"` — set to `"submit"` for form submission or `"reset"` to reset), `form`, `formAction`, `formMethod`, `formNoValidate`, `formTarget`, `name`, `value`, `autoFocus`.
+- **Link-related (on `<a>`)**: `download`, `hreflang`, `ping`, `referrerPolicy` (plus the explicit `target` and `rel` props).
+- **Universal**: `id`, `style`, `tabIndex`, `title`, `role`, all `aria-*` attributes, all `data-*` attributes, and every DOM event handler (`onFocus`, `onBlur`, `onKeyDown`, `onMouseEnter`, etc.).
+
+> **Gotcha:** the rendered DOM shows `type="button"` by default because that is the component default — it is **not** forced. Pass `type="submit"` to wire the button to a parent `<form>`'s `onSubmit` handler (preferred over an `onClick` shim, because it preserves Enter-to-submit, native form validation, and assistive-tech semantics).
+
 ## Props
 
 <ArgTypes of={Stories} />
 
 ## CSS variables
 
-
 <table>
 <thead>
 <tr><th>Variable</th><th>Default</th><th>Description</th></tr>
@@ -60,19 +102,32 @@ Primary interactive element for triggering actions. Renders as `<button>` or `<a
 <tbody>
 <tr><td>`--button_color`</td><td>`var(--bds-color_interactive)`</td><td>Identity colour — fills default, outlines outline. Set this to re-theme.</td></tr>
 <tr><td>`--button_on-color`</td><td>`var(--bds-color_on-interactive)`</td><td>Text/icon colour on the button. Pair with `--button_color`.</td></tr>
-<tr><td>`--button_color--on-bg`</td><td>`var(--bds-color_interactive_on-bg)`</td><td>Text-safe variant of `--button_color` for outline variant text/border</td></tr>
-<tr><td>`--button_radius`</td><td>`var(--bds-border_radius--full)`</td><td>Button border radius</td></tr>
-<tr><td>`--button_bg--hover`</td><td>`var(--bds-color_bg)`</td><td>Default variant background on hover</td></tr>
-<tr><td>`--button_text--hover`</td><td>`var(--bds-color_interactive_on-bg)`</td><td>Default variant text colour on hover</td></tr>
-<tr><td>`--button_bg--outline-hover`</td><td>`var(--button_color)`</td><td>Outline variant background on hover</td></tr>
-<tr><td>`--button_text--outline-hover`</td><td>`var(--button_on-color)`</td><td>Outline variant text colour on hover</td></tr>
+<tr><td>`--button_color--on-bg`</td><td>`var(--bds-color_interactive_on-bg)`</td><td>Text-safe variant of `--button_color` for outline variant text/border.</td></tr>
+<tr><td>`--button_radius`</td><td>`var(--bds-border_radius--full)`</td><td>Button border radius.</td></tr>
+<tr><td>`--button_height`</td><td>`3em` (medium)</td><td>Button height. Also drives the width when `isIconOnly` is set.</td></tr>
+<tr><td>`--button_bg--hover`</td><td>`var(--bds-color_bg)`</td><td>Default variant background on hover.</td></tr>
+<tr><td>`--button_text--hover`</td><td>`var(--bds-color_interactive_on-bg)`</td><td>Default variant text colour on hover.</td></tr>
+<tr><td>`--button_bg--outline-hover`</td><td>`var(--button_color)`</td><td>Outline variant background on hover.</td></tr>
+<tr><td>`--button_text--outline-hover`</td><td>`var(--button_on-color)`</td><td>Outline variant text colour on hover.</td></tr>
+<tr><td>`--button_pulse-color`</td><td>`var(--button_color)`</td><td>Halo colour for the pulse animation.</td></tr>
 </tbody>
 </table>
 
+### Re-theming
+
+Change the two identity custom properties to re-theme both variants at once:
+
+```css
+.danger-zone .button {
+  --button_color:    var(--bds-color_error);
+  --button_on-color: var(--bds-color_on-error);
+}
+```
 
 ## Accessibility
 
-- Always provide children or `aria-label` for icon-only buttons
-- Disabled state sets `aria-disabled="true"` and removes the element from the tab order
-- When rendered as `<a>`, `href` must point to a valid destination
-- `hasPulse` animation respects `prefers-reduced-motion`
+- Always provide children **or** `aria-label` — icon-only buttons without an accessible name are a WCAG failure.
+- Disabled state sets `aria-disabled="true"` and removes the element from the tab order.
+- When rendered as `<a>`, `href` must point to a valid destination.
+- `hasPulse` animation respects `prefers-reduced-motion`.
+- Minimum hit target is enforced via the size tokens — even `size="small"` at 2.25em font-size satisfies the 44 × 44px guideline at standard root-font sizes.

package/src/components/interaction/Button/Button.module.css

@@ -27,7 +27,7 @@
   }
 }
 
-@layer component {
+@layer boostdev.component {
   .button,
   .button[href] {
     all: unset;
@@ -96,6 +96,25 @@
     animation: pulse 3s infinite;
   }
 
+  /* Icon-only: square (1:1), equal xs padding on both axes — composes with
+     any variant/size. `box-sizing: border-box` keeps the outer box at
+     `--button_height`; without it, `all: unset` reverts to content-box and
+     `padding-block` would stretch the button past its declared height.
+     Direct child fills the content area (button height minus the two
+     padding sides) so SVG icons scale with button size.
+     Nested icon overrides live after .iconStart/.iconEnd below to satisfy
+     stylelint's no-descending-specificity rule. */
+  .button.--iconOnly {
+    aspect-ratio: 1;
+    box-sizing: border-box;
+    padding: var(--bds-space_xxs);
+  }
+
+  .button.--iconOnly > * {
+    inline-size: 100%;
+    block-size: 100%;
+  }
+
   .button[href] {
     text-decoration: none;
   }
@@ -122,6 +141,11 @@
     transition: var(--bds-animation_transition);
   }
 
+  .button.--iconOnly .iconStart,
+  .button.--iconOnly .iconEnd {
+    margin-inline: 0;
+  }
+
   @media (hover: hover) and (pointer: fine) {
     .button:hover .iconStart svg {
       animation: fadeZoom 2s ease-out infinite;

package/src/components/interaction/Button/Button.native.mdx

@@ -1,4 +1,4 @@
-import { Meta, Canvas, ArgTypes } from '@storybook/blocks';
+import { Meta, Canvas, ArgTypes, Controls } from '@storybook/blocks';
 import * as Stories from './Button.native.stories';
 
 <Meta of={Stories} />
@@ -12,7 +12,7 @@ React Native button component using `Pressable`. Matches the web `Button` API as
 ## Usage
 
 ```tsx
-import { Button } from '@boostdev/components';
+import { Button } from '@boostdev/design-system-components';
 
 <Button variant="default" size="medium" onPress={() => console.log('pressed')}>
   Save
@@ -22,30 +22,48 @@ import { Button } from '@boostdev/components';
 Wrap your tree in `ThemeProvider` (once, at the app root):
 
 ```tsx
-import { ThemeProvider } from '@boostdev/components/native/ThemeContext';
+import { ThemeProvider } from '@boostdev/design-system-components/native/ThemeContext';
 
 export default function App() {
   return <ThemeProvider><YourApp /></ThemeProvider>;
 }
 ```
 
-## Examples
+## Playground
 
-### All variants & sizes
-<Canvas of={Stories.AllVariants} />
+<Canvas of={Stories.Playground} />
+<Controls of={Stories.Playground} />
+
+## Variants
 
-### Default
 <Canvas of={Stories.Default} />
+<Canvas of={Stories.Outline} />
 
-### Ghost
-<Canvas of={Stories.Ghost} />
+## Sizes
 
-### Sizes
 <Canvas of={Stories.Small} />
 <Canvas of={Stories.Medium} />
 <Canvas of={Stories.Large} />
 
-### Disabled
+## Icons
+
+<Canvas of={Stories.WithIconStart} />
+<Canvas of={Stories.WithIconEnd} />
+
+### Icon-only (1:1 aspect ratio)
+
+Set `isIconOnly` to render a square button with equal `spacing.xs` padding on both axes. Composable with any `variant`. Always pair with `accessibilityLabel` for assistive tech.
+
+<Canvas of={Stories.IconOnly} />
+<Canvas of={Stories.IconOnlyOutline} />
+<Canvas of={Stories.AllIconOnly} />
+
+## All variants × sizes
+
+<Canvas of={Stories.AllVariants} />
+
+## Disabled
+
 <Canvas of={Stories.Disabled} />
 
 ## Props
@@ -56,13 +74,14 @@ export default function App() {
 
 | Prop | Type | Default | Description |
 |------|------|---------|-------------|
-| `variant` | `"default" \| "ghost"` | `"default"` | Visual style |
-| `size` | `"small" \| "medium" \| "large"` | `"medium"` | Height and padding scale |
+| `variant` | `"default" \| "outline"` | `"default"` | Visual style (`"ghost"` is a deprecated alias for `"outline"`) |
+| `size` | `"small" \| "medium" \| "large"` | `"medium"` | Height and horizontal padding |
 | `disabled` | boolean | `false` | Prevents interaction, reduces opacity |
 | `onPress` | `() => void` | — | Called when the button is pressed |
 | `iconStart` | `ReactNode` | — | Icon before the label |
 | `iconEnd` | `ReactNode` | — | Icon after the label |
-| `accessibilityLabel` | string | — | Screen reader label (required for icon-only buttons) |
+| `isIconOnly` | boolean | `false` | 1:1 aspect ratio with equal `spacing.xs` padding on both axes. Requires `accessibilityLabel`. |
+| `accessibilityLabel` | string | — | Screen-reader label (required for icon-only buttons) |
 | `style` | `StyleProp<ViewStyle>` | — | Override container styles |
 
 ## Accessibility

package/src/components/interaction/Button/Button.native.spec.tsx

@@ -32,4 +32,24 @@ describe('Button (native)', () => {
     expect(screen.getByRole('button')).toBeInTheDocument();
     expect(screen.getByTestId('icon-end')).toBeInTheDocument();
   });
+
+  it('renders icon-only button with accessibilityLabel and icon as children (not wrapped in Text)', () => {
+    renderWithTheme(
+      <Button isIconOnly accessibilityLabel="Confirm">
+        <span data-testid="icon-only">✓</span>
+      </Button>
+    );
+    expect(screen.getByRole('button', { name: 'Confirm' })).toBeInTheDocument();
+    expect(screen.getByTestId('icon-only')).toBeInTheDocument();
+  });
+
+  it('renders icon-only with outline variant', () => {
+    renderWithTheme(
+      <Button isIconOnly variant="outline" accessibilityLabel="Confirm">
+        <span data-testid="icon-only-outline">✓</span>
+      </Button>
+    );
+    expect(screen.getByRole('button', { name: 'Confirm' })).toBeInTheDocument();
+    expect(screen.getByTestId('icon-only-outline')).toBeInTheDocument();
+  });
 });