@ideasui/button 0.0.2-beta.1 → 0.0.2-canary.1786301183157

package/README.md

@@ -56,19 +56,20 @@ function ActionMenu() {
 
 ### Button Props
 
-| Prop         | Type                                               | Default     | Description                                    |
-| :----------- | :------------------------------------------------- | :---------- | :--------------------------------------------- |
-| `variant`    | `'solid' \| 'outline' \| 'ghost'`                  | `'solid'`   | Visual style variant.                          |
-| `color`      | `SemanticColor`                                    | `'default'` | Semantic color intent (primary, success, etc). |
-| `size`       | `'xs' \| 'sm' \| 'md' \| 'lg' \| 'xl'`             | `'md'`      | The size of the button.                        |
-| `radius`     | `'none' \| 'sm' \| 'md' \| 'lg' \| 'xl' \| 'full'` | `'md'`      | The corner radius.                             |
-| `loading`    | `boolean`                                          | `false`     | Shows a spinner and disables interaction.      |
-| `disabled`   | `boolean`                                          | `false`     | Disables the button.                           |
-| `fullWidth`  | `boolean`                                          | `false`     | Expands to fill the container width.           |
-| `startIcon`  | `ReactNode`                                        | —           | Icon displayed before the label.               |
-| `endIcon`    | `ReactNode`                                        | —           | Icon displayed after the label.                |
-| `shortcut`   | `string`                                           | —           | Keyboard shortcut hint.                        |
-| `classNames` | `ButtonClassNames`                                 | —           | Custom classes for internal slots.             |
+| Prop         | Type                                               | Default     | Description                                                                                                     |
+| :----------- | :------------------------------------------------- | :---------- | :-------------------------------------------------------------------------------------------------------------- |
+| `variant`    | `'solid' \| 'outline' \| 'ghost'`                  | `'solid'`   | Visual style variant.                                                                                           |
+| `color`      | `SemanticColor`                                    | `'default'` | Semantic color intent (primary, success, etc).                                                                  |
+| `size`       | `'xs' \| 'sm' \| 'md' \| 'lg' \| 'xl'`             | `'md'`      | The size of the button.                                                                                         |
+| `radius`     | `'none' \| 'sm' \| 'md' \| 'lg' \| 'xl' \| 'full'` | `'md'`      | The corner radius.                                                                                              |
+| `loading`    | `boolean`                                          | `false`     | Shows a spinner and disables interaction.                                                                       |
+| `disabled`   | `boolean`                                          | `false`     | Disables the button.                                                                                            |
+| `fullWidth`  | `boolean`                                          | `false`     | Expands to fill the container width.                                                                            |
+| `isIconOnly` | `boolean`                                          | `false`     | Formats the button for icon-only display (square, equal padding). Enforces accessibility props at compile-time. |
+| `startIcon`  | `ReactNode`                                        | —           | Icon displayed before the label.                                                                                |
+| `endIcon`    | `ReactNode`                                        | —           | Icon displayed after the label.                                                                                 |
+| `shortcut`   | `string`                                           | —           | Keyboard shortcut hint.                                                                                         |
+| `classNames` | `ButtonClassNames`                                 | —           | Custom classes for internal slots.                                                                              |
 
 ### Granular Styling (`classNames`)
 
@@ -93,6 +94,7 @@ The `classNames` prop allows you to override styles for specific internal elemen
 - Proper `aria-live` regions for loading states.
 - High-contrast focus rings for keyboard navigation.
 - Semantic HTML tags based on the `as` prop.
+- **Icon-Only Trigger Safety**: When `isIconOnly` is `true`, TypeScript compile-time checks enforce that either `aria-label` or `aria-labelledby` is supplied to ensure the button has a screen-readable name (WCAG 2.1 AA).
 
 ## License
 

package/dist/index.mjs

@@ -1,2 +1,2 @@
-import {Button}from'react-aria-components';import {cn,mergePropsWithContext,getAccessibleName}from'@ideasui/utils';import {createContext,forwardRef,useContext}from'react';import {button}from'@ideasui/theme/recipes';import {jsx,jsxs,Fragment}from'react/jsx-runtime';var C=createContext(null);function E(){return useContext(C)}var v=forwardRef(({children:o,className:c,size:t,color:s,variant:u,isDisabled:a,isAttached:n=true,isVertical:l=false,radius:d,fullWidth:i,disableAnimation:p=true,showDivider:m,...B},h)=>{let e={size:t,color:s,variant:u,isDisabled:a,isAttached:n,isVertical:l,radius:d,fullWidth:i,disableAnimation:p,showDivider:m},I=cn(i?"flex":"inline-flex",l?"flex-col":"flex-row",n?"isolate":l?"gap-y-2":"gap-x-2",i&&"w-full",c);return jsx(C.Provider,{value:e,children:jsx("div",{ref:h,className:I,"data-attached":n,"data-full-width":i,"data-slot":"button-group","data-vertical":l,role:"group",...B,children:o})})});v.displayName="IdeasUI.Button.Group";var T=createContext(null);function P(){let o=useContext(T);if(!o)throw new Error("Button sub-components must be rendered within a Button component");return o}var f=forwardRef(({children:o,className:c,placement:t="start",...s},u)=>{let{styles:a,classNames:n}=P(),{icon:l}=a,d=t==="start"?n?.startIcon:n?.endIcon;return jsx("span",{ref:u,"aria-hidden":"true",className:cn(l(),t==="end"?"order-last":"order-first",d,c),"data-slot":"button-icon",...s,children:o})});f.displayName="IdeasUI.Button.Icon";var g=forwardRef(({className:o,label:c="Loading",...t},s)=>{let{styles:u,classNames:a}=P(),{loader:n,icon:l}=u;return jsxs("span",{ref:s,className:cn(n(),l(),"inline-flex shrink-0 items-center justify-center",a?.spinner,o),"data-slot":"button-spinner",role:"status",...t,children:[jsx("svg",{className:"size-full animate-spin",fill:"none",stroke:"currentColor",strokeLinecap:"round",strokeLinejoin:"round",strokeWidth:"2.5",viewBox:"0 0 24 24",xmlns:"http://www.w3.org/2000/svg",children:jsx("path",{d:"M21 12a9 9 0 1 1-6.219-8.56"})}),jsx("span",{className:"sr-only",children:c})]})});g.displayName="IdeasUI.Button.Spinner";var S=forwardRef(({children:o,className:c,...t},s)=>{let{styles:u,classNames:a}=P(),{shortcut:n}=u;return jsx("kbd",{ref:s,className:cn(n(),a?.shortcut,c),"data-slot":"button-shortcut",...t,children:o})});S.displayName="IdeasUI.Button.Shortcut";var L=forwardRef(({children:o,className:c,...t},s)=>{let{styles:u,classNames:a}=P(),{label:n}=u;return jsx("span",{ref:s,className:cn(n(),a?.label,c),"data-slot":"button-label",...t,children:o})});L.displayName="IdeasUI.Button.Label";var j=({isLoading:o,loadingIndicator:c,loadingPosition:t="start",isIconOnly:s,startIcon:u,endIcon:a,shortcut:n,children:l,renderProps:d})=>{let i=typeof l=="function"?l(d):l,p=c||jsx(g,{});if(s||o&&t==="center")return o?p:i;let m=o&&t==="start",B=o&&t==="end";return jsxs(Fragment,{children:[m?jsx(f,{placement:"start",children:p}):null,u&&!m?jsx(f,{placement:"start",children:u}):null,typeof i=="string"||typeof i=="number"?jsx(L,{children:i}):i,a&&!B?jsx(f,{placement:"end",children:a}):null,B?jsx(f,{placement:"end",children:p}):null,n?jsx(S,{children:n}):null]})},D=forwardRef((o,c)=>{let{isLoading:t,loadingIndicator:s,loadingPosition:u,isIconOnly:a,startIcon:n,endIcon:l,shortcut:d,children:i,className:p,classNames:m,...B}=o,h=E(),e=mergePropsWithContext(o,h),I=e.isDisabled||t,w=button({variant:e.variant,size:e.size,color:e.color,radius:e.radius,fullWidth:e.fullWidth,isIconOnly:a,isDisabled:I,isLoading:t,disableAnimation:e.disableAnimation,isAttached:e.isAttached,isVertical:e.isVertical,elevation:e.elevation,showDivider:e.showDivider??e.isAttached}),R=getAccessibleName(e,typeof i=="function"?null:i);return jsx(Button,{ref:c,"aria-busy":t,"aria-label":t&&!R?typeof s=="string"?s:"Loading":R,className:N=>w.base({className:cn(typeof p=="function"?p(N):p,m?.base)}),"data-attached":e.isAttached,"data-slot":"button","data-vertical":e.isVertical,isDisabled:I,isPending:t,...B,children:N=>jsx(T.Provider,{value:{styles:w,classNames:m},children:jsx(j,{endIcon:l,isIconOnly:a,isLoading:t,loadingIndicator:s,loadingPosition:u,renderProps:N,shortcut:d,startIcon:n,children:i})})})});D.displayName="IdeasUI.Button";var x=D;x.Icon=f;x.Shortcut=S;x.Spinner=g;x.Label=L;x.Group=v;
-export{x as Button,v as ButtonGroup,C as ButtonGroupContext,E as useButtonGroupContext};
+import {Button}from'react-aria-components';import {cn,mergePropsWithContext,getAccessibleName}from'@ideasui/utils';import {createContext,forwardRef,useMemo,useContext}from'react';import {button}from'@ideasui/theme/recipes';import {jsx,jsxs,Fragment}from'react/jsx-runtime';var g=createContext(null);function G(){return useContext(g)}var S=forwardRef(({children:o,className:c,size:t,color:r,variant:a,isDisabled:l,isAttached:n=true,isVertical:u=false,radius:d="md",fullWidth:i,disableAnimation:p=false,divider:m="full",isIconOnly:B,...P},e)=>{let C=useMemo(()=>({size:t,color:r,variant:a,isDisabled:l,isAttached:n,isVertical:u,radius:d,fullWidth:i,disableAnimation:p,divider:m,isIconOnly:B}),[t,r,a,l,n,u,d,i,p,m,B]),b="isolate";n||(b=u?"gap-y-2":"gap-x-2");let N=cn(i?"flex":"inline-flex",u?"flex-col":"flex-row",b,i&&"w-full",c);return jsx(g.Provider,{value:C,children:jsx("div",{ref:e,className:N,"data-attached":n,"data-full-width":i,"data-slot":"button-group","data-vertical":u,...P,children:o})})});S.displayName="IdeasUI.Button.Group";var M=createContext(null);function h(){let o=useContext(M);if(!o)throw new Error("Button sub-components must be rendered within a Button component");return o}var f=forwardRef(({children:o,className:c,placement:t="start",...r},a)=>{let{styles:l,classNames:n}=h(),{icon:u}=l,d=t==="start"?n?.startIcon:n?.endIcon;return jsx("span",{ref:a,"aria-hidden":"true",className:cn(u(),t==="end"?"order-last":"order-first",d,c),"data-slot":"button-icon",...r,children:o})});f.displayName="IdeasUI.Button.Icon";var L=forwardRef(({className:o,label:c="Loading",...t},r)=>{let{styles:a,classNames:l}=h(),{loader:n,icon:u}=a;return jsxs("span",{ref:r,className:cn(n(),u(),"inline-flex shrink-0 items-center justify-center",l?.spinner,o),"data-slot":"button-spinner",...t,children:[jsx("svg",{className:"size-full animate-spin",fill:"none",stroke:"currentColor",strokeLinecap:"round",strokeLinejoin:"round",strokeWidth:"2.5",viewBox:"0 0 24 24",xmlns:"http://www.w3.org/2000/svg",children:jsx("path",{d:"M21 12a9 9 0 1 1-6.219-8.56"})}),jsx("span",{className:"sr-only",children:c})]})});L.displayName="IdeasUI.Button.Spinner";var w=forwardRef(({children:o,className:c,...t},r)=>{let{styles:a,classNames:l}=h(),{shortcut:n}=a;return jsx("kbd",{ref:r,className:cn(n(),l?.shortcut,c),"data-slot":"button-shortcut",...t,children:o})});w.displayName="IdeasUI.Button.Shortcut";var R=forwardRef(({children:o,className:c,...t},r)=>{let{styles:a,classNames:l}=h(),{label:n}=a;return jsx("span",{ref:r,className:cn(n(),l?.label,c),"data-slot":"button-label",...t,children:o})});R.displayName="IdeasUI.Button.Label";var F=({isLoading:o,loadingIndicator:c,loadingPosition:t="start",isIconOnly:r,startIcon:a,endIcon:l,shortcut:n,children:u,renderProps:d})=>{let i=typeof u=="function"?u(d):u,p=c||jsx(L,{});if(r||o&&t==="center")return o?p:i;let m=o&&t==="start",B=o&&t==="end";return jsxs(Fragment,{children:[m?jsx(f,{placement:"start",children:p}):null,a&&!m?jsx(f,{placement:"start",children:a}):null,typeof i=="string"||typeof i=="number"?jsx(R,{children:i}):i,l&&!B?jsx(f,{placement:"end",children:l}):null,B?jsx(f,{placement:"end",children:p}):null,n?jsx(w,{children:n}):null]})},H=forwardRef((o,c)=>{let{isLoading:t,loadingIndicator:r,loadingPosition:a,isIconOnly:l,startIcon:n,endIcon:u,shortcut:d,children:i,className:p,classNames:m,...B}=o,P=G(),e=mergePropsWithContext(o,P),C=e.isDisabled||t,b=button({variant:e.variant,size:e.size,color:e.color,radius:e.radius,fullWidth:e.fullWidth,isIconOnly:e.isIconOnly,isDisabled:C,isLoading:t,disableAnimation:e.disableAnimation,isAttached:e.isAttached,isVertical:e.isVertical,elevation:e.elevation,divider:e.divider||(e.isAttached?"full":"none")}),N={styles:b,classNames:m},E=getAccessibleName(e,typeof i=="function"?null:i);return jsx(Button,{ref:c,"aria-busy":t,"aria-label":t&&!E?typeof r=="string"?r:"Loading":E,className:v=>b.base({className:cn(typeof p=="function"?p(v):p,m?.base)}),"data-attached":e.isAttached,"data-slot":"button","data-vertical":e.isVertical,isDisabled:C,isPending:t,...B,children:v=>jsx(M.Provider,{value:N,children:jsx(F,{endIcon:u,isIconOnly:e.isIconOnly,isLoading:t,loadingIndicator:r,loadingPosition:a,renderProps:v,shortcut:d,startIcon:n,children:i})})})});H.displayName="IdeasUI.Button";var I=H;I.Icon=f;I.Shortcut=w;I.Spinner=L;I.Label=R;I.Group=S;
+export{I as Button,S as ButtonGroup,g as ButtonGroupContext,G as useButtonGroupContext};

package/package.json

@@ -1,22 +1,26 @@
 {
   "name": "@ideasui/button",
-  "version": "0.0.2-beta.1",
-  "description": "A high-performance, accessible Button and ButtonGroup component library for React, built with Tailwind CSS v4 and React Aria.",
-  "author": "IdeasUI<support@ideasui.com>",
+  "version": "0.0.2-canary.1786301183157",
+  "description": "Accessible, high-performance Button and ButtonGroup components for React. Built with Tailwind CSS v4, React Aria, and OKLCH color palettes.",
+  "author": "IdeasUI<ideas2logic@gmail.com>",
   "homepage": "https://ideasui.com",
   "license": "MIT",
   "keywords": [
-    "ideasui",
     "react",
     "button",
     "button-group",
-    "button-component",
-    "accessible-components",
-    "ui-components",
+    "react-aria",
+    "tailwindcss",
+    "tailwind-v4",
+    "accessible-ui",
+    "wcag",
+    "ideasui",
+    "components",
     "design-system",
-    "tailwindcss"
+    "headless-ui"
   ],
   "main": "dist/index.mjs",
+  "types": "dist/index.d.mts",
   "exports": {
     ".": {
       "types": "./dist/index.d.mts",
@@ -46,9 +50,8 @@
   },
   "dependencies": {
     "react-aria-components": "^1.16.0",
-    "@ideasui/theme": "0.0.5-beta.1",
-    "@ideasui/utils": "0.0.2-beta.1"
+    "@ideasui/theme": "0.0.5-canary.1786301183157",
+    "@ideasui/utils": "0.0.2-canary.1786301183157"
   },
-  "module": "dist/index.mjs",
-  "types": "dist/index.d.mts"
+  "module": "dist/index.mjs"
 }

package/src/button-group-context.tsx

@@ -1,20 +1,21 @@
 'use client';
 
-import type { ButtonProps } from './button.types';
+import type { ButtonProps as ButtonProperties } from './button.types';
 
 import { createContext, useContext } from 'react';
 
 export interface ButtonGroupContextType {
-  size?: ButtonProps['size'];
-  color?: ButtonProps['color'];
-  variant?: ButtonProps['variant'];
+  size?: ButtonProperties['size'];
+  color?: ButtonProperties['color'];
+  variant?: ButtonProperties['variant'];
   isDisabled?: boolean;
   isAttached?: boolean;
   isVertical?: boolean;
-  radius?: ButtonProps['radius'];
+  radius?: ButtonProperties['radius'];
   fullWidth?: boolean;
   disableAnimation?: boolean;
-  showDivider?: boolean;
+  divider?: ButtonProperties['divider'];
+  isIconOnly?: boolean;
 }
 
 export const ButtonGroupContext = createContext<ButtonGroupContextType | null>(null);

package/src/button-group.tsx

@@ -3,7 +3,7 @@
 import type { HTMLAttributes, ReactNode, JSX } from 'react';
 import type { ButtonGroupContextType } from './button-group-context';
 
-import { forwardRef } from 'react';
+import { forwardRef, useMemo } from 'react';
 import { cn } from '@ideasui/utils';
 
 import { ButtonGroupContext } from './button-group-context';
@@ -12,7 +12,7 @@ import { ButtonGroupContext } from './button-group-context';
  * ButtonGroup Component
  * ---------------------------------------------------------------------------------------------*/
 
-export interface ButtonGroupProps
+export interface ButtonGroupProperties
   extends Omit<HTMLAttributes<HTMLDivElement>, 'color'>, ButtonGroupContextType {
   /**
    * Whether the buttons in the group should be vertical.
@@ -25,17 +25,17 @@ export interface ButtonGroupProps
    */
   isAttached?: boolean;
   /**
-   * Whether to show a divider between the buttons in the group.
-   * @default true (when isAttached is true)
+   * The type of divider to display between the buttons in the group.
+   * @default 'full' (when isAttached is true)
    */
-  showDivider?: boolean;
+  divider?: 'full' | 'middle' | 'none';
   /**
    * The content of the button group.
    */
   children: ReactNode;
 }
 
-export const ButtonGroup = forwardRef<HTMLDivElement, ButtonGroupProps>(
+export const ButtonGroup = forwardRef<HTMLDivElement, ButtonGroupProperties>(
   (
     {
       children,
@@ -46,31 +46,54 @@ export const ButtonGroup = forwardRef<HTMLDivElement, ButtonGroupProps>(
       isDisabled,
       isAttached = true,
       isVertical = false,
-      radius,
+      radius = 'md',
       fullWidth,
-      disableAnimation = true,
-      showDivider,
-      ...props
+      disableAnimation = false,
+      divider = 'full',
+      isIconOnly,
+      ...properties
     },
-    ref,
+    reference,
   ): JSX.Element => {
-    const contextValue = {
-      size,
-      color,
-      variant,
-      isDisabled,
-      isAttached,
-      isVertical,
-      radius,
-      fullWidth,
-      disableAnimation,
-      showDivider,
-    };
+    const contextValue = useMemo(
+      () => ({
+        size,
+        color,
+        variant,
+        isDisabled,
+        isAttached,
+        isVertical,
+        radius,
+        fullWidth,
+        disableAnimation,
+        divider,
+        isIconOnly,
+      }),
+      [
+        size,
+        color,
+        variant,
+        isDisabled,
+        isAttached,
+        isVertical,
+        radius,
+        fullWidth,
+        disableAnimation,
+        divider,
+        isIconOnly,
+      ],
+    );
+
+    let gapClass = 'isolate';
+
+    if (!isAttached) {
+      gapClass = isVertical ? 'gap-y-2' : 'gap-x-2';
+    }
 
     const groupClasses = cn(
       fullWidth ? 'flex' : 'inline-flex',
       isVertical ? 'flex-col' : 'flex-row',
-      isAttached ? 'isolate' : isVertical ? 'gap-y-2' : 'gap-x-2',
+      gapClass,
       fullWidth && 'w-full',
       className,
     );
@@ -78,14 +101,13 @@ export const ButtonGroup = forwardRef<HTMLDivElement, ButtonGroupProps>(
     return (
       <ButtonGroupContext.Provider value={contextValue}>
         <div
-          ref={ref}
+          ref={reference}
           className={groupClasses}
           data-attached={isAttached}
           data-full-width={fullWidth}
           data-slot="button-group"
           data-vertical={isVertical}
-          role="group"
-          {...props}
+          {...properties}
         >
           {children}
         </div>

package/src/button.tsx

@@ -1,12 +1,13 @@
 'use client';
 
 import type {
-  ButtonProps,
+  ButtonProps as ButtonProperties,
   ButtonComponent,
-  ButtonLabelProps,
-  ButtonIconProps,
-  ButtonSpinnerProps,
-  ButtonShortcutProps,
+  ButtonClassNames,
+  ButtonLabelProperties,
+  ButtonIconProperties,
+  ButtonSpinnerProperties,
+  ButtonShortcutProperties,
 } from './button.types';
 import type { ButtonReturnType } from '@ideasui/theme/recipes';
 import type { ButtonRenderProps } from 'react-aria-components';
@@ -29,7 +30,7 @@ import { ButtonGroup } from './button-group';
  */
 interface ButtonContextValue {
   styles: ButtonReturnType;
-  classNames?: ButtonProps['classNames'];
+  classNames?: ButtonClassNames;
 }
 
 const ButtonContext = createContext<ButtonContextValue | null>(null);
@@ -53,8 +54,8 @@ function useButtonContext(): ButtonContextValue {
  * Button Slots
  * ---------------------------------------------------------------------------------------------*/
 
-const ButtonIcon = forwardRef<HTMLElement, ButtonIconProps>(
-  ({ children, className, placement = 'start', ...props }, ref): JSX.Element => {
+const ButtonIcon = forwardRef<HTMLElement, ButtonIconProperties>(
+  ({ children, className, placement = 'start', ...properties }, reference): JSX.Element => {
     const { styles, classNames } = useButtonContext();
     const { icon } = styles;
 
@@ -62,7 +63,7 @@ const ButtonIcon = forwardRef<HTMLElement, ButtonIconProps>(
 
     return (
       <span
-        ref={ref}
+        ref={reference}
         aria-hidden="true"
         className={cn(
           icon(),
@@ -71,7 +72,7 @@ const ButtonIcon = forwardRef<HTMLElement, ButtonIconProps>(
           className,
         )}
         data-slot="button-icon"
-        {...props}
+        {...properties}
       >
         {children}
       </span>
@@ -81,14 +82,14 @@ const ButtonIcon = forwardRef<HTMLElement, ButtonIconProps>(
 
 ButtonIcon.displayName = 'IdeasUI.Button.Icon';
 
-const ButtonSpinner = forwardRef<HTMLSpanElement, ButtonSpinnerProps>(
-  ({ className, label = 'Loading', ...props }, ref): JSX.Element => {
+const ButtonSpinner = forwardRef<HTMLSpanElement, ButtonSpinnerProperties>(
+  ({ className, label = 'Loading', ...properties }, reference): JSX.Element => {
     const { styles, classNames } = useButtonContext();
     const { loader, icon } = styles;
 
     return (
       <span
-        ref={ref}
+        ref={reference}
         className={cn(
           loader(),
           icon(),
@@ -97,8 +98,7 @@ const ButtonSpinner = forwardRef<HTMLSpanElement, ButtonSpinnerProps>(
           className,
         )}
         data-slot="button-spinner"
-        role="status"
-        {...props}
+        {...properties}
       >
         <svg
           className="size-full animate-spin"
@@ -120,17 +120,17 @@ const ButtonSpinner = forwardRef<HTMLSpanElement, ButtonSpinnerProps>(
 
 ButtonSpinner.displayName = 'IdeasUI.Button.Spinner';
 
-const ButtonShortcut = forwardRef<HTMLSpanElement, ButtonShortcutProps>(
-  ({ children, className, ...props }, ref): JSX.Element => {
+const ButtonShortcut = forwardRef<HTMLSpanElement, ButtonShortcutProperties>(
+  ({ children, className, ...properties }, reference): JSX.Element => {
     const { styles, classNames } = useButtonContext();
     const { shortcut } = styles;
 
     return (
       <kbd
-        ref={ref}
+        ref={reference}
         className={cn(shortcut(), classNames?.shortcut, className)}
         data-slot="button-shortcut"
-        {...props}
+        {...properties}
       >
         {children}
       </kbd>
@@ -140,17 +140,17 @@ const ButtonShortcut = forwardRef<HTMLSpanElement, ButtonShortcutProps>(
 
 ButtonShortcut.displayName = 'IdeasUI.Button.Shortcut';
 
-const ButtonLabel = forwardRef<HTMLSpanElement, ButtonLabelProps>(
-  ({ children, className, ...props }, ref): JSX.Element => {
+const ButtonLabel = forwardRef<HTMLSpanElement, ButtonLabelProperties>(
+  ({ children, className, ...properties }, reference): JSX.Element => {
     const { styles, classNames } = useButtonContext();
     const { label } = styles;
 
     return (
       <span
-        ref={ref}
+        ref={reference}
         className={cn(label(), classNames?.label, className)}
         data-slot="button-label"
-        {...props}
+        {...properties}
       >
         {children}
       </span>
@@ -164,7 +164,7 @@ ButtonLabel.displayName = 'IdeasUI.Button.Label';
  * Button Render Helpers
  * ---------------------------------------------------------------------------------------------*/
 
-interface ButtonContentProps {
+interface ButtonContentProperties {
   isLoading?: boolean;
   loadingIndicator?: React.ReactNode;
   loadingPosition?: 'start' | 'end' | 'center';
@@ -172,7 +172,7 @@ interface ButtonContentProps {
   startIcon?: React.ReactNode;
   endIcon?: React.ReactNode;
   shortcut?: React.ReactNode;
-  children: ButtonProps['children'];
+  children: ButtonProperties['children'];
   renderProps: ButtonRenderProps;
 }
 
@@ -186,7 +186,8 @@ const ButtonContent = ({
   shortcut,
   children,
   renderProps,
-}: ButtonContentProps): ReactNode => {
+  // eslint-disable-next-line sonarjs/function-return-type
+}: ButtonContentProperties): ReactNode => {
   const content = typeof children === 'function' ? children(renderProps) : children;
   const loader = loadingIndicator || <ButtonSpinner />;
 
@@ -224,86 +225,92 @@ const ButtonContent = ({
  * Button Base
  * ---------------------------------------------------------------------------------------------*/
 
-const ButtonBase = forwardRef<HTMLButtonElement, ButtonProps>((originalProps, ref): JSX.Element => {
-  const {
-    isLoading,
-    loadingIndicator,
-    loadingPosition,
-    isIconOnly,
-    startIcon,
-    endIcon,
-    shortcut,
-    children,
-    className,
-    classNames,
-    ...props
-  } = originalProps;
-
-  const groupContext = useButtonGroupContext();
-  const merged = mergePropsWithContext(originalProps, groupContext);
-
-  // Specific logic for Button
-  const mergedDisabled = merged.isDisabled || isLoading;
-
-  const styles = button({
-    variant: merged.variant,
-    size: merged.size,
-    color: merged.color,
-    radius: merged.radius,
-    fullWidth: merged.fullWidth,
-    isIconOnly,
-    isDisabled: mergedDisabled,
-    isLoading,
-    disableAnimation: merged.disableAnimation,
-    isAttached: merged.isAttached,
-    isVertical: merged.isVertical,
-    elevation: merged.elevation,
-    showDivider: merged.showDivider ?? merged.isAttached,
-  });
-
-  // Ensure we have an accessible name when loading or icon-only
-  const ariaLabel = getAccessibleName(merged, typeof children === 'function' ? null : children);
-  const loadingLabel = typeof loadingIndicator === 'string' ? loadingIndicator : 'Loading';
+const ButtonBase = forwardRef<HTMLButtonElement, ButtonProperties>(
+  (originalProperties, reference): JSX.Element => {
+    const {
+      isLoading,
+      loadingIndicator,
+      loadingPosition,
+      // eslint-disable-next-line @typescript-eslint/no-unused-vars
+      isIconOnly,
+      startIcon,
+      endIcon,
+      shortcut,
+      children,
+      className,
+      classNames,
+      ...properties
+    } = originalProperties;
+
+    const groupContext = useButtonGroupContext();
+    const merged = mergePropsWithContext(originalProperties, groupContext);
+
+    // Specific logic for Button
+    const mergedDisabled = merged.isDisabled || isLoading;
+
+    const styles = button({
+      variant: merged.variant,
+      size: merged.size,
+      color: merged.color,
+      radius: merged.radius,
+      fullWidth: merged.fullWidth,
+      isIconOnly: merged.isIconOnly,
+      isDisabled: mergedDisabled,
+      isLoading,
+      disableAnimation: merged.disableAnimation,
+      isAttached: merged.isAttached,
+      isVertical: merged.isVertical,
+      elevation: merged.elevation,
+      divider: merged.divider || (merged.isAttached ? 'full' : 'none'),
+    });
+
+    // Context value - React Compiler will optimize this automatically
+    const contextValue = { styles, classNames };
+
+    // Ensure we have an accessible name when loading or icon-only
+    const ariaLabel = getAccessibleName(merged, typeof children === 'function' ? null : children);
+    const loadingLabel = typeof loadingIndicator === 'string' ? loadingIndicator : 'Loading';
 
-  return (
-    <ButtonPrimitive
-      ref={ref}
-      aria-busy={isLoading}
-      aria-label={isLoading && !ariaLabel ? loadingLabel : ariaLabel}
-      className={(renderProps) =>
-        styles.base({
-          className: cn(
-            typeof className === 'function' ? className(renderProps) : className,
-            classNames?.base,
-          ),
-        })
-      }
-      data-attached={merged.isAttached}
-      data-slot="button"
-      data-vertical={merged.isVertical}
-      isDisabled={mergedDisabled}
-      isPending={isLoading}
-      {...props}
-    >
-      {(renderProps) => (
-        <ButtonContext.Provider value={{ styles, classNames }}>
-          <ButtonContent
-            endIcon={endIcon}
-            isIconOnly={isIconOnly}
-            isLoading={isLoading}
-            loadingIndicator={loadingIndicator}
-            loadingPosition={loadingPosition}
-            renderProps={renderProps}
-            shortcut={shortcut}
-            startIcon={startIcon}
-          >
-            {children}
-          </ButtonContent>
-        </ButtonContext.Provider>
-      )}
-    </ButtonPrimitive>
-  );
-});
+    return (
+      <ButtonPrimitive
+        ref={reference}
+        aria-busy={isLoading}
+        aria-label={isLoading && !ariaLabel ? loadingLabel : ariaLabel}
+        className={(renderProperties) =>
+          styles.base({
+            className: cn(
+              typeof className === 'function' ? className(renderProperties) : className,
+              classNames?.base,
+            ),
+          })
+        }
+        data-attached={merged.isAttached}
+        data-slot="button"
+        data-vertical={merged.isVertical}
+        isDisabled={mergedDisabled}
+        isPending={isLoading}
+        {...properties}
+      >
+        {(renderProperties) => (
+          <ButtonContext.Provider value={contextValue}>
+            <ButtonContent
+              endIcon={endIcon}
+              isIconOnly={merged.isIconOnly}
+              isLoading={isLoading}
+              loadingIndicator={loadingIndicator}
+              loadingPosition={loadingPosition}
+              renderProps={renderProperties}
+              shortcut={shortcut}
+              startIcon={startIcon}
+            >
+              {children}
+            </ButtonContent>
+          </ButtonContext.Provider>
+        )}
+      </ButtonPrimitive>
+    );
+  },
+);
 
 ButtonBase.displayName = 'IdeasUI.Button';
 

package/src/button.types.ts

@@ -1,7 +1,10 @@
-import type { ButtonProps as ButtonPrimitiveProps, ButtonRenderProps } from 'react-aria-components';
+import type {
+  ButtonProps as ButtonPrimitiveProperties,
+  ButtonRenderProps,
+} from 'react-aria-components';
 import type { ForwardRefExoticComponent, HTMLAttributes, ReactNode, RefAttributes } from 'react';
 import type { ButtonVariantProps } from '@ideasui/theme/recipes';
-import type { ButtonGroupProps } from './button-group';
+import type { ButtonGroupProperties } from './button-group';
 
 /**
  * Granular class names for the Button component slots.
@@ -22,11 +25,11 @@ export interface ButtonClassNames {
 }
 
 /**
- * Props for the Button component.
+ * Base props for the Button component.
  */
-export interface ButtonProps
+interface ButtonBaseProperties
   extends
-    Omit<ButtonPrimitiveProps, 'className'>,
+    Omit<ButtonPrimitiveProperties, 'className'>,
     Omit<ButtonVariantProps, 'isLoading' | 'isDisabled'> {
   /**
    * Whether the button is in a loading state.
@@ -43,13 +46,6 @@ export interface ButtonProps
    * @default 'start'
    */
   loadingPosition?: 'start' | 'end' | 'center';
-  /**
-   * Whether the button should be square and optimized for icons.
-   *
-   * Note: When true, you MUST provide an `aria-label` or `aria-labelledby` for accessibility.
-   * @default false
-   */
-  isIconOnly?: boolean;
   /**
    * Icon to display before the button content.
    */
@@ -63,10 +59,10 @@ export interface ButtonProps
    */
   shortcut?: ReactNode;
   /**
-   * Whether to show a divider between the buttons in a group.
-   * @default true (when isAttached is true)
+   * The type of divider to display between the buttons in a group.
+   * @default 'full' (when isAttached is true)
    */
-  showDivider?: boolean;
+  divider?: 'full' | 'middle' | 'none';
   /**
    * Custom class names for individual button slots.
    */
@@ -75,12 +71,19 @@ export interface ButtonProps
    * The CSS class name for the button.
    * Can be a string or a function that receives the button render props.
    */
-  className?: string | ((props: ButtonRenderProps) => string);
+  className?: string | ((properties: ButtonRenderProps) => string);
   /**
    * The content to display inside the button.
    * Can be a ReactNode or a function that receives the button render props.
    */
-  children?: ReactNode | ((props: ButtonRenderProps) => ReactNode);
+  children?: ReactNode | ((properties: ButtonRenderProps) => ReactNode);
+  /**
+   * Whether the button should be square and optimized for icons.
+   *
+   * Note: When true, you MUST provide an `aria-label` or `aria-labelledby` for accessibility.
+   * @default false
+   */
+  isIconOnly?: boolean;
   /**
    * Accessibility label for the button.
    * Required if the button has no visible label (e.g., `isIconOnly`).
@@ -92,15 +95,67 @@ export interface ButtonProps
   'aria-labelledby'?: string;
 }
 
+/**
+ * Props for the Button component.
+ *
+ * Enforces that if `isIconOnly` is true, either `aria-label` or `aria-labelledby` must be provided.
+ */
+export type ButtonProps =
+  | (ButtonBaseProperties & {
+      /**
+       * Whether the button should be square and optimized for icons.
+       * @default false
+       */
+      isIconOnly?: false;
+      /**
+       * Accessibility label for the button.
+       */
+      'aria-label'?: string;
+      /**
+       * ID of an element that serves as the accessible label for the button.
+       */
+      'aria-labelledby'?: string;
+    })
+  | (ButtonBaseProperties & {
+      /**
+       * Whether the button should be square and optimized for icons.
+       */
+      isIconOnly: true;
+      /**
+       * Accessibility label for the button.
+       * Required if the button has no visible label (e.g., `isIconOnly`).
+       */
+      'aria-label': string;
+      /**
+       * ID of an element that serves as the accessible label for the button.
+       */
+      'aria-labelledby'?: string;
+    })
+  | (ButtonBaseProperties & {
+      /**
+       * Whether the button should be square and optimized for icons.
+       */
+      isIconOnly: true;
+      /**
+       * Accessibility label for the button.
+       */
+      'aria-label'?: string;
+      /**
+       * ID of an element that serves as the accessible label for the button.
+       * Required if the button has no visible label (e.g., `isIconOnly`).
+       */
+      'aria-labelledby': string;
+    });
+
 /**
  * Props for the Button.Label component.
  */
-export interface ButtonLabelProps extends HTMLAttributes<HTMLSpanElement> {}
+export interface ButtonLabelProperties extends HTMLAttributes<HTMLSpanElement> {}
 
 /**
  * Props for the Button.Icon component.
  */
-export interface ButtonIconProps extends HTMLAttributes<HTMLElement> {
+export interface ButtonIconProperties extends HTMLAttributes<HTMLElement> {
   /**
    * The icon content.
    */
@@ -115,7 +170,7 @@ export interface ButtonIconProps extends HTMLAttributes<HTMLElement> {
 /**
  * Props for the Button.Spinner component.
  */
-export interface ButtonSpinnerProps extends HTMLAttributes<HTMLSpanElement> {
+export interface ButtonSpinnerProperties extends HTMLAttributes<HTMLSpanElement> {
   /**
    * Accessibility label for the spinner.
    * @default 'Loading'
@@ -126,7 +181,7 @@ export interface ButtonSpinnerProps extends HTMLAttributes<HTMLSpanElement> {
 /**
  * Props for the Button.Shortcut component.
  */
-export interface ButtonShortcutProps extends HTMLAttributes<HTMLSpanElement> {
+export interface ButtonShortcutProperties extends HTMLAttributes<HTMLSpanElement> {
   /**
    * The shortcut keys to display.
    */
@@ -142,21 +197,21 @@ export interface ButtonComponent extends ForwardRefExoticComponent<
   /**
    * Component to display the button label.
    */
-  Label: ForwardRefExoticComponent<ButtonLabelProps & RefAttributes<HTMLSpanElement>>;
+  Label: ForwardRefExoticComponent<ButtonLabelProperties & RefAttributes<HTMLSpanElement>>;
   /**
    * Component to display an icon inside the button.
    */
-  Icon: ForwardRefExoticComponent<ButtonIconProps & RefAttributes<HTMLElement>>;
+  Icon: ForwardRefExoticComponent<ButtonIconProperties & RefAttributes<HTMLElement>>;
   /**
    * Component to display a shortcut indicator inside the button.
    */
-  Shortcut: ForwardRefExoticComponent<ButtonShortcutProps & RefAttributes<HTMLSpanElement>>;
+  Shortcut: ForwardRefExoticComponent<ButtonShortcutProperties & RefAttributes<HTMLSpanElement>>;
   /**
    * Component to display a loading spinner inside the button.
    */
-  Spinner: ForwardRefExoticComponent<ButtonSpinnerProps & RefAttributes<HTMLSpanElement>>;
+  Spinner: ForwardRefExoticComponent<ButtonSpinnerProperties & RefAttributes<HTMLSpanElement>>;
   /**
    * Component to group multiple buttons together.
    */
-  Group: ForwardRefExoticComponent<ButtonGroupProps & RefAttributes<HTMLDivElement>>;
+  Group: ForwardRefExoticComponent<ButtonGroupProperties & RefAttributes<HTMLDivElement>>;
 }