@boostdev/design-system-components 2.0.0 → 2.1.0

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-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/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";

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": "2.0.0",
+  "version": "2.1.0",
   "description": "BoostDev React component library: accessible, token-driven components built on @boostdev/design-system-foundation",
   "keywords": [
     "React",

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,62 +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 (`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
-
-## HTML attribute forwarding
+- 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.
 
-`Button` spreads all unrecognised props onto the underlying element (`<button>` when `href` is absent, `<a>` when `href` is provided). That means every standard HTML attribute for the target element is accepted as a prop, including:
+## Variants
 
-- **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).
+Two visual styles:
 
-## Examples
+- **`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.
 
-### All variants & sizes
-<Canvas of={Stories.AllVariants} />
-
-### Default
 <Canvas of={Stories.Default} />
+<Canvas of={Stories.Outline} />
+
+## Sizes
 
-### Outline
-<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>
@@ -70,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

@@ -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} />
@@ -29,23 +29,41 @@ export default function App() {
 }
 ```
 
-## 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();
+  });
 });

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

@@ -1,34 +1,113 @@
 import React from 'react';
+import type { ReactNode } from 'react';
 import type { Meta, StoryObj } from '@storybook/react';
 import { ThemeProvider } from '../../../native/ThemeContext';
-import { Button } from './Button.native';
+import { Button, type ButtonProps } from './Button.native';
 
-const meta = {
+const CheckIcon = (
+  <svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24" width="20" height="20" aria-hidden>
+    <path d="M12 0a12 12 0 1 0 12 12A12 12 0 0 0 12 0Zm6.93 8.2-6.85 9.29a1 1 0 0 1-1.43.19l-4.89-3.91a1 1 0 0 1-.15-1.41A1 1 0 0 1 7 12.21l4.08 3.26L17.32 7a1 1 0 0 1 1.39-.21 1 1 0 0 1 .22 1.41Z" fill="currentColor"/>
+  </svg>
+);
+
+const ArrowRight = <span aria-hidden>→</span>;
+const ArrowLeft = <span aria-hidden>←</span>;
+
+const iconMap = {
+  none: undefined,
+  check: CheckIcon,
+  arrowRight: ArrowRight,
+  arrowLeft: ArrowLeft,
+};
+
+type IconKey = keyof typeof iconMap;
+
+type ButtonStoryArgs = Omit<ButtonProps, 'iconStart' | 'iconEnd' | 'children'> & {
+  iconStart?: IconKey;
+  iconEnd?: IconKey;
+  children?: ReactNode;
+};
+
+const meta: Meta<ButtonStoryArgs> = {
   tags: ['!stable', 'alpha'],
   title: 'React Native/Interaction/Button',
   component: Button,
   decorators: [(Story) => <ThemeProvider colorScheme="light"><Story /></ThemeProvider>],
   parameters: { layout: 'centered' },
   argTypes: {
-    variant: { control: 'select', options: ['default', 'ghost'] },
-    size: { control: 'select', options: ['small', 'medium', 'large'] },
+    variant: {
+      control: 'select',
+      options: ['default', 'outline'],
+      description: 'Visual style. `default` is filled; `outline` is transparent with a border.',
+      table: { defaultValue: { summary: 'default' } },
+    },
+    size: {
+      control: 'select',
+      options: ['small', 'medium', 'large'],
+      description: 'Height + horizontal padding.',
+      table: { defaultValue: { summary: 'medium' } },
+    },
+    iconStart: {
+      control: 'select',
+      options: Object.keys(iconMap) as IconKey[],
+      mapping: iconMap,
+      description: 'Icon rendered before the label.',
+    },
+    iconEnd: {
+      control: 'select',
+      options: Object.keys(iconMap) as IconKey[],
+      mapping: iconMap,
+      description: 'Icon rendered after the label.',
+    },
+    isIconOnly: {
+      control: 'boolean',
+      description: 'Forces 1:1 aspect ratio with minimal xs padding. Composable with any `variant`. Requires `accessibilityLabel`.',
+      table: { defaultValue: { summary: 'false' } },
+    },
+    disabled: { control: 'boolean' },
     onPress: { action: 'pressed' },
   },
-} satisfies Meta<typeof Button>;
+  args: { variant: 'default', size: 'medium' },
+};
 
 export default meta;
-type Story = StoryObj<typeof meta>;
+type Story = StoryObj<ButtonStoryArgs>;
 
-export const Default: Story = { args: { children: 'Default', variant: 'default' } };
-export const Ghost: Story = { args: { children: 'Ghost', variant: 'ghost' } };
+export const Playground: Story = {
+  args: { children: 'Button', iconStart: 'none', iconEnd: 'none' },
+};
+
+export const Default: Story = { args: { children: 'Default' } };
+export const Outline: Story = { args: { children: 'Outline', variant: 'outline' } };
 export const Small: Story = { args: { children: 'Small', size: 'small' } };
 export const Medium: Story = { args: { children: 'Medium', size: 'medium' } };
 export const Large: Story = { args: { children: 'Large', size: 'large' } };
 export const Disabled: Story = { args: { children: 'Disabled', disabled: true } };
+
+export const WithIconStart: Story = { args: { children: 'Confirm', iconStart: 'check' } };
+export const WithIconEnd: Story = { args: { children: 'Continue', iconEnd: 'arrowRight' } };
+
+export const IconOnly: Story = {
+  args: {
+    isIconOnly: true,
+    accessibilityLabel: 'Confirm',
+    children: CheckIcon,
+  },
+};
+
+export const IconOnlyOutline: Story = {
+  args: {
+    variant: 'outline',
+    isIconOnly: true,
+    accessibilityLabel: 'Confirm',
+    children: CheckIcon,
+  },
+};
+
 export const AllVariants: Story = {
   render: () => (
     <div style={{ display: 'flex', flexDirection: 'column', gap: '12px' }}>
-      {(['default', 'ghost'] as const).map(v => (
+      {(['default', 'outline'] as const).map(v => (
         <div key={v} style={{ display: 'flex', gap: '8px', alignItems: 'center' }}>
           {(['small', 'medium', 'large'] as const).map(s => (
             <Button key={s} variant={v} size={s}>{v} {s}</Button>
@@ -38,3 +117,25 @@ export const AllVariants: Story = {
     </div>
   ),
 };
+
+export const AllIconOnly: Story = {
+  render: () => (
+    <div style={{ display: 'flex', flexDirection: 'column', gap: '12px' }}>
+      {(['default', 'outline'] as const).map(v => (
+        <div key={v} style={{ display: 'flex', gap: '8px', alignItems: 'center' }}>
+          {(['small', 'medium', 'large'] as const).map(s => (
+            <Button
+              key={s}
+              variant={v}
+              size={s}
+              isIconOnly
+              accessibilityLabel={`${v} ${s}`}
+            >
+              {CheckIcon}
+            </Button>
+          ))}
+        </div>
+      ))}
+    </div>
+  ),
+};

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

@@ -13,6 +13,8 @@ export 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>;
@@ -46,6 +48,7 @@ export function Button({
   iconStart,
   iconEnd,
   disabled = false,
+  isIconOnly = false,
   onPress,
   accessibilityLabel,
   style,
@@ -62,9 +65,11 @@ export function Button({
   const isOutline = variant === 'outline' || variant === 'ghost';
   const containerStyle: ViewStyle = {
     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',
@@ -86,9 +91,13 @@ export function Button({
     >
       {iconStart && <View importantForAccessibility="no-hide-descendants" accessibilityElementsHidden={true}>{iconStart}</View>}
       {children && (
-        <Text style={[styles.label, { fontSize, color: textColor }]}>
-          {children}
-        </Text>
+        isIconOnly
+          ? children
+          : (
+            <Text style={[styles.label, { fontSize, color: textColor }]}>
+              {children}
+            </Text>
+          )
       )}
       {iconEnd && <View importantForAccessibility="no-hide-descendants">{iconEnd}</View>}
     </Pressable>