From 499e39827330bcf373253686d50b2cb9311178c4 Mon Sep 17 00:00:00 2001
From: Aziz Becha <aziz07becha@gmail.com>
Date: Tue, 12 May 2026 20:47:01 +0100
Subject: [PATCH 01/24] refactor: add Button label prop and deprecate children

Introduce a `label?: string` prop as the primary way to set the button
text. The `children` prop keeps working as a deprecated fallback (when
both are set, `label` wins) and emits a dev-only warning.

This decouples the button layout from arbitrary child structures and
makes `uppercase` work reliably, since the label is always a string.
---
 src/components/Button/Button.tsx         |  34 ++++-
 src/components/__tests__/Button.test.tsx | 167 +++++++++++++++--------
 2 files changed, 137 insertions(+), 64 deletions(-)

diff --git a/src/components/Button/Button.tsx b/src/components/Button/Button.tsx
index 17d40fb035..1e4493f1db 100644
--- a/src/components/Button/Button.tsx
+++ b/src/components/Button/Button.tsx
@@ -31,7 +31,10 @@ import TouchableRipple, {
 } from '../TouchableRipple/TouchableRipple';
 import Text from '../Typography/Text';
 
-export type Props = $Omit<React.ComponentProps<typeof Surface>, 'mode'> & {
+export type Props = $Omit<
+  React.ComponentProps<typeof Surface>,
+  'mode' | 'children'
+> & {
   /**
    * Mode of the button. You can change the mode to adjust the styling to give it desired emphasis.
    * - `text` - flat button without background or outline, used for the lowest priority actions, especially when presenting multiple options.
@@ -74,9 +77,14 @@ export type Props = $Omit<React.ComponentProps<typeof Surface>, 'mode'> & {
   /**
    * Label text of the button.
    */
-  children: React.ReactNode;
+  label?: string;
   /**
-   * Make the label text uppercased. Note that this won't work if you pass React elements as children.
+   * @deprecated Use `label` instead. When both `label` and `children` are set, `label` is used.
+   * Label text of the button.
+   */
+  children?: React.ReactNode;
+  /**
+   * Make the label text uppercased.
    */
   uppercase?: boolean;
   /**
@@ -157,9 +165,12 @@ export type Props = $Omit<React.ComponentProps<typeof Surface>, 'mode'> & {
  * import { Button } from 'react-native-paper';
  *
  * const MyComponent = () => (
- *   <Button icon="camera" mode="contained" onPress={() => console.log('Pressed')}>
- *     Press me
- *   </Button>
+ *   <Button
+ *     icon="camera"
+ *     mode="contained"
+ *     onPress={() => console.log('Pressed')}
+ *     label="Press me"
+ *   />
  * );
  *
  * export default MyComponent;
@@ -175,6 +186,7 @@ const Button = (
     icon,
     buttonColor: customButtonColor,
     textColor: customTextColor,
+    label,
     children,
     accessibilityLabel,
     accessibilityHint,
@@ -210,6 +222,14 @@ const Button = (
   const uppercase = uppercaseProp ?? false;
   const isWeb = Platform.OS === 'web';
 
+  if (process.env.NODE_ENV !== 'production' && children != null) {
+    console.warn(
+      'Button: the `children` prop is deprecated and will be removed in a future release. Use the `label` prop instead.'
+    );
+  }
+
+  const labelContent = label != null ? label : children;
+
   const hasPassedTouchHandler = hasTouchHandler({
     onPress,
     onPressIn,
@@ -416,7 +436,7 @@ const Button = (
             ]}
             maxFontSizeMultiplier={maxFontSizeMultiplier}
           >
-            {children}
+            {labelContent}
           </Text>
         </View>
       </TouchableRipple>
diff --git a/src/components/__tests__/Button.test.tsx b/src/components/__tests__/Button.test.tsx
index 71107089e7..153bec346e 100644
--- a/src/components/__tests__/Button.test.tsx
+++ b/src/components/__tests__/Button.test.tsx
@@ -28,20 +28,20 @@ const styles = StyleSheet.create({
 });
 
 it('renders text button by default', () => {
-  const tree = render(<Button>Text Button</Button>).toJSON();
+  const tree = render(<Button label="Text Button" />).toJSON();
 
   expect(tree).toMatchSnapshot();
 });
 
 it('renders text button with mode', () => {
-  const tree = render(<Button mode="text">Text Button</Button>).toJSON();
+  const tree = render(<Button mode="text" label="Text Button" />).toJSON();
 
   expect(tree).toMatchSnapshot();
 });
 
 it('renders outlined button with mode', () => {
   const tree = render(
-    <Button mode="outlined">Outlined Button</Button>
+    <Button mode="outlined" label="Outlined Button" />
   ).toJSON();
 
   expect(tree).toMatchSnapshot();
@@ -49,43 +49,45 @@ it('renders outlined button with mode', () => {
 
 it('renders contained contained with mode', () => {
   const tree = render(
-    <Button mode="contained">Contained Button</Button>
+    <Button mode="contained" label="Contained Button" />
   ).toJSON();
 
   expect(tree).toMatchSnapshot();
 });
 
 it('renders button with icon', () => {
-  const tree = render(<Button icon="camera">Icon Button</Button>).toJSON();
+  const tree = render(<Button icon="camera" label="Icon Button" />).toJSON();
 
   expect(tree).toMatchSnapshot();
 });
 
 it('renders button with icon in reverse order', () => {
   const tree = render(
-    <Button icon="chevron-right" contentStyle={styles.flexing}>
-      Right Icon
-    </Button>
+    <Button
+      icon="chevron-right"
+      contentStyle={styles.flexing}
+      label="Right Icon"
+    />
   ).toJSON();
 
   expect(tree).toMatchSnapshot();
 });
 
 it('renders loading button', () => {
-  const tree = render(<Button loading>Loading Button</Button>).toJSON();
+  const tree = render(<Button loading label="Loading Button" />).toJSON();
 
   expect(tree).toMatchSnapshot();
 });
 
 it('renders disabled button', () => {
-  const tree = render(<Button disabled>Disabled Button</Button>).toJSON();
+  const tree = render(<Button disabled label="Disabled Button" />).toJSON();
 
   expect(tree).toMatchSnapshot();
 });
 
 it('renders disabled button if there is no touch handler passed', () => {
   const { getByTestId } = render(
-    <Button testID="disabled-button">Disabled button</Button>
+    <Button testID="disabled-button" label="Disabled button" />
   );
 
   expect(getByTestId('disabled-button').props.accessibilityState).toMatchObject(
@@ -97,9 +99,11 @@ it('renders disabled button if there is no touch handler passed', () => {
 
 it('renders active button if only onLongPress handler is passed', () => {
   const { getByTestId } = render(
-    <Button onLongPress={() => {}} testID="active-button">
-      Active button
-    </Button>
+    <Button
+      onLongPress={() => {}}
+      testID="active-button"
+      label="Active button"
+    />
   );
 
   expect(getByTestId('active-button').props.accessibilityState).toMatchObject({
@@ -109,7 +113,7 @@ it('renders active button if only onLongPress handler is passed', () => {
 
 it('renders button with color', () => {
   const tree = render(
-    <Button textColor={pink500}>Custom Button</Button>
+    <Button textColor={pink500} label="Custom Button" />
   ).toJSON();
 
   expect(tree).toMatchSnapshot();
@@ -117,7 +121,7 @@ it('renders button with color', () => {
 
 it('renders button with button color', () => {
   const tree = render(
-    <Button buttonColor={pink500}>Custom Button</Button>
+    <Button buttonColor={pink500} label="Custom Button" />
   ).toJSON();
 
   expect(tree).toMatchSnapshot();
@@ -125,7 +129,7 @@ it('renders button with button color', () => {
 
 it('renders button with custom testID', () => {
   const tree = render(
-    <Button testID={'custom:testID'}>Button with custom testID</Button>
+    <Button testID={'custom:testID'} label="Button with custom testID" />
   ).toJSON();
 
   expect(tree).toMatchSnapshot();
@@ -133,9 +137,10 @@ it('renders button with custom testID', () => {
 
 it('renders button with an accessibility label', () => {
   const tree = render(
-    <Button accessibilityLabel={'label'}>
-      Button with accessibility label
-    </Button>
+    <Button
+      accessibilityLabel={'label'}
+      label="Button with accessibility label"
+    />
   ).toJSON();
 
   expect(tree).toMatchSnapshot();
@@ -143,7 +148,7 @@ it('renders button with an accessibility label', () => {
 
 it('renders button with an accessibility hint', () => {
   const tree = render(
-    <Button accessibilityHint={'hint'}>Button with accessibility hint</Button>
+    <Button accessibilityHint={'hint'} label="Button with accessibility hint" />
   ).toJSON();
 
   expect(tree).toMatchSnapshot();
@@ -151,9 +156,11 @@ it('renders button with an accessibility hint', () => {
 
 it('renders button with custom border radius', () => {
   const { getByTestId } = render(
-    <Button testID="custom-radius" style={styles.customRadius}>
-      Custom radius
-    </Button>
+    <Button
+      testID="custom-radius"
+      style={styles.customRadius}
+      label="Custom radius"
+    />
   );
 
   expect(getByTestId('custom-radius-container')).toHaveStyle(
@@ -168,9 +175,8 @@ it('renders outlined button with custom border radius', () => {
       mode={'outlined'}
       testID="custom-radius"
       style={styles.customRadius}
-    >
-      Custom radius
-    </Button>
+      label="Custom radius"
+    />
   );
 
   expect(getByTestId('custom-radius-container')).toHaveStyle(
@@ -186,9 +192,11 @@ it('renders outlined button with custom border radius', () => {
 
 it('renders button without border radius', () => {
   const { getByTestId } = render(
-    <Button testID="custom-radius" style={styles.noRadius}>
-      Custom radius
-    </Button>
+    <Button
+      testID="custom-radius"
+      style={styles.noRadius}
+      label="Custom radius"
+    />
   );
 
   expect(getByTestId('custom-radius-container')).toHaveStyle(styles.noRadius);
@@ -200,9 +208,7 @@ it('should execute onPressIn', () => {
   const onPress = jest.fn();
 
   const { getByTestId } = render(
-    <Button onPress={onPress} onPressIn={onPressInMock} testID="button">
-      {null}
-    </Button>
+    <Button onPress={onPress} onPressIn={onPressInMock} testID="button" />
   );
   fireEvent(getByTestId('button'), 'onPressIn');
   expect(onPressInMock).toHaveBeenCalledTimes(1);
@@ -213,20 +219,56 @@ it('should execute onPressOut', () => {
   const onPress = jest.fn();
 
   const { getByTestId } = render(
-    <Button onPress={onPress} onPressOut={onPressOutMock} testID="button">
-      {null}
-    </Button>
+    <Button onPress={onPress} onPressOut={onPressOutMock} testID="button" />
   );
   fireEvent(getByTestId('button'), 'onPressOut');
   expect(onPressOutMock).toHaveBeenCalledTimes(1);
 });
 
+describe('label prop', () => {
+  it('renders the label text', () => {
+    const { getByTestId } = render(<Button testID="button" label="My label" />);
+
+    expect(getByTestId('button-text')).toHaveTextContent('My label');
+  });
+
+  it('takes precedence over children', () => {
+    const { getByTestId } = render(
+      <Button testID="button" label="From label">
+        From children
+      </Button>
+    );
+
+    expect(getByTestId('button-text')).toHaveTextContent('From label');
+  });
+});
+
+describe('deprecated children prop', () => {
+  it('still renders the children as the label', () => {
+    const warn = jest.spyOn(console, 'warn').mockImplementation(() => {});
+    const { getByTestId } = render(
+      <Button testID="button">Legacy label</Button>
+    );
+
+    expect(getByTestId('button-text')).toHaveTextContent('Legacy label');
+    warn.mockRestore();
+  });
+
+  it('warns about the deprecation', () => {
+    const warn = jest.spyOn(console, 'warn').mockImplementation(() => {});
+    render(<Button>Legacy label</Button>);
+
+    expect(warn).toHaveBeenCalledWith(
+      expect.stringContaining('`children` prop is deprecated')
+    );
+    warn.mockRestore();
+  });
+});
+
 describe('button text styles', () => {
   it('applies uppercase styles if uppercase prop is truthy', () => {
     const { getByTestId } = render(
-      <Button testID="button" uppercase>
-        Test
-      </Button>
+      <Button testID="button" uppercase label="Test" />
     );
 
     expect(getByTestId('button-text')).toHaveStyle({
@@ -236,9 +278,7 @@ describe('button text styles', () => {
 
   it('does not apply uppercase styles if uppercase prop is falsy', () => {
     const { getByTestId } = render(
-      <Button testID="button" uppercase={false}>
-        Test
-      </Button>
+      <Button testID="button" uppercase={false} label="Test" />
     );
 
     expect(getByTestId('button-text')).not.toHaveStyle({
@@ -250,9 +290,13 @@ describe('button text styles', () => {
 describe('button icon styles', () => {
   it('should return correct icon styles for compact text button', () => {
     const { getByTestId } = render(
-      <Button mode={'text'} compact icon="camera" testID="compact-button">
-        Compact text button
-      </Button>
+      <Button
+        mode={'text'}
+        compact
+        icon="camera"
+        testID="compact-button"
+        label="Compact text button"
+      />
     );
     expect(getByTestId('compact-button-icon-container')).toHaveStyle({
       marginLeft: 6,
@@ -264,9 +308,13 @@ describe('button icon styles', () => {
     (mode) =>
       it(`should return correct icon styles for compact ${mode} button`, () => {
         const { getByTestId } = render(
-          <Button mode={mode} compact icon="camera" testID="compact-button">
-            Compact {mode} button
-          </Button>
+          <Button
+            mode={mode}
+            compact
+            icon="camera"
+            testID="compact-button"
+            label={`Compact ${mode} button`}
+          />
         );
         expect(getByTestId('compact-button-icon-container')).toHaveStyle({
           marginLeft: 8,
@@ -277,9 +325,12 @@ describe('button icon styles', () => {
 
   it('should return correct icon styles for text button', () => {
     const { getByTestId } = render(
-      <Button mode={'text'} icon="camera" testID="compact-button">
-        text button
-      </Button>
+      <Button
+        mode={'text'}
+        icon="camera"
+        testID="compact-button"
+        label="text button"
+      />
     );
     expect(getByTestId('compact-button-icon-container')).toHaveStyle({
       marginLeft: 12,
@@ -291,9 +342,12 @@ describe('button icon styles', () => {
     (mode) =>
       it(`should return correct icon styles for compact ${mode} button`, () => {
         const { getByTestId } = render(
-          <Button mode={mode} icon="camera" testID="compact-button">
-            {mode} button
-          </Button>
+          <Button
+            mode={mode}
+            icon="camera"
+            testID="compact-button"
+            label={`${mode} button`}
+          />
         );
         expect(getByTestId('compact-button-icon-container')).toHaveStyle({
           marginLeft: 16,
@@ -706,9 +760,8 @@ it('animated value changes correctly', () => {
       compact
       icon="camera"
       style={[{ transform: [{ scale: value }] }]}
-    >
-      Compact button
-    </Button>
+      label="Compact button"
+    />
   );
   expect(getByTestId('button-container-outer-layer')).toHaveStyle({
     transform: [{ scale: 1 }],

From e30b72db2fde13ab19c5c82931bd645234bf470f Mon Sep 17 00:00:00 2001
From: Aziz Becha <aziz07becha@gmail.com>
Date: Tue, 12 May 2026 20:53:10 +0100
Subject: [PATCH 02/24] refactor: migrate internal Button usages to label

Update the components that compose Button (Banner, Snackbar,
DataTablePagination) to pass the new `label` prop instead of children,
and update the `## Usage` / `@example` JSDoc blocks (and the test
files) accordingly so nothing relies on the deprecated `children` prop.
---
 src/components/Banner.tsx                     |  5 ++--
 src/components/Card/Card.tsx                  |  4 +--
 src/components/Card/CardActions.tsx           |  4 +--
 .../DataTable/DataTablePagination.tsx         |  5 ++--
 src/components/Dialog/Dialog.tsx              |  4 +--
 src/components/Dialog/DialogActions.tsx       |  4 +--
 src/components/Menu/Menu.tsx                  |  2 +-
 src/components/Modal.tsx                      |  4 +--
 src/components/Snackbar.tsx                   |  7 +++--
 src/components/__tests__/Card/Card.test.tsx   |  7 +++--
 src/components/__tests__/Dialog.test.tsx      | 12 ++++-----
 src/components/__tests__/Menu.test.tsx        | 26 +++++++------------
 12 files changed, 35 insertions(+), 49 deletions(-)

diff --git a/src/components/Banner.tsx b/src/components/Banner.tsx
index b1a00b4ce4..428a225d37 100644
--- a/src/components/Banner.tsx
+++ b/src/components/Banner.tsx
@@ -246,10 +246,9 @@ const Banner = ({
                 style={styles.button}
                 textColor={colors.primary}
                 theme={theme}
+                label={label}
                 {...others}
-              >
-                {label}
-              </Button>
+              />
             ))}
           </View>
         </Animated.View>
diff --git a/src/components/Card/Card.tsx b/src/components/Card/Card.tsx
index 6dc433322a..1e1677c5d2 100644
--- a/src/components/Card/Card.tsx
+++ b/src/components/Card/Card.tsx
@@ -127,8 +127,8 @@ export type Props = $Omit<React.ComponentProps<typeof Surface>, 'mode'> & {
  *     </Card.Content>
  *     <Card.Cover source={{ uri: 'https://picsum.photos/700' }} />
  *     <Card.Actions>
- *       <Button>Cancel</Button>
- *       <Button>Ok</Button>
+ *       <Button label="Cancel" />
+ *       <Button label="Ok" />
  *     </Card.Actions>
  *   </Card>
  * );
diff --git a/src/components/Card/CardActions.tsx b/src/components/Card/CardActions.tsx
index daa26a19fd..cee98b6f0d 100644
--- a/src/components/Card/CardActions.tsx
+++ b/src/components/Card/CardActions.tsx
@@ -25,8 +25,8 @@ export type Props = React.ComponentPropsWithRef<typeof View> & {
  * const MyComponent = () => (
  *   <Card>
  *     <Card.Actions>
- *       <Button>Cancel</Button>
- *       <Button>Ok</Button>
+ *       <Button label="Cancel" />
+ *       <Button label="Ok" />
  *     </Card.Actions>
  *   </Card>
  * );
diff --git a/src/components/DataTable/DataTablePagination.tsx b/src/components/DataTable/DataTablePagination.tsx
index 5e26051819..0d0b1a7f93 100644
--- a/src/components/DataTable/DataTablePagination.tsx
+++ b/src/components/DataTable/DataTablePagination.tsx
@@ -183,9 +183,8 @@ const PaginationDropdown = ({
           icon="menu-down"
           contentStyle={styles.contentStyle}
           theme={theme}
-        >
-          {`${numberOfItemsPerPage}`}
-        </Button>
+          label={`${numberOfItemsPerPage}`}
+        />
       }
     >
       {numberOfItemsPerPageList?.map((option) => (
diff --git a/src/components/Dialog/Dialog.tsx b/src/components/Dialog/Dialog.tsx
index 717445aed7..e2f9ec2491 100644
--- a/src/components/Dialog/Dialog.tsx
+++ b/src/components/Dialog/Dialog.tsx
@@ -73,7 +73,7 @@ const DIALOG_ELEVATION: number = 24;
  *   return (
  *     <PaperProvider>
  *       <View>
- *         <Button onPress={showDialog}>Show Dialog</Button>
+ *         <Button onPress={showDialog} label="Show Dialog" />
  *         <Portal>
  *           <Dialog visible={visible} onDismiss={hideDialog}>
  *             <Dialog.Title>Alert</Dialog.Title>
@@ -81,7 +81,7 @@ const DIALOG_ELEVATION: number = 24;
  *               <Text variant="bodyMedium">This is simple dialog</Text>
  *             </Dialog.Content>
  *             <Dialog.Actions>
- *               <Button onPress={hideDialog}>Done</Button>
+ *               <Button onPress={hideDialog} label="Done" />
  *             </Dialog.Actions>
  *           </Dialog>
  *         </Portal>
diff --git a/src/components/Dialog/DialogActions.tsx b/src/components/Dialog/DialogActions.tsx
index 0c8d8c5f74..b3b532416d 100644
--- a/src/components/Dialog/DialogActions.tsx
+++ b/src/components/Dialog/DialogActions.tsx
@@ -34,8 +34,8 @@ export type Props = React.ComponentPropsWithRef<typeof View> & {
  *     <Portal>
  *       <Dialog visible={visible} onDismiss={hideDialog}>
  *         <Dialog.Actions>
- *           <Button onPress={() => console.log('Cancel')}>Cancel</Button>
- *           <Button onPress={() => console.log('Ok')}>Ok</Button>
+ *           <Button onPress={() => console.log('Cancel')} label="Cancel" />
+ *           <Button onPress={() => console.log('Ok')} label="Ok" />
  *         </Dialog.Actions>
  *       </Dialog>
  *     </Portal>
diff --git a/src/components/Menu/Menu.tsx b/src/components/Menu/Menu.tsx
index 832eac30bb..5ff69f48ca 100644
--- a/src/components/Menu/Menu.tsx
+++ b/src/components/Menu/Menu.tsx
@@ -154,7 +154,7 @@ const isBrowser = () => Platform.OS === 'web' && 'document' in global;
  *         <Menu
  *           visible={visible}
  *           onDismiss={closeMenu}
- *           anchor={<Button onPress={openMenu}>Show menu</Button>}>
+ *           anchor={<Button onPress={openMenu} label="Show menu" />}>
  *           <Menu.Item onPress={() => {}} title="Item 1" />
  *           <Menu.Item onPress={() => {}} title="Item 2" />
  *           <Divider />
diff --git a/src/components/Modal.tsx b/src/components/Modal.tsx
index 7cce27eb3c..c9cc80d42e 100644
--- a/src/components/Modal.tsx
+++ b/src/components/Modal.tsx
@@ -93,9 +93,7 @@ const AnimatedPressable = Animated.createAnimatedComponent(Pressable);
  *           <Text>Example Modal.  Click outside this area to dismiss.</Text>
  *         </Modal>
  *       </Portal>
- *       <Button style={{ marginTop: 30 }} onPress={showModal}>
- *         Show
- *       </Button>
+ *       <Button style={{ marginTop: 30 }} onPress={showModal} label="Show" />
  *     </PaperProvider>
  *   );
  * };
diff --git a/src/components/Snackbar.tsx b/src/components/Snackbar.tsx
index f6eb590e84..30d553114c 100644
--- a/src/components/Snackbar.tsx
+++ b/src/components/Snackbar.tsx
@@ -113,7 +113,7 @@ const DURATION_LONG = 10000;
  *
  *   return (
  *     <View style={styles.container}>
- *       <Button onPress={onToggleSnackBar}>{visible ? 'Hide' : 'Show'}</Button>
+ *       <Button onPress={onToggleSnackBar} label={visible ? 'Hide' : 'Show'} />
  *       <Snackbar
  *         visible={visible}
  *         onDismiss={onDismissSnackBar}
@@ -330,10 +330,9 @@ const Snackbar = ({
                 compact={false}
                 mode="text"
                 theme={theme}
+                label={actionLabel}
                 {...actionProps}
-              >
-                {actionLabel}
-              </Button>
+              />
             ) : null}
             {isIconButton ? (
               <IconButton
diff --git a/src/components/__tests__/Card/Card.test.tsx b/src/components/__tests__/Card/Card.test.tsx
index b11e006445..95cebf98ec 100644
--- a/src/components/__tests__/Card/Card.test.tsx
+++ b/src/components/__tests__/Card/Card.test.tsx
@@ -132,7 +132,7 @@ describe('CardActions', () => {
     const { getByTestId } = render(
       <Card>
         <Card.Actions testID="card-actions">
-          <Button mode="contained">Agree</Button>
+          <Button mode="contained" label="Agree" />
         </Card.Actions>
       </Card>
     );
@@ -150,9 +150,8 @@ describe('CardActions', () => {
             testID="card-actions-button"
             mode="contained"
             style={styles.customBorderRadius}
-          >
-            Agree
-          </Button>
+            label="Agree"
+          />
         </Card.Actions>
       </Card>
     );
diff --git a/src/components/__tests__/Dialog.test.tsx b/src/components/__tests__/Dialog.test.tsx
index 742f44b941..47a6409c58 100644
--- a/src/components/__tests__/Dialog.test.tsx
+++ b/src/components/__tests__/Dialog.test.tsx
@@ -110,8 +110,8 @@ describe('DialogActions', () => {
   it('should render passed children', () => {
     const { getByTestId } = render(
       <Dialog.Actions>
-        <Button testID="button-cancel">Cancel</Button>
-        <Button testID="button-ok">Ok</Button>
+        <Button testID="button-cancel" label="Cancel" />
+        <Button testID="button-ok" label="Ok" />
       </Dialog.Actions>
     );
 
@@ -122,8 +122,8 @@ describe('DialogActions', () => {
   it('should apply default styles', () => {
     const { getByTestId } = render(
       <Dialog.Actions testID="dialog-actions">
-        <Button>Cancel</Button>
-        <Button>Ok</Button>
+        <Button label="Cancel" />
+        <Button label="Ok" />
       </Dialog.Actions>
     );
 
@@ -141,8 +141,8 @@ describe('DialogActions', () => {
   it('should apply custom styles', () => {
     const { getByTestId } = render(
       <Dialog.Actions testID="dialog-actions">
-        <Button style={styles.spacing}>Cancel</Button>
-        <Button style={styles.noSpacing}>Ok</Button>
+        <Button style={styles.spacing} label="Cancel" />
+        <Button style={styles.noSpacing} label="Ok" />
       </Dialog.Actions>
     );
 
diff --git a/src/components/__tests__/Menu.test.tsx b/src/components/__tests__/Menu.test.tsx
index 9147ad456a..e71cb70d89 100644
--- a/src/components/__tests__/Menu.test.tsx
+++ b/src/components/__tests__/Menu.test.tsx
@@ -23,7 +23,7 @@ it('renders visible menu', () => {
       <Menu
         visible
         onDismiss={jest.fn()}
-        anchor={<Button mode="outlined">Open menu</Button>}
+        anchor={<Button mode="outlined" label="Open menu" />}
       >
         <Menu.Item onPress={jest.fn()} title="Undo" />
         <Menu.Item onPress={jest.fn()} title="Redo" />
@@ -40,7 +40,7 @@ it('renders not visible menu', () => {
       <Menu
         visible={false}
         onDismiss={jest.fn()}
-        anchor={<Button mode="outlined">Open menu</Button>}
+        anchor={<Button mode="outlined" label="Open menu" />}
       >
         <Menu.Item onPress={jest.fn()} title="Undo" />
         <Menu.Item onPress={jest.fn()} title="Redo" />
@@ -57,7 +57,7 @@ it('renders menu with content styles', () => {
       <Menu
         visible
         onDismiss={jest.fn()}
-        anchor={<Button mode="outlined">Open menu</Button>}
+        anchor={<Button mode="outlined" label="Open menu" />}
         contentStyle={styles.contentStyle}
       >
         <Menu.Item onPress={jest.fn()} title="Undo" />
@@ -78,7 +78,7 @@ it('renders menu with content styles', () => {
         <Menu
           visible
           onDismiss={jest.fn()}
-          anchor={<Button mode="outlined">Open menu</Button>}
+          anchor={<Button mode="outlined" label="Open menu" />}
           elevation={elevation}
         >
           <Menu.Item onPress={jest.fn()} title="Undo" />
@@ -110,11 +110,7 @@ it('uses the default anchorPosition of top', async () => {
         <Menu
           visible={visible}
           onDismiss={jest.fn()}
-          anchor={
-            <Button mode="outlined" testID="anchor">
-              Open menu
-            </Button>
-          }
+          anchor={<Button mode="outlined" testID="anchor" label="Open menu" />}
           contentStyle={styles.contentStyle}
         >
           <Menu.Item onPress={jest.fn()} title="Undo" />
@@ -166,11 +162,7 @@ it('respects anchorPosition bottom', async () => {
         <Menu
           visible={visible}
           onDismiss={jest.fn()}
-          anchor={
-            <Button mode="outlined" testID="anchor">
-              Open menu
-            </Button>
-          }
+          anchor={<Button mode="outlined" testID="anchor" label="Open menu" />}
           anchorPosition="bottom"
           contentStyle={styles.contentStyle}
         >
@@ -209,7 +201,7 @@ it('animated value changes correctly', () => {
       <Menu
         visible
         onDismiss={jest.fn()}
-        anchor={<Button mode="outlined">Open menu</Button>}
+        anchor={<Button mode="outlined" label="Open menu" />}
         testID="menu"
         contentStyle={[{ transform: [{ scale: value }] }]}
       >
@@ -241,7 +233,7 @@ it('renders menu with mode "elevated"', () => {
       <Menu
         visible
         onDismiss={jest.fn()}
-        anchor={<Button mode="outlined">Open menu</Button>}
+        anchor={<Button mode="outlined" label="Open menu" />}
         mode="elevated"
       >
         <Menu.Item onPress={jest.fn()} title="Undo" />
@@ -265,7 +257,7 @@ it('renders menu with mode "flat"', () => {
       <Menu
         visible
         onDismiss={jest.fn()}
-        anchor={<Button mode="outlined">Open menu</Button>}
+        anchor={<Button mode="outlined" label="Open menu" />}
         mode="flat"
       >
         <Menu.Item onPress={jest.fn()} title="Undo" />

From 322c3a53d42442c730975ff312bf760e8bf62576 Mon Sep 17 00:00:00 2001
From: Aziz Becha <aziz07becha@gmail.com>
Date: Tue, 12 May 2026 21:30:04 +0100
Subject: [PATCH 03/24] feat: add Button iconPosition prop

Add an `iconPosition?: 'leading' | 'trailing'` prop to control where the
icon sits relative to the label. The previous approach of setting
`contentStyle={{ flexDirection: 'row-reverse' }}` still works but is now
deprecated and emits a dev-only warning.

The icon margins are extracted into a `getButtonIconStyle` helper,
replacing the previous matrix of computed StyleSheet keys, and
DataTablePagination is updated to use the new prop.
---
 src/components/Button/Button.tsx              | 96 ++++++++-----------
 src/components/Button/utils.tsx               | 35 +++++++
 .../DataTable/DataTablePagination.tsx         |  5 +-
 src/components/__tests__/Button.test.tsx      | 52 ++++++++++
 .../__snapshots__/Banner.test.tsx.snap        |  4 +
 .../__snapshots__/Button.test.tsx.snap        | 69 ++++++-------
 .../__snapshots__/DataTable.test.tsx.snap     | 20 ++--
 .../__snapshots__/Menu.test.tsx.snap          |  3 +
 .../__snapshots__/Snackbar.test.tsx.snap      |  1 +
 9 files changed, 169 insertions(+), 116 deletions(-)

diff --git a/src/components/Button/Button.tsx b/src/components/Button/Button.tsx
index 1e4493f1db..4edd23b9b9 100644
--- a/src/components/Button/Button.tsx
+++ b/src/components/Button/Button.tsx
@@ -16,6 +16,7 @@ import {
 import {
   ButtonMode,
   getButtonColors,
+  getButtonIconStyle,
   getButtonTouchableRippleStyle,
 } from './utils';
 import { useInternalTheme } from '../../core/theming';
@@ -70,6 +71,10 @@ export type Props = $Omit<
    * Icon to display for the `Button`.
    */
   icon?: IconSource;
+  /**
+   * Position of the `icon` relative to the label. Defaults to `'leading'`.
+   */
+  iconPosition?: 'leading' | 'trailing';
   /**
    * Whether the button is disabled. A disabled button is greyed out and `onPress` is not called on touch.
    */
@@ -126,7 +131,10 @@ export type Props = $Omit<
   delayLongPress?: number;
   /**
    * Style of button's inner content.
-   * Use this prop to apply custom height and width, to set a custom padding or to set the icon on the right with `flexDirection: 'row-reverse'`.
+   * Use this prop to apply custom height and width or to set a custom padding.
+   *
+   * Note: setting `flexDirection: 'row-reverse'` here to move the icon to the
+   * trailing edge is deprecated — use the `iconPosition` prop instead.
    */
   contentStyle?: StyleProp<ViewStyle>;
   /**
@@ -184,6 +192,7 @@ const Button = (
     dark,
     loading,
     icon,
+    iconPosition,
     buttonColor: customButtonColor,
     textColor: customTextColor,
     label,
@@ -230,6 +239,20 @@ const Button = (
 
   const labelContent = label != null ? label : children;
 
+  const flattenedContentStyle = StyleSheet.flatten(contentStyle) as
+    | ViewStyle
+    | undefined;
+  const usesReverseContentStyle =
+    flattenedContentStyle?.flexDirection === 'row-reverse';
+
+  if (process.env.NODE_ENV !== 'production' && usesReverseContentStyle) {
+    console.warn(
+      'Button: setting `flexDirection: \'row-reverse\'` in `contentStyle` to move the icon to the trailing edge is deprecated. Use the `iconPosition="trailing"` prop instead.'
+    );
+  }
+
+  const isTrailingIcon = iconPosition === 'trailing' || usesReverseContentStyle;
+
   const hasPassedTouchHandler = hasTouchHandler({
     onPress,
     onPressIn,
@@ -328,20 +351,11 @@ const Button = (
     ...font,
   };
 
-  const iconStyle =
-    StyleSheet.flatten(contentStyle)?.flexDirection === 'row-reverse'
-      ? [
-          styles.iconReverse,
-          styles[`md3IconReverse${compact ? 'Compact' : ''}`],
-          isMode('text') &&
-            styles[`md3IconReverseTextMode${compact ? 'Compact' : ''}`],
-        ]
-      : [
-          styles.icon,
-          styles[`md3Icon${compact ? 'Compact' : ''}`],
-          isMode('text') &&
-            styles[`md3IconTextMode${compact ? 'Compact' : ''}`],
-        ];
+  const iconStyle = getButtonIconStyle({
+    mode,
+    compact,
+    position: isTrailingIcon ? 'trailing' : 'leading',
+  });
 
   return (
     <Surface
@@ -392,7 +406,14 @@ const Button = (
         theme={theme}
         ref={touchableRef}
       >
-        <View style={[styles.content, { opacity: textOpacity }, contentStyle]}>
+        <View
+          style={[
+            styles.content,
+            isTrailingIcon && styles.contentReverse,
+            { opacity: textOpacity },
+            contentStyle,
+          ]}
+        >
           {icon && loading !== true ? (
             <View style={iconStyle} testID={`${testID}-icon-container`}>
               <Icon
@@ -457,48 +478,9 @@ const styles = StyleSheet.create({
     alignItems: 'center',
     justifyContent: 'center',
   },
-  icon: {
-    marginLeft: 12,
-    marginRight: -4,
-  },
-  iconReverse: {
-    marginRight: 12,
-    marginLeft: -4,
-  },
-  /* eslint-disable react-native/no-unused-styles */
-  md3Icon: {
-    marginLeft: 16,
-    marginRight: -16,
-  },
-  md3IconCompact: {
-    marginLeft: 8,
-    marginRight: 0,
-  },
-  md3IconReverse: {
-    marginLeft: -16,
-    marginRight: 16,
-  },
-  md3IconReverseCompact: {
-    marginLeft: 0,
-    marginRight: 8,
-  },
-  md3IconTextMode: {
-    marginLeft: 12,
-    marginRight: -8,
-  },
-  md3IconTextModeCompact: {
-    marginLeft: 6,
-    marginRight: 0,
-  },
-  md3IconReverseTextMode: {
-    marginLeft: -8,
-    marginRight: 12,
-  },
-  md3IconReverseTextModeCompact: {
-    marginLeft: 0,
-    marginRight: 6,
+  contentReverse: {
+    flexDirection: 'row-reverse',
   },
-  /* eslint-enable react-native/no-unused-styles */
   label: {
     textAlign: 'center',
     marginVertical: 9,
diff --git a/src/components/Button/utils.tsx b/src/components/Button/utils.tsx
index 03ce9513ea..96b86af25c 100644
--- a/src/components/Button/utils.tsx
+++ b/src/components/Button/utils.tsx
@@ -14,6 +14,41 @@ export type ButtonMode =
   | 'elevated'
   | 'contained-tonal';
 
+export type ButtonIconPosition = 'leading' | 'trailing';
+
+/**
+ * Returns the margins applied to the button's icon (or loading indicator)
+ * depending on the button mode, density and the position of the icon relative
+ * to the label.
+ */
+export const getButtonIconStyle = ({
+  mode,
+  compact,
+  position,
+}: {
+  mode: ButtonMode;
+  compact?: boolean;
+  position: ButtonIconPosition;
+}): Pick<ViewStyle, 'marginLeft' | 'marginRight'> => {
+  const isTextMode = mode === 'text';
+
+  if (position === 'trailing') {
+    if (compact) {
+      return { marginLeft: 0, marginRight: isTextMode ? 6 : 8 };
+    }
+    return isTextMode
+      ? { marginLeft: -8, marginRight: 12 }
+      : { marginLeft: -16, marginRight: 16 };
+  }
+
+  if (compact) {
+    return { marginLeft: isTextMode ? 6 : 8, marginRight: 0 };
+  }
+  return isTextMode
+    ? { marginLeft: 12, marginRight: -8 }
+    : { marginLeft: 16, marginRight: -16 };
+};
+
 type BaseProps = {
   isMode: (mode: ButtonMode) => boolean;
   theme: InternalTheme;
diff --git a/src/components/DataTable/DataTablePagination.tsx b/src/components/DataTable/DataTablePagination.tsx
index 0d0b1a7f93..890202f75e 100644
--- a/src/components/DataTable/DataTablePagination.tsx
+++ b/src/components/DataTable/DataTablePagination.tsx
@@ -181,7 +181,7 @@ const PaginationDropdown = ({
           onPress={() => toggleSelect(true)}
           style={styles.button}
           icon="menu-down"
-          contentStyle={styles.contentStyle}
+          iconPosition="trailing"
           theme={theme}
           label={`${numberOfItemsPerPage}`}
         />
@@ -358,9 +358,6 @@ const styles = StyleSheet.create({
   iconsContainer: {
     flexDirection: 'row',
   },
-  contentStyle: {
-    flexDirection: 'row-reverse',
-  },
 });
 
 export default DataTablePagination;
diff --git a/src/components/__tests__/Button.test.tsx b/src/components/__tests__/Button.test.tsx
index 153bec346e..2c351535a5 100644
--- a/src/components/__tests__/Button.test.tsx
+++ b/src/components/__tests__/Button.test.tsx
@@ -357,6 +357,58 @@ describe('button icon styles', () => {
   );
 });
 
+describe('icon position', () => {
+  it('places the icon before the label by default', () => {
+    const { getByTestId } = render(
+      <Button testID="button" mode="outlined" icon="camera" label="Press me" />
+    );
+
+    expect(getByTestId('button-icon-container')).toHaveStyle({
+      marginLeft: 16,
+      marginRight: -16,
+    });
+  });
+
+  it('places the icon after the label when iconPosition is "trailing"', () => {
+    const { getByTestId } = render(
+      <Button
+        testID="button"
+        mode="outlined"
+        icon="chevron-right"
+        iconPosition="trailing"
+        label="Next"
+      />
+    );
+
+    expect(getByTestId('button-icon-container')).toHaveStyle({
+      marginLeft: -16,
+      marginRight: 16,
+    });
+  });
+
+  it('still flips the icon via the deprecated contentStyle row-reverse and warns', () => {
+    const warn = jest.spyOn(console, 'warn').mockImplementation(() => {});
+    const { getByTestId } = render(
+      <Button
+        testID="button"
+        mode="outlined"
+        icon="chevron-right"
+        contentStyle={styles.flexing}
+        label="Next"
+      />
+    );
+
+    expect(getByTestId('button-icon-container')).toHaveStyle({
+      marginLeft: -16,
+      marginRight: 16,
+    });
+    expect(warn).toHaveBeenCalledWith(
+      expect.stringContaining('`contentStyle`')
+    );
+    warn.mockRestore();
+  });
+});
+
 describe('getButtonColors - background color', () => {
   const customButtonColor = '#111111';
 
diff --git a/src/components/__tests__/__snapshots__/Banner.test.tsx.snap b/src/components/__tests__/__snapshots__/Banner.test.tsx.snap
index 2b7d4fd813..c27ef0c407 100644
--- a/src/components/__tests__/__snapshots__/Banner.test.tsx.snap
+++ b/src/components/__tests__/__snapshots__/Banner.test.tsx.snap
@@ -208,6 +208,7 @@ exports[`render visible banner, with custom theme 1`] = `
                         "flexDirection": "row",
                         "justifyContent": "center",
                       },
+                      false,
                       {
                         "opacity": 1,
                       },
@@ -641,6 +642,7 @@ exports[`renders visible banner, with action buttons and with image 1`] = `
                         "flexDirection": "row",
                         "justifyContent": "center",
                       },
+                      false,
                       {
                         "opacity": 1,
                       },
@@ -917,6 +919,7 @@ exports[`renders visible banner, with action buttons and without image 1`] = `
                         "flexDirection": "row",
                         "justifyContent": "center",
                       },
+                      false,
                       {
                         "opacity": 1,
                       },
@@ -1069,6 +1072,7 @@ exports[`renders visible banner, with action buttons and without image 1`] = `
                         "flexDirection": "row",
                         "justifyContent": "center",
                       },
+                      false,
                       {
                         "opacity": 1,
                       },
diff --git a/src/components/__tests__/__snapshots__/Button.test.tsx.snap b/src/components/__tests__/__snapshots__/Button.test.tsx.snap
index 992205a103..069451e1a4 100644
--- a/src/components/__tests__/__snapshots__/Button.test.tsx.snap
+++ b/src/components/__tests__/__snapshots__/Button.test.tsx.snap
@@ -92,6 +92,7 @@ exports[`renders button with an accessibility hint 1`] = `
               "flexDirection": "row",
               "justifyContent": "center",
             },
+            false,
             {
               "opacity": 1,
             },
@@ -245,6 +246,7 @@ exports[`renders button with an accessibility label 1`] = `
               "flexDirection": "row",
               "justifyContent": "center",
             },
+            false,
             {
               "opacity": 1,
             },
@@ -397,6 +399,7 @@ exports[`renders button with button color 1`] = `
               "flexDirection": "row",
               "justifyContent": "center",
             },
+            false,
             {
               "opacity": 1,
             },
@@ -549,6 +552,7 @@ exports[`renders button with color 1`] = `
               "flexDirection": "row",
               "justifyContent": "center",
             },
+            false,
             {
               "opacity": 1,
             },
@@ -701,6 +705,7 @@ exports[`renders button with custom testID 1`] = `
               "flexDirection": "row",
               "justifyContent": "center",
             },
+            false,
             {
               "opacity": 1,
             },
@@ -853,6 +858,7 @@ exports[`renders button with icon 1`] = `
               "flexDirection": "row",
               "justifyContent": "center",
             },
+            false,
             {
               "opacity": 1,
             },
@@ -862,20 +868,10 @@ exports[`renders button with icon 1`] = `
       >
         <View
           style={
-            [
-              {
-                "marginLeft": 12,
-                "marginRight": -4,
-              },
-              {
-                "marginLeft": 16,
-                "marginRight": -16,
-              },
-              {
-                "marginLeft": 12,
-                "marginRight": -8,
-              },
-            ]
+            {
+              "marginLeft": 12,
+              "marginRight": -8,
+            }
           }
           testID="button-icon-container"
         >
@@ -1054,6 +1050,9 @@ exports[`renders button with icon in reverse order 1`] = `
               "flexDirection": "row",
               "justifyContent": "center",
             },
+            {
+              "flexDirection": "row-reverse",
+            },
             {
               "opacity": 1,
             },
@@ -1065,20 +1064,10 @@ exports[`renders button with icon in reverse order 1`] = `
       >
         <View
           style={
-            [
-              {
-                "marginLeft": -4,
-                "marginRight": 12,
-              },
-              {
-                "marginLeft": -16,
-                "marginRight": 16,
-              },
-              {
-                "marginLeft": -8,
-                "marginRight": 12,
-              },
-            ]
+            {
+              "marginLeft": -8,
+              "marginRight": 12,
+            }
           }
           testID="button-icon-container"
         >
@@ -1257,6 +1246,7 @@ exports[`renders contained contained with mode 1`] = `
               "flexDirection": "row",
               "justifyContent": "center",
             },
+            false,
             {
               "opacity": 1,
             },
@@ -1410,6 +1400,7 @@ exports[`renders disabled button 1`] = `
               "flexDirection": "row",
               "justifyContent": "center",
             },
+            false,
             {
               "opacity": 0.38,
             },
@@ -1562,6 +1553,7 @@ exports[`renders loading button 1`] = `
               "flexDirection": "row",
               "justifyContent": "center",
             },
+            false,
             {
               "opacity": 1,
             },
@@ -1583,20 +1575,10 @@ exports[`renders loading button 1`] = `
                 "alignItems": "center",
                 "justifyContent": "center",
               },
-              [
-                {
-                  "marginLeft": 12,
-                  "marginRight": -4,
-                },
-                {
-                  "marginLeft": 16,
-                  "marginRight": -16,
-                },
-                {
-                  "marginLeft": 12,
-                  "marginRight": -8,
-                },
-              ],
+              {
+                "marginLeft": 12,
+                "marginRight": -8,
+              },
             ]
           }
         >
@@ -1922,6 +1904,7 @@ exports[`renders outlined button with mode 1`] = `
               "flexDirection": "row",
               "justifyContent": "center",
             },
+            false,
             {
               "opacity": 1,
             },
@@ -2075,6 +2058,7 @@ exports[`renders text button by default 1`] = `
               "flexDirection": "row",
               "justifyContent": "center",
             },
+            false,
             {
               "opacity": 1,
             },
@@ -2227,6 +2211,7 @@ exports[`renders text button with mode 1`] = `
               "flexDirection": "row",
               "justifyContent": "center",
             },
+            false,
             {
               "opacity": 1,
             },
diff --git a/src/components/__tests__/__snapshots__/DataTable.test.tsx.snap b/src/components/__tests__/__snapshots__/DataTable.test.tsx.snap
index 0f997739ba..f486d1db3e 100644
--- a/src/components/__tests__/__snapshots__/DataTable.test.tsx.snap
+++ b/src/components/__tests__/__snapshots__/DataTable.test.tsx.snap
@@ -1788,27 +1788,21 @@ exports[`DataTable.Pagination renders data table pagination with options select
                     "justifyContent": "center",
                   },
                   {
-                    "opacity": 1,
+                    "flexDirection": "row-reverse",
                   },
                   {
-                    "flexDirection": "row-reverse",
+                    "opacity": 1,
                   },
+                  undefined,
                 ]
               }
             >
               <View
                 style={
-                  [
-                    {
-                      "marginLeft": -4,
-                      "marginRight": 12,
-                    },
-                    {
-                      "marginLeft": -16,
-                      "marginRight": 16,
-                    },
-                    false,
-                  ]
+                  {
+                    "marginLeft": -16,
+                    "marginRight": 16,
+                  }
                 }
                 testID="button-icon-container"
               >
diff --git a/src/components/__tests__/__snapshots__/Menu.test.tsx.snap b/src/components/__tests__/__snapshots__/Menu.test.tsx.snap
index ee711c93f8..40aba65e7c 100644
--- a/src/components/__tests__/__snapshots__/Menu.test.tsx.snap
+++ b/src/components/__tests__/__snapshots__/Menu.test.tsx.snap
@@ -104,6 +104,7 @@ exports[`renders menu with content styles 1`] = `
                     "flexDirection": "row",
                     "justifyContent": "center",
                   },
+                  false,
                   {
                     "opacity": 1,
                   },
@@ -667,6 +668,7 @@ exports[`renders not visible menu 1`] = `
                   "flexDirection": "row",
                   "justifyContent": "center",
                 },
+                false,
                 {
                   "opacity": 1,
                 },
@@ -835,6 +837,7 @@ exports[`renders visible menu 1`] = `
                     "flexDirection": "row",
                     "justifyContent": "center",
                   },
+                  false,
                   {
                     "opacity": 1,
                   },
diff --git a/src/components/__tests__/__snapshots__/Snackbar.test.tsx.snap b/src/components/__tests__/__snapshots__/Snackbar.test.tsx.snap
index bc4642cc3f..c808c020d3 100644
--- a/src/components/__tests__/__snapshots__/Snackbar.test.tsx.snap
+++ b/src/components/__tests__/__snapshots__/Snackbar.test.tsx.snap
@@ -410,6 +410,7 @@ exports[`renders snackbar with action button 1`] = `
                       "flexDirection": "row",
                       "justifyContent": "center",
                     },
+                    false,
                     {
                       "opacity": 1,
                     },

From 1130ddf27c32b558ec0698e7bd49c0fadd75fe29 Mon Sep 17 00:00:00 2001
From: Aziz Becha <aziz07becha@gmail.com>
Date: Tue, 12 May 2026 21:50:56 +0100
Subject: [PATCH 04/24] feat: derive Button ripple color from label color

Add a `rippleColor?: ColorValue` prop and, by default, drive the ripple
/ state layer with the label color at the pressed-state opacity (per
Material Design 3) instead of TouchableRipple's onSurface-based default.

The color is computed by a new `getButtonRippleColor` helper, which
falls back to `undefined` (TouchableRipple's own default) when the
label color is not a plain string, e.g. an Android Material You
PlatformColor.
---
 src/components/Button/Button.tsx         | 10 ++++++++
 src/components/Button/utils.tsx          | 29 ++++++++++++++++++++++++
 src/components/__tests__/Button.test.tsx | 25 ++++++++++++++++++--
 3 files changed, 62 insertions(+), 2 deletions(-)

diff --git a/src/components/Button/Button.tsx b/src/components/Button/Button.tsx
index 4edd23b9b9..73bb6e67ae 100644
--- a/src/components/Button/Button.tsx
+++ b/src/components/Button/Button.tsx
@@ -17,6 +17,7 @@ import {
   ButtonMode,
   getButtonColors,
   getButtonIconStyle,
+  getButtonRippleColor,
   getButtonTouchableRippleStyle,
 } from './utils';
 import { useInternalTheme } from '../../core/theming';
@@ -97,6 +98,11 @@ export type Props = $Omit<
    * https://reactnative.dev/docs/pressable#rippleconfig
    */
   background?: PressableAndroidRippleConfig;
+  /**
+   * Color of the ripple effect / state layer. Defaults to the label color at
+   * the pressed-state opacity.
+   */
+  rippleColor?: ColorValue;
   /**
    * Accessibility label for the button. This is read by the screen reader when the user taps the button.
    */
@@ -214,6 +220,7 @@ const Button = (
     testID = 'button',
     accessible,
     background,
+    rippleColor: customRippleColor,
     maxFontSizeMultiplier,
     touchableRef,
     ...rest
@@ -329,6 +336,8 @@ const Button = (
     dark,
   });
 
+  const rippleColor = getButtonRippleColor({ textColor, customRippleColor });
+
   const touchableStyle = {
     ...borderRadiusStyles,
     borderRadius: borderRadiusStyles.borderRadius ?? borderRadius,
@@ -389,6 +398,7 @@ const Button = (
       <TouchableRipple
         borderless
         background={background}
+        rippleColor={rippleColor}
         onPress={onPress}
         onLongPress={onLongPress}
         onPressIn={hasPassedTouchHandler ? handlePressIn : undefined}
diff --git a/src/components/Button/utils.tsx b/src/components/Button/utils.tsx
index 96b86af25c..cf41e4b9e6 100644
--- a/src/components/Button/utils.tsx
+++ b/src/components/Button/utils.tsx
@@ -1,5 +1,7 @@
 import type { ColorValue, ViewStyle } from 'react-native';
 
+import color from 'color';
+
 import { black, white } from '../../theme/colors';
 import { tokens } from '../../theme/tokens';
 import type { InternalTheme, Theme } from '../../types';
@@ -226,6 +228,33 @@ export const getButtonColors = ({
   };
 };
 
+/**
+ * Returns the color used for the button's ripple / state layer. Defaults to
+ * the label color at the pressed-state opacity (per Material Design 3), unless
+ * a custom ripple color is provided.
+ *
+ * When the label color is not a plain string (e.g. an Android Material You
+ * `PlatformColor`), `undefined` is returned so `TouchableRipple` falls back to
+ * its own default state-layer color.
+ */
+export const getButtonRippleColor = ({
+  textColor,
+  customRippleColor,
+}: {
+  textColor: ColorValue;
+  customRippleColor?: ColorValue;
+}): ColorValue | undefined => {
+  if (customRippleColor) {
+    return customRippleColor;
+  }
+
+  if (typeof textColor !== 'string') {
+    return undefined;
+  }
+
+  return color(textColor).alpha(stateOpacity.pressed).rgb().string();
+};
+
 type ViewStyleBorderRadiusStyles = Partial<
   Pick<
     ViewStyle,
diff --git a/src/components/__tests__/Button.test.tsx b/src/components/__tests__/Button.test.tsx
index 2c351535a5..94cf3ab0db 100644
--- a/src/components/__tests__/Button.test.tsx
+++ b/src/components/__tests__/Button.test.tsx
@@ -1,14 +1,15 @@
 import * as React from 'react';
-import { Animated, StyleSheet } from 'react-native';
+import { Animated, PlatformColor, StyleSheet } from 'react-native';
 
 import { act, fireEvent } from '@testing-library/react-native';
+import color from 'color';
 
 import { getTheme } from '../../core/theming';
 import { render } from '../../test-utils';
 import { pink500, white } from '../../theme/colors';
 import { tokens } from '../../theme/tokens';
 import Button from '../Button/Button';
-import { getButtonColors } from '../Button/utils';
+import { getButtonColors, getButtonRippleColor } from '../Button/utils';
 
 const { stateOpacity } = tokens.md.ref;
 
@@ -804,6 +805,26 @@ describe('getButtonColors - border width', () => {
   );
 });
 
+describe('getButtonRippleColor', () => {
+  it('returns the custom ripple color when one is provided', () => {
+    expect(
+      getButtonRippleColor({ textColor: '#123456', customRippleColor: 'red' })
+    ).toBe('red');
+  });
+
+  it('defaults to the label color at the pressed-state opacity', () => {
+    expect(getButtonRippleColor({ textColor: '#123456' })).toBe(
+      color('#123456').alpha(stateOpacity.pressed).rgb().string()
+    );
+  });
+
+  it('returns undefined when the label color is not a plain string', () => {
+    expect(
+      getButtonRippleColor({ textColor: PlatformColor('?attr/colorPrimary') })
+    ).toBeUndefined();
+  });
+});
+
 it('animated value changes correctly', () => {
   const value = new Animated.Value(1);
   const { getByTestId } = render(

From a7b1b6d6748d90fd6b5849b61a4905497bae5d90 Mon Sep 17 00:00:00 2001
From: Aziz Becha <aziz07becha@gmail.com>
Date: Tue, 12 May 2026 22:12:50 +0100
Subject: [PATCH 05/24] perf: memoize Button's derived values and handlers

Wrap the expensive derived values (color computation, border-radius
extraction, ripple color, icon style, touchable ripple style, and the
flattened style objects) in `useMemo`, memoize the press handlers with
`useCallback`, and replace the `isMode` `useCallback` with a plain
local function. No behavior or render-output change.
---
 src/components/Button/Button.tsx | 188 +++++++++++++++++++------------
 1 file changed, 114 insertions(+), 74 deletions(-)

diff --git a/src/components/Button/Button.tsx b/src/components/Button/Button.tsx
index 73bb6e67ae..fc71192a2d 100644
--- a/src/components/Button/Button.tsx
+++ b/src/components/Button/Button.tsx
@@ -190,6 +190,13 @@ export type Props = $Omit<
  * export default MyComponent;
  * ```
  */
+
+// Elevation levels (MD3) used by the `elevated` mode: level 1 at rest,
+// level 2 while pressed.
+const initialElevation = 1;
+const activeElevation = 2;
+const iconSize = 18;
+
 const Button = (
   {
     disabled,
@@ -228,12 +235,7 @@ const Button = (
   ref: React.ForwardedRef<View>
 ) => {
   const theme = useInternalTheme(themeOverrides);
-  const isMode = React.useCallback(
-    (modeToCompare: ButtonMode) => {
-      return mode === modeToCompare;
-    },
-    [mode]
-  );
+  const isMode = (modeToCompare: ButtonMode) => mode === modeToCompare;
   const { animation } = theme;
   const uppercase = uppercaseProp ?? false;
   const isWeb = Platform.OS === 'web';
@@ -246,9 +248,10 @@ const Button = (
 
   const labelContent = label != null ? label : children;
 
-  const flattenedContentStyle = StyleSheet.flatten(contentStyle) as
-    | ViewStyle
-    | undefined;
+  const flattenedContentStyle = React.useMemo(
+    () => StyleSheet.flatten(contentStyle) as ViewStyle | undefined,
+    [contentStyle]
+  );
   const usesReverseContentStyle =
     flattenedContentStyle?.flexDirection === 'row-reverse';
 
@@ -268,8 +271,6 @@ const Button = (
   });
 
   const isElevationEntitled = !disabled && isMode('elevated');
-  const initialElevation = 1;
-  const activeElevation = 2;
 
   const { current: elevation } = React.useRef<Animated.Value>(
     new Animated.Value(isElevationEntitled ? initialElevation : 0)
@@ -283,42 +284,50 @@ const Button = (
       duration: 0,
       useNativeDriver: true,
     });
-  }, [isElevationEntitled, elevation, initialElevation]);
-
-  const handlePressIn = (e: GestureResponderEvent) => {
-    onPressIn?.(e);
-    if (isMode('elevated')) {
-      const { scale } = animation;
-      Animated.timing(elevation, {
-        toValue: activeElevation,
-        duration: 200 * scale,
-        useNativeDriver:
-          isWeb || Platform.constants.reactNativeVersion.minor <= 72,
-      }).start();
-    }
-  };
+  }, [isElevationEntitled, elevation]);
 
-  const handlePressOut = (e: GestureResponderEvent) => {
-    onPressOut?.(e);
-    if (isMode('elevated')) {
-      const { scale } = animation;
-      Animated.timing(elevation, {
-        toValue: initialElevation,
-        duration: 150 * scale,
-        useNativeDriver:
-          isWeb || Platform.constants.reactNativeVersion.minor <= 72,
-      }).start();
-    }
-  };
+  const handlePressIn = React.useCallback(
+    (e: GestureResponderEvent) => {
+      onPressIn?.(e);
+      if (mode === 'elevated') {
+        const { scale } = animation;
+        Animated.timing(elevation, {
+          toValue: activeElevation,
+          duration: 200 * scale,
+          useNativeDriver:
+            isWeb || Platform.constants.reactNativeVersion.minor <= 72,
+        }).start();
+      }
+    },
+    [onPressIn, mode, animation, elevation, isWeb]
+  );
 
-  const flattenedStyles = (StyleSheet.flatten(style) || {}) as ViewStyle;
-  const [, borderRadiusStyles] = splitStyles(
-    flattenedStyles,
-    (style) => style.startsWith('border') && style.endsWith('Radius')
+  const handlePressOut = React.useCallback(
+    (e: GestureResponderEvent) => {
+      onPressOut?.(e);
+      if (mode === 'elevated') {
+        const { scale } = animation;
+        Animated.timing(elevation, {
+          toValue: initialElevation,
+          duration: 150 * scale,
+          useNativeDriver:
+            isWeb || Platform.constants.reactNativeVersion.minor <= 72,
+        }).start();
+      }
+    },
+    [onPressOut, mode, animation, elevation, isWeb]
   );
 
+  const borderRadiusStyles = React.useMemo(() => {
+    const flattenedStyles = (StyleSheet.flatten(style) || {}) as ViewStyle;
+    const [, radiusStyles] = splitStyles(
+      flattenedStyles,
+      (key) => key.startsWith('border') && key.endsWith('Radius')
+    );
+    return radiusStyles;
+  }, [style]);
+
   const borderRadius = theme.shapes.corner.largeIncreased;
-  const iconSize = 18;
 
   const {
     backgroundColor,
@@ -327,44 +336,75 @@ const Button = (
     textOpacity,
     borderWidth,
     backgroundOpacity,
-  } = getButtonColors({
-    customButtonColor,
-    customTextColor,
-    theme,
-    mode,
-    disabled,
-    dark,
-  });
+  } = React.useMemo(
+    () =>
+      getButtonColors({
+        customButtonColor,
+        customTextColor,
+        theme,
+        mode,
+        disabled,
+        dark,
+      }),
+    [customButtonColor, customTextColor, theme, mode, disabled, dark]
+  );
 
-  const rippleColor = getButtonRippleColor({ textColor, customRippleColor });
+  const rippleColor = React.useMemo(
+    () => getButtonRippleColor({ textColor, customRippleColor }),
+    [textColor, customRippleColor]
+  );
 
-  const touchableStyle = {
-    ...borderRadiusStyles,
-    borderRadius: borderRadiusStyles.borderRadius ?? borderRadius,
-  };
+  const touchableStyle = React.useMemo(
+    () => ({
+      ...borderRadiusStyles,
+      borderRadius: borderRadiusStyles.borderRadius ?? borderRadius,
+    }),
+    [borderRadiusStyles, borderRadius]
+  );
 
-  const buttonStyle = {
-    backgroundColor: backgroundOpacity < 1 ? 'transparent' : backgroundColor,
-    borderColor,
-    borderWidth,
-    ...touchableStyle,
-  };
+  const buttonStyle = React.useMemo(
+    () => ({
+      backgroundColor: backgroundOpacity < 1 ? 'transparent' : backgroundColor,
+      borderColor,
+      borderWidth,
+      ...touchableStyle,
+    }),
+    [
+      backgroundOpacity,
+      backgroundColor,
+      borderColor,
+      borderWidth,
+      touchableStyle,
+    ]
+  );
 
-  const { color: customLabelColor, fontSize: customLabelSize } =
-    StyleSheet.flatten(labelStyle) || {};
+  const touchableRippleStyle = React.useMemo(
+    () => getButtonTouchableRippleStyle(touchableStyle, borderWidth),
+    [touchableStyle, borderWidth]
+  );
 
-  const font = (theme as Theme).fonts.labelLarge;
+  const { color: customLabelColor, fontSize: customLabelSize } = React.useMemo(
+    () => StyleSheet.flatten(labelStyle) || {},
+    [labelStyle]
+  );
 
-  const textStyle = {
-    color: textColor,
-    ...font,
-  };
+  const textStyle = React.useMemo(
+    () => ({
+      color: textColor,
+      ...(theme as Theme).fonts.labelLarge,
+    }),
+    [textColor, theme]
+  );
 
-  const iconStyle = getButtonIconStyle({
-    mode,
-    compact,
-    position: isTrailingIcon ? 'trailing' : 'leading',
-  });
+  const iconStyle = React.useMemo(
+    () =>
+      getButtonIconStyle({
+        mode,
+        compact,
+        position: isTrailingIcon ? 'trailing' : 'leading',
+      }),
+    [mode, compact, isTrailingIcon]
+  );
 
   return (
     <Surface
@@ -411,7 +451,7 @@ const Button = (
         accessible={accessible}
         hitSlop={hitSlop}
         disabled={disabled}
-        style={getButtonTouchableRippleStyle(touchableStyle, borderWidth)}
+        style={touchableRippleStyle}
         testID={testID}
         theme={theme}
         ref={touchableRef}

From 63275241505a5a43fa26f8b0130ddbb308adef10 Mon Sep 17 00:00:00 2001
From: Aziz Becha <aziz07becha@gmail.com>
Date: Tue, 12 May 2026 22:35:11 +0100
Subject: [PATCH 06/24] chore(example): migrate example app Buttons to label
 prop

Update the example screens to use the new `label` prop instead of
children, and the `iconPosition="trailing"` prop instead of the
`contentStyle={{ flexDirection: 'row-reverse' }}` hack.
---
 example/src/DrawerItems.tsx                   |   2 +-
 example/src/Examples/ButtonExample.tsx        | 256 +++++++++---------
 example/src/Examples/CardExample.tsx          |  12 +-
 example/src/Examples/DialogExample.tsx        |  35 +--
 .../Dialogs/DialogWithCustomColors.tsx        |   4 +-
 .../DialogWithDismissableBackButton.tsx       |   6 +-
 .../src/Examples/Dialogs/DialogWithIcon.tsx   |  10 +-
 .../Examples/Dialogs/DialogWithLongText.tsx   |   2 +-
 .../Examples/Dialogs/DialogWithRadioBtns.tsx  |   4 +-
 .../Examples/Dialogs/UndismissableDialog.tsx  |   6 +-
 example/src/Examples/MenuExample.tsx          |  24 +-
 example/src/Examples/ProgressBarExample.tsx   |  11 +-
 example/src/Examples/SnackbarExample.tsx      |   5 +-
 example/src/Examples/TeamDetails.tsx          |   8 +-
 14 files changed, 184 insertions(+), 201 deletions(-)

diff --git a/example/src/DrawerItems.tsx b/example/src/DrawerItems.tsx
index f9df80433c..fcfe677a2b 100644
--- a/example/src/DrawerItems.tsx
+++ b/example/src/DrawerItems.tsx
@@ -270,7 +270,7 @@ function DrawerItems() {
               <Text variant="labelMedium">example</Text> directory.
             </Text>
             <Dialog.Actions>
-              <Button onPress={_handleDismissRTLDialog}>Ok</Button>
+              <Button onPress={_handleDismissRTLDialog} label="Ok" />
             </Dialog.Actions>
           </Dialog.Content>
         </Dialog>
diff --git a/example/src/Examples/ButtonExample.tsx b/example/src/Examples/ButtonExample.tsx
index b56b0a8327..9b2884f24d 100644
--- a/example/src/Examples/ButtonExample.tsx
+++ b/example/src/Examples/ButtonExample.tsx
@@ -1,7 +1,7 @@
 import * as React from 'react';
 import { Image, StyleSheet, View } from 'react-native';
 
-import { Button, List, Text, useTheme } from 'react-native-paper';
+import { Button, List, useTheme } from 'react-native-paper';
 
 import ScreenWrapper from '../ScreenWrapper';
 
@@ -14,29 +14,38 @@ const ButtonExample = () => {
     <ScreenWrapper>
       <List.Section title="Text button (text)">
         <View style={styles.row}>
-          <Button onPress={() => {}} style={styles.button}>
-            Default
-          </Button>
-          <Button textColor={color} onPress={() => {}} style={styles.button}>
-            Custom
-          </Button>
-          <Button disabled onPress={() => {}} style={styles.button}>
-            Disabled
-          </Button>
-          <Button icon="camera" onPress={() => {}} style={styles.button}>
-            Icon
-          </Button>
-          <Button loading onPress={() => {}} style={styles.button}>
-            Loading
-          </Button>
+          <Button onPress={() => {}} style={styles.button} label="Default" />
+          <Button
+            textColor={color}
+            onPress={() => {}}
+            style={styles.button}
+            label="Custom"
+          />
+          <Button
+            disabled
+            onPress={() => {}}
+            style={styles.button}
+            label="Disabled"
+          />
           <Button
             icon="camera"
             onPress={() => {}}
             style={styles.button}
-            contentStyle={styles.flexReverse}
-          >
-            Icon right
-          </Button>
+            label="Icon"
+          />
+          <Button
+            loading
+            onPress={() => {}}
+            style={styles.button}
+            label="Loading"
+          />
+          <Button
+            icon="camera"
+            onPress={() => {}}
+            style={styles.button}
+            iconPosition="trailing"
+            label="Icon right"
+          />
         </View>
       </List.Section>
       <List.Section title="Contained-tonal button (tonal)">
@@ -45,194 +54,182 @@ const ButtonExample = () => {
             mode="contained-tonal"
             onPress={() => {}}
             style={styles.button}
-          >
-            Default
-          </Button>
+            label="Default"
+          />
           <Button
             mode="contained-tonal"
             buttonColor={color}
             onPress={() => {}}
             style={styles.button}
-          >
-            Custom
-          </Button>
+            label="Custom"
+          />
           <Button
             mode="contained-tonal"
             disabled
             onPress={() => {}}
             style={styles.button}
-          >
-            Disabled
-          </Button>
+            label="Disabled"
+          />
           <Button
             mode="contained-tonal"
             icon="camera"
             onPress={() => {}}
             style={styles.button}
-          >
-            Icon
-          </Button>
+            label="Icon"
+          />
           <Button
             mode="contained-tonal"
             loading
             onPress={() => {}}
             style={styles.button}
-          >
-            Loading
-          </Button>
+            label="Loading"
+          />
           <Button
             mode="contained-tonal"
             icon="camera"
             onPress={() => {}}
             style={styles.button}
-            contentStyle={styles.flexReverse}
-          >
-            Icon right
-          </Button>
+            iconPosition="trailing"
+            label="Icon right"
+          />
         </View>
       </List.Section>
       <List.Section title="Outlined button (outlined)">
         <View style={styles.row}>
-          <Button mode="outlined" onPress={() => {}} style={styles.button}>
-            Default
-          </Button>
+          <Button
+            mode="outlined"
+            onPress={() => {}}
+            style={styles.button}
+            label="Default"
+          />
           <Button
             mode="outlined"
             textColor={color}
             onPress={() => {}}
             style={styles.button}
-          >
-            Custom
-          </Button>
+            label="Custom"
+          />
           <Button
             mode="outlined"
             disabled
             onPress={() => {}}
             style={styles.button}
-          >
-            Disabled
-          </Button>
+            label="Disabled"
+          />
           <Button
             mode="outlined"
             icon="camera"
             onPress={() => {}}
             style={styles.button}
-          >
-            Icon
-          </Button>
+            label="Icon"
+          />
           <Button
             mode="outlined"
             loading
             onPress={() => {}}
             style={styles.button}
-          >
-            Loading
-          </Button>
+            label="Loading"
+          />
           <Button
             mode="outlined"
             icon="camera"
             onPress={() => {}}
             style={styles.button}
-            contentStyle={styles.flexReverse}
-          >
-            Icon right
-          </Button>
+            iconPosition="trailing"
+            label="Icon right"
+          />
         </View>
       </List.Section>
       <List.Section title="Contained button (filled)">
         <View style={styles.row}>
-          <Button mode="contained" onPress={() => {}} style={styles.button}>
-            Default
-          </Button>
+          <Button
+            mode="contained"
+            onPress={() => {}}
+            style={styles.button}
+            label="Default"
+          />
           <Button
             mode="contained"
             buttonColor={color}
             onPress={() => {}}
             style={styles.button}
-          >
-            Custom
-          </Button>
+            label="Custom"
+          />
           <Button
             mode="contained"
             disabled
             onPress={() => {}}
             style={styles.button}
-          >
-            Disabled
-          </Button>
+            label="Disabled"
+          />
           <Button
             mode="contained"
             icon="camera"
             onPress={() => {}}
             style={styles.button}
-          >
-            Icon
-          </Button>
+            label="Icon"
+          />
           <Button
             mode="contained"
             loading
             onPress={() => {}}
             style={styles.button}
-          >
-            Loading
-          </Button>
+            label="Loading"
+          />
           <Button
             mode="contained"
             icon="camera"
             onPress={() => {}}
             style={styles.button}
-            contentStyle={styles.flexReverse}
-          >
-            Icon right
-          </Button>
+            iconPosition="trailing"
+            label="Icon right"
+          />
         </View>
       </List.Section>
       <List.Section title="Elevated button (elevated)">
         <View style={styles.row}>
-          <Button mode="elevated" onPress={() => {}} style={styles.button}>
-            Default
-          </Button>
+          <Button
+            mode="elevated"
+            onPress={() => {}}
+            style={styles.button}
+            label="Default"
+          />
           <Button
             mode="elevated"
             buttonColor={color}
             onPress={() => {}}
             style={styles.button}
-          >
-            Custom
-          </Button>
+            label="Custom"
+          />
           <Button
             mode="elevated"
             disabled
             onPress={() => {}}
             style={styles.button}
-          >
-            Disabled
-          </Button>
+            label="Disabled"
+          />
           <Button
             mode="elevated"
             icon="camera"
             onPress={() => {}}
             style={styles.button}
-          >
-            Icon
-          </Button>
+            label="Icon"
+          />
           <Button
             mode="elevated"
             loading
             onPress={() => {}}
             style={styles.button}
-          >
-            Loading
-          </Button>
+            label="Loading"
+          />
           <Button
             mode="elevated"
             icon="camera"
             onPress={() => {}}
             style={styles.button}
-            contentStyle={styles.flexReverse}
-          >
-            Icon right
-          </Button>
+            iconPosition="trailing"
+            label="Icon right"
+          />
         </View>
       </List.Section>
       <List.Section title="Custom">
@@ -244,17 +241,15 @@ const ButtonExample = () => {
             }}
             onPress={() => {}}
             style={styles.button}
-          >
-            Remote image
-          </Button>
+            label="Remote image"
+          />
           <Button
             mode="outlined"
             icon={require('../../assets/images/favorite.png')}
             onPress={() => {}}
             style={styles.button}
-          >
-            Required asset
-          </Button>
+            label="Required asset"
+          />
           <Button
             mode="outlined"
             icon={({ size }) => (
@@ -266,39 +261,42 @@ const ButtonExample = () => {
             )}
             onPress={() => {}}
             style={styles.button}
-          >
-            Custom component
-          </Button>
+            label="Custom component"
+          />
           <Button
             icon="heart"
             mode="outlined"
             onPress={() => {}}
             style={styles.button}
             labelStyle={[styles.fontStyles, styles.md3FontStyles]}
-          >
-            Custom Font
-          </Button>
-          <Button mode="outlined" onPress={() => {}} style={styles.button}>
-            <Text variant="titleLarge">Custom text</Text>
-          </Button>
+            label="Custom Font"
+          />
+          <Button
+            mode="outlined"
+            onPress={() => {}}
+            style={styles.button}
+            labelStyle={theme.fonts.titleLarge}
+            label="Custom text"
+          />
           <Button
             mode="outlined"
             onPress={() => {}}
             style={styles.customRadius}
-          >
-            Custom radius
-          </Button>
-          <Button mode="contained" onPress={() => {}} style={styles.noRadius}>
-            Without radius
-          </Button>
+            label="Custom radius"
+          />
+          <Button
+            mode="contained"
+            onPress={() => {}}
+            style={styles.noRadius}
+            label="Without radius"
+          />
           <Button
             mode="contained-tonal"
             onPress={() => {}}
             style={{ borderRadius: styles.customRadiusAndPadding.borderRadius }}
             contentStyle={styles.customRadiusAndPadding}
-          >
-            Custom radius and padding
-          </Button>
+            label="Custom radius and padding"
+          />
         </View>
 
         <View style={styles.row}>
@@ -306,18 +304,16 @@ const ButtonExample = () => {
             mode="contained"
             onPress={() => {}}
             style={styles.flexGrow1Button}
-          >
-            flex-grow: 1
-          </Button>
+            label="flex-grow: 1"
+          />
         </View>
         <View style={styles.row}>
           <Button
             mode="contained"
             onPress={() => {}}
             style={styles.width100PercentButton}
-          >
-            width: 100%
-          </Button>
+            label="width: 100%"
+          />
         </View>
       </List.Section>
       <List.Section title="Compact">
@@ -339,9 +335,8 @@ const ButtonExample = () => {
                 onPress={() => {}}
                 style={styles.button}
                 icon="camera"
-              >
-                Compact {mode}
-              </Button>
+                label={`Compact ${mode}`}
+              />
             );
           })}
         </View>
@@ -363,9 +358,6 @@ const styles = StyleSheet.create({
   button: {
     margin: 4,
   },
-  flexReverse: {
-    flexDirection: 'row-reverse',
-  },
   md3FontStyles: {
     lineHeight: 32,
   },
diff --git a/example/src/Examples/CardExample.tsx b/example/src/Examples/CardExample.tsx
index ad3451e8b0..9a7973a8de 100644
--- a/example/src/Examples/CardExample.tsx
+++ b/example/src/Examples/CardExample.tsx
@@ -75,8 +75,8 @@ const CardExample = () => {
         <Card style={styles.card} mode={selectedMode}>
           <Card.Cover source={require('../../assets/images/forest.jpg')} />
           <Card.Actions>
-            <Button onPress={() => {}}>Share</Button>
-            <Button onPress={() => {}}>Explore</Button>
+            <Button onPress={() => {}} label="Share" />
+            <Button onPress={() => {}} label="Explore" />
           </Card.Actions>
         </Card>
         <Card style={styles.card} mode={selectedMode}>
@@ -104,12 +104,8 @@ const CardExample = () => {
           />
           <Card.Title title="Custom Button styles" />
           <Card.Actions>
-            <Button style={styles.button} onPress={() => {}}>
-              Share
-            </Button>
-            <Button style={styles.button} onPress={() => {}}>
-              Explore
-            </Button>
+            <Button style={styles.button} onPress={() => {}} label="Share" />
+            <Button style={styles.button} onPress={() => {}} label="Explore" />
           </Card.Actions>
         </Card>
         <Card
diff --git a/example/src/Examples/DialogExample.tsx b/example/src/Examples/DialogExample.tsx
index d926ae6616..33fb7fab59 100644
--- a/example/src/Examples/DialogExample.tsx
+++ b/example/src/Examples/DialogExample.tsx
@@ -32,52 +32,45 @@ const DialogExample = () => {
         mode="outlined"
         onPress={_toggleDialog('dialog1')}
         style={styles.button}
-      >
-        Long text
-      </Button>
+        label="Long text"
+      />
       <Button
         mode="outlined"
         onPress={_toggleDialog('dialog2')}
         style={styles.button}
-      >
-        Radio buttons
-      </Button>
+        label="Radio buttons"
+      />
       <Button
         mode="outlined"
         onPress={_toggleDialog('dialog3')}
         style={styles.button}
-      >
-        Progress indicator
-      </Button>
+        label="Progress indicator"
+      />
       <Button
         mode="outlined"
         onPress={_toggleDialog('dialog4')}
         style={styles.button}
-      >
-        Undismissable Dialog
-      </Button>
+        label="Undismissable Dialog"
+      />
       <Button
         mode="outlined"
         onPress={_toggleDialog('dialog5')}
         style={styles.button}
-      >
-        Custom colors
-      </Button>
+        label="Custom colors"
+      />
       <Button
         mode="outlined"
         onPress={_toggleDialog('dialog6')}
         style={styles.button}
-      >
-        With icon
-      </Button>
+        label="With icon"
+      />
       {Platform.OS === 'android' && (
         <Button
           mode="outlined"
           onPress={_toggleDialog('dialog7')}
           style={styles.button}
-        >
-          Dismissable back button
-        </Button>
+          label="Dismissable back button"
+        />
       )}
       <DialogWithLongText
         visible={_getVisible('dialog1')}
diff --git a/example/src/Examples/Dialogs/DialogWithCustomColors.tsx b/example/src/Examples/Dialogs/DialogWithCustomColors.tsx
index c811523b9e..fd2c1950a5 100644
--- a/example/src/Examples/Dialogs/DialogWithCustomColors.tsx
+++ b/example/src/Examples/Dialogs/DialogWithCustomColors.tsx
@@ -27,9 +27,7 @@ const DialogWithCustomColors = ({
           </TextComponent>
         </Dialog.Content>
         <Dialog.Actions>
-          <Button textColor={Palette.primary95} onPress={close}>
-            Ok
-          </Button>
+          <Button textColor={Palette.primary95} onPress={close} label="Ok" />
         </Dialog.Actions>
       </Dialog>
     </Portal>
diff --git a/example/src/Examples/Dialogs/DialogWithDismissableBackButton.tsx b/example/src/Examples/Dialogs/DialogWithDismissableBackButton.tsx
index 21f647e75c..aa0b93f4ea 100644
--- a/example/src/Examples/Dialogs/DialogWithDismissableBackButton.tsx
+++ b/example/src/Examples/Dialogs/DialogWithDismissableBackButton.tsx
@@ -26,10 +26,8 @@ const DialogWithDismissableBackButton = ({
         </TextComponent>
       </Dialog.Content>
       <Dialog.Actions>
-        <Button textColor={Palette.tertiary50} disabled>
-          Disagree
-        </Button>
-        <Button onPress={close}>Agree</Button>
+        <Button textColor={Palette.tertiary50} disabled label="Disagree" />
+        <Button onPress={close} label="Agree" />
       </Dialog.Actions>
     </Dialog>
   </Portal>
diff --git a/example/src/Examples/Dialogs/DialogWithIcon.tsx b/example/src/Examples/Dialogs/DialogWithIcon.tsx
index f12089193d..b4112642d7 100644
--- a/example/src/Examples/Dialogs/DialogWithIcon.tsx
+++ b/example/src/Examples/Dialogs/DialogWithIcon.tsx
@@ -24,10 +24,12 @@ const DialogWithIcon = ({
           </TextComponent>
         </Dialog.Content>
         <Dialog.Actions>
-          <Button onPress={close} textColor={Palette.error50}>
-            Disagree
-          </Button>
-          <Button onPress={close}>Agree</Button>
+          <Button
+            onPress={close}
+            textColor={Palette.error50}
+            label="Disagree"
+          />
+          <Button onPress={close} label="Agree" />
         </Dialog.Actions>
       </Dialog>
     </Portal>
diff --git a/example/src/Examples/Dialogs/DialogWithLongText.tsx b/example/src/Examples/Dialogs/DialogWithLongText.tsx
index 3f826c1b40..e92bbe3267 100644
--- a/example/src/Examples/Dialogs/DialogWithLongText.tsx
+++ b/example/src/Examples/Dialogs/DialogWithLongText.tsx
@@ -63,7 +63,7 @@ const DialogWithLongText = ({
         </ScrollView>
       </Dialog.ScrollArea>
       <Dialog.Actions>
-        <Button onPress={close}>Ok</Button>
+        <Button onPress={close} label="Ok" />
       </Dialog.Actions>
     </Dialog>
   </Portal>
diff --git a/example/src/Examples/Dialogs/DialogWithRadioBtns.tsx b/example/src/Examples/Dialogs/DialogWithRadioBtns.tsx
index 966422369e..07aca7ecf2 100644
--- a/example/src/Examples/Dialogs/DialogWithRadioBtns.tsx
+++ b/example/src/Examples/Dialogs/DialogWithRadioBtns.tsx
@@ -84,8 +84,8 @@ const DialogWithRadioBtns = ({ visible, close }: Props) => {
           </ScrollView>
         </Dialog.ScrollArea>
         <Dialog.Actions>
-          <Button onPress={close}>Cancel</Button>
-          <Button onPress={close}>Ok</Button>
+          <Button onPress={close} label="Cancel" />
+          <Button onPress={close} label="Ok" />
         </Dialog.Actions>
       </Dialog>
     </Portal>
diff --git a/example/src/Examples/Dialogs/UndismissableDialog.tsx b/example/src/Examples/Dialogs/UndismissableDialog.tsx
index 3a9fe10cb8..9a5ab75d9c 100644
--- a/example/src/Examples/Dialogs/UndismissableDialog.tsx
+++ b/example/src/Examples/Dialogs/UndismissableDialog.tsx
@@ -18,10 +18,8 @@ const UndismissableDialog = ({
         <TextComponent>This is an undismissable dialog!!</TextComponent>
       </Dialog.Content>
       <Dialog.Actions>
-        <Button textColor={Palette.tertiary50} disabled>
-          Disagree
-        </Button>
-        <Button onPress={close}>Agree</Button>
+        <Button textColor={Palette.tertiary50} disabled label="Disagree" />
+        <Button onPress={close} label="Agree" />
       </Dialog.Actions>
     </Dialog>
   </Portal>
diff --git a/example/src/Examples/MenuExample.tsx b/example/src/Examples/MenuExample.tsx
index a263b7ee39..4e720fcb6c 100644
--- a/example/src/Examples/MenuExample.tsx
+++ b/example/src/Examples/MenuExample.tsx
@@ -84,9 +84,11 @@ const MenuExample = ({ navigation }: Props) => {
               visible={_getVisible('menu2')}
               onDismiss={_toggleMenu('menu2')}
               anchor={
-                <Button mode="outlined" onPress={_toggleMenu('menu2')}>
-                  Menu with icons
-                </Button>
+                <Button
+                  mode="outlined"
+                  onPress={_toggleMenu('menu2')}
+                  label="Menu with icons"
+                />
               }
             >
               <Menu.Item leadingIcon="undo" onPress={() => {}} title="Undo" />
@@ -143,9 +145,11 @@ const MenuExample = ({ navigation }: Props) => {
             onDismiss={_toggleMenu('menu5')}
             anchorPosition="bottom"
             anchor={
-              <Button mode="outlined" onPress={_toggleMenu('menu5')}>
-                Menu with anchor position bottom
-              </Button>
+              <Button
+                mode="outlined"
+                onPress={_toggleMenu('menu5')}
+                label="Menu with anchor position bottom"
+              />
             }
           >
             <Menu.Item onPress={() => {}} title="Item 1" />
@@ -159,9 +163,11 @@ const MenuExample = ({ navigation }: Props) => {
             visible={_getVisible('menu4')}
             onDismiss={_toggleMenu('menu4')}
             anchor={
-              <Button mode="outlined" onPress={_toggleMenu('menu4')}>
-                Menu at bottom
-              </Button>
+              <Button
+                mode="outlined"
+                onPress={_toggleMenu('menu4')}
+                label="Menu at bottom"
+              />
             }
           >
             <Menu.Item onPress={() => {}} title="Bottom Item 1" />
diff --git a/example/src/Examples/ProgressBarExample.tsx b/example/src/Examples/ProgressBarExample.tsx
index 5b59566d6e..214f82b3ca 100644
--- a/example/src/Examples/ProgressBarExample.tsx
+++ b/example/src/Examples/ProgressBarExample.tsx
@@ -41,11 +41,12 @@ const ProgressBarExample = () => {
 
   return (
     <ScreenWrapper contentContainerStyle={styles.container}>
-      <Button onPress={() => setVisible(!visible)}>Toggle visibility</Button>
-      <Button onPress={() => setProgress(Math.random())}>
-        Random progress
-      </Button>
-      <Button onPress={runCustomAnimation}>Toggle animation</Button>
+      <Button onPress={() => setVisible(!visible)} label="Toggle visibility" />
+      <Button
+        onPress={() => setProgress(Math.random())}
+        label="Random progress"
+      />
+      <Button onPress={runCustomAnimation} label="Toggle animation" />
 
       <View style={styles.row}>
         <Text variant="bodyMedium">Default ProgressBar</Text>
diff --git a/example/src/Examples/SnackbarExample.tsx b/example/src/Examples/SnackbarExample.tsx
index e31955f18c..06e65ce077 100644
--- a/example/src/Examples/SnackbarExample.tsx
+++ b/example/src/Examples/SnackbarExample.tsx
@@ -90,9 +90,8 @@ const SnackbarExample = () => {
             onPress={() =>
               setOptions({ ...options, showSnackbar: !showSnackbar })
             }
-          >
-            {showSnackbar ? 'Hide' : 'Show'}
-          </Button>
+            label={showSnackbar ? 'Hide' : 'Show'}
+          />
         </View>
       </ScreenWrapper>
       <Snackbar
diff --git a/example/src/Examples/TeamDetails.tsx b/example/src/Examples/TeamDetails.tsx
index a4b1f41a0b..d151f836e6 100644
--- a/example/src/Examples/TeamDetails.tsx
+++ b/example/src/Examples/TeamDetails.tsx
@@ -107,8 +107,8 @@ const News = () => {
               </Text>
             </Card.Content>
             <Card.Actions>
-              <Button onPress={() => {}}>Share</Button>
-              <Button onPress={() => {}}>Read more</Button>
+              <Button onPress={() => {}} label="Share" />
+              <Button onPress={() => {}} label="Read more" />
             </Card.Actions>
           </Card>
           <Card style={styles.card} mode="contained">
@@ -124,8 +124,8 @@ const News = () => {
               </Text>
             </Card.Content>
             <Card.Actions>
-              <Button onPress={() => {}}>Share</Button>
-              <Button onPress={() => {}}>Read more</Button>
+              <Button onPress={() => {}} label="Share" />
+              <Button onPress={() => {}} label="Read more" />
             </Card.Actions>
           </Card>
         </View>

From 6309587567f597877d711b1ea1ce79273cb91189 Mon Sep 17 00:00:00 2001
From: Aziz Becha <aziz07becha@gmail.com>
Date: Tue, 12 May 2026 22:53:03 +0100
Subject: [PATCH 07/24] docs: update Button usage in guides to label prop

Update the hand-written guide snippets (icons, react-navigation, ripple
effect) and the docs-site example components to use the new `label` prop
instead of children. The generated component reference pages are derived
from the JSDoc and will be regenerated by the docs build.
---
 docs/docs/guides/03-icons.mdx             | 26 ++++++++++-------------
 docs/docs/guides/09-react-navigation.md   |  8 ++++---
 docs/docs/guides/11-ripple-effect.md      |  6 +++---
 docs/src/components/BannerExample.tsx     | 22 +++++++++++--------
 docs/src/components/GetStartedButtons.tsx | 14 ++++++------
 5 files changed, 40 insertions(+), 36 deletions(-)

diff --git a/docs/docs/guides/03-icons.mdx b/docs/docs/guides/03-icons.mdx
index c773ce7a56..350b90d59c 100644
--- a/docs/docs/guides/03-icons.mdx
+++ b/docs/docs/guides/03-icons.mdx
@@ -27,7 +27,7 @@ You can pass the name of an icon from [`MaterialDesignIcons`](https://pictogramm
 Example:
 
 ```js
-<Button icon="camera">Press me</Button>
+<Button icon="camera" label="Press me" />
 ```
 
 :::note
@@ -63,15 +63,14 @@ Remote image:
 ```js
 <Button
   icon={{ uri: 'https://avatars0.githubusercontent.com/u/17571969?v=3&s=400' }}
->
-  Press me
-</Button>
+  label="Press me"
+/>
 ```
 
 Local image:
 
 ```js
-<Button icon={require('../assets/chameleon.jpg')}>Press me</Button>
+<Button icon={require('../assets/chameleon.jpg')} label="Press me" />
 ```
 
 ### 3. A render function
@@ -88,9 +87,8 @@ Example:
       style={{ width: size, height: size, tintColor: color }}
     />
   )}
->
-  Press me
-</Button>
+  label="Press me"
+/>
 ```
 
 ### 4. Use custom icons
@@ -131,15 +129,14 @@ Example for using an image source:
     },
     direction: 'rtl',
   }}
->
-  Press me
-</Button>
+  label="Press me"
+/>
 ```
 
 Example for using an icon name:
 
 ```js
-<Button icon={{ source: 'add-a-photo', direction: 'rtl' }}>Press me</Button>
+<Button icon={{ source: 'add-a-photo', direction: 'rtl' }} label="Press me" />
 ```
 
 You can also use a render function. Along with `size` and `color`, you have access to `direction` which will either be `'rtl'` or `'ltr'`. You can then decide how to render your icon component accordingly.
@@ -163,7 +160,6 @@ Example of using a render function:
       ]}
     />
   )}
->
-  Press me
-</Button>
+  label="Press me"
+/>
 ```
diff --git a/docs/docs/guides/09-react-navigation.md b/docs/docs/guides/09-react-navigation.md
index 5ea5d556fa..c37bf2bad9 100644
--- a/docs/docs/guides/09-react-navigation.md
+++ b/docs/docs/guides/09-react-navigation.md
@@ -86,9 +86,11 @@ function HomeScreen({ navigation }) {
   return (
     <View style={style.container}>
       <Text>Home Screen</Text>
-      <Button mode="contained" onPress={() => navigation.navigate('Details')}>
-        Go to details
-      </Button>
+      <Button
+        mode="contained"
+        onPress={() => navigation.navigate('Details')}
+        label="Go to details"
+      />
     </View>
   );
 }
diff --git a/docs/docs/guides/11-ripple-effect.md b/docs/docs/guides/11-ripple-effect.md
index 31845060d7..fcdb1e70a4 100644
--- a/docs/docs/guides/11-ripple-effect.md
+++ b/docs/docs/guides/11-ripple-effect.md
@@ -19,9 +19,9 @@ The `rippleColor` prop is available for every pressable component which allows y
   rippleColor="#FF000020"
   icon="camera"
   mode="contained"
-  onPress={() => console.log('Pressed')}>
-  Press me
-</Button>
+  onPress={() => console.log('Pressed')}
+  label="Press me"
+/>
 ```
 
 ## Disable ripple effect in all components
diff --git a/docs/src/components/BannerExample.tsx b/docs/src/components/BannerExample.tsx
index 59ec60634a..0bae591bac 100644
--- a/docs/src/components/BannerExample.tsx
+++ b/docs/src/components/BannerExample.tsx
@@ -74,15 +74,19 @@ const BannerExample = () => {
     >
       <Stack spacing={16}>
         <Stack direction="row" spacing={8} style={styles.row}>
-          <Button loading onPress={() => {}}>
-            Loading
-          </Button>
-          <Button mode="contained-tonal" icon="camera" onPress={() => {}}>
-            Icon
-          </Button>
-          <Button icon="camera" mode="contained" onPress={() => {}}>
-            Press me
-          </Button>
+          <Button loading onPress={() => {}} label="Loading" />
+          <Button
+            mode="contained-tonal"
+            icon="camera"
+            onPress={() => {}}
+            label="Icon"
+          />
+          <Button
+            icon="camera"
+            mode="contained"
+            onPress={() => {}}
+            label="Press me"
+          />
           <FAB icon="plus" size="small" onPress={() => {}} />
           <FAB icon="plus" size="medium" onPress={() => {}} />
           <FAB icon="plus" size="large" onPress={() => {}} />
diff --git a/docs/src/components/GetStartedButtons.tsx b/docs/src/components/GetStartedButtons.tsx
index fd00420b46..906c51be13 100644
--- a/docs/src/components/GetStartedButtons.tsx
+++ b/docs/src/components/GetStartedButtons.tsx
@@ -36,9 +36,12 @@ const GetStartedButton = () => {
   return (
     <View style={styles.container}>
       <Link to="/docs/guides/getting-started" style={noTextDecoration}>
-        <Button mode="contained" style={styles.button} onPress={noop}>
-          Get started
-        </Button>
+        <Button
+          mode="contained"
+          style={styles.button}
+          onPress={noop}
+          label="Get started"
+        />
       </Link>
       <Button
         mode="outlined"
@@ -47,9 +50,8 @@ const GetStartedButton = () => {
             'https://snack.expo.dev/@react-native-paper/react-native-paper-example_v5'
           )
         }
-      >
-        Try on Snack
-      </Button>
+        label="Try on Snack"
+      />
     </View>
   );
 };

From 1269af3c1e23548915adaa2b8a79b8f135c0727e Mon Sep 17 00:00:00 2001
From: Aziz Becha <aziz07becha@gmail.com>
Date: Wed, 13 May 2026 13:59:26 +0100
Subject: [PATCH 08/24] feat: add Button size prop (MD3 expressive)

Add a `size?: 'extra-small' | 'small' | 'medium' | 'large' | 'extra-large'`
prop. When omitted, the Button keeps its current visuals; when set, the
per-size MD3 metrics (minHeight, horizontal padding, icon size,
icon/label gap, label typescale) are applied via a new
`getButtonSizeStyle` helper.
---
 src/components/Button/Button.tsx              |  67 ++++--
 src/components/Button/utils.tsx               |  67 ++++++
 src/components/__tests__/Button.test.tsx      |  56 ++++-
 .../__snapshots__/Button.test.tsx.snap        | 192 ++++++++++++++++++
 4 files changed, 366 insertions(+), 16 deletions(-)

diff --git a/src/components/Button/Button.tsx b/src/components/Button/Button.tsx
index fc71192a2d..075afc2b63 100644
--- a/src/components/Button/Button.tsx
+++ b/src/components/Button/Button.tsx
@@ -15,9 +15,11 @@ import {
 
 import {
   ButtonMode,
+  ButtonSize,
   getButtonColors,
   getButtonIconStyle,
   getButtonRippleColor,
+  getButtonSizeStyle,
   getButtonTouchableRippleStyle,
 } from './utils';
 import { useInternalTheme } from '../../core/theming';
@@ -56,6 +58,15 @@ export type Props = $Omit<
    * Use a compact look, useful for `text` buttons in a row.
    */
   compact?: boolean;
+  /**
+   * Size of the button (Material Design 3 expressive). One of
+   * `'extra-small' | 'small' | 'medium' | 'large' | 'extra-large'`.
+   *
+   * When omitted, the button uses its legacy visuals. When set, the size
+   * controls the minimum height, horizontal padding, icon size, the gap
+   * between icon and label, and the label typescale.
+   */
+  size?: ButtonSize;
   /**
    * Custom button's background color.
    */
@@ -202,6 +213,7 @@ const Button = (
     disabled,
     compact,
     mode = 'text',
+    size,
     dark,
     loading,
     icon,
@@ -388,22 +400,29 @@ const Button = (
     [labelStyle]
   );
 
+  const sizeStyle = React.useMemo(
+    () => (size ? getButtonSizeStyle(size) : undefined),
+    [size]
+  );
+
   const textStyle = React.useMemo(
     () => ({
       color: textColor,
-      ...(theme as Theme).fonts.labelLarge,
+      ...(theme as Theme).fonts[sizeStyle?.labelVariant ?? 'labelLarge'],
     }),
-    [textColor, theme]
+    [textColor, theme, sizeStyle]
   );
 
   const iconStyle = React.useMemo(
     () =>
-      getButtonIconStyle({
-        mode,
-        compact,
-        position: isTrailingIcon ? 'trailing' : 'leading',
-      }),
-    [mode, compact, isTrailingIcon]
+      sizeStyle
+        ? null
+        : getButtonIconStyle({
+            mode,
+            compact,
+            position: isTrailingIcon ? 'trailing' : 'leading',
+          }),
+    [mode, compact, isTrailingIcon, sizeStyle]
   );
 
   return (
@@ -460,15 +479,27 @@ const Button = (
           style={[
             styles.content,
             isTrailingIcon && styles.contentReverse,
+            ...(sizeStyle
+              ? [
+                  {
+                    minHeight: sizeStyle.minHeight,
+                    paddingHorizontal: sizeStyle.paddingHorizontal,
+                    gap: sizeStyle.iconGap,
+                  },
+                ]
+              : []),
             { opacity: textOpacity },
             contentStyle,
           ]}
         >
           {icon && loading !== true ? (
-            <View style={iconStyle} testID={`${testID}-icon-container`}>
+            <View
+              style={iconStyle ?? undefined}
+              testID={`${testID}-icon-container`}
+            >
               <Icon
                 source={icon}
-                size={customLabelSize ?? iconSize}
+                size={sizeStyle?.iconSize ?? customLabelSize ?? iconSize}
                 color={
                   typeof customLabelColor === 'string'
                     ? customLabelColor
@@ -479,28 +510,30 @@ const Button = (
           ) : null}
           {loading ? (
             <ActivityIndicator
-              size={customLabelSize ?? iconSize}
+              size={sizeStyle?.iconSize ?? customLabelSize ?? iconSize}
               color={
                 typeof customLabelColor === 'string'
                   ? customLabelColor
                   : textColor
               }
-              style={iconStyle}
+              style={iconStyle ?? undefined}
             />
           ) : null}
           <Text
-            variant="labelLarge"
+            variant={sizeStyle?.labelVariant ?? 'labelLarge'}
             selectable={false}
             numberOfLines={1}
             testID={`${testID}-text`}
             style={[
               styles.label,
-              isMode('text')
+              sizeStyle
+                ? styles.sizedLabel
+                : isMode('text')
                 ? icon || loading
                   ? styles.md3LabelTextAddons
                   : styles.md3LabelText
                 : styles.md3Label,
-              compact && styles.compactLabel,
+              !sizeStyle && compact && styles.compactLabel,
               uppercase && styles.uppercaseLabel,
               textStyle,
               labelStyle,
@@ -536,6 +569,10 @@ const styles = StyleSheet.create({
     marginVertical: 9,
     marginHorizontal: 16,
   },
+  sizedLabel: {
+    marginVertical: 0,
+    marginHorizontal: 0,
+  },
   compactLabel: {
     marginHorizontal: 8,
   },
diff --git a/src/components/Button/utils.tsx b/src/components/Button/utils.tsx
index cf41e4b9e6..8710fe2371 100644
--- a/src/components/Button/utils.tsx
+++ b/src/components/Button/utils.tsx
@@ -18,6 +18,73 @@ export type ButtonMode =
 
 export type ButtonIconPosition = 'leading' | 'trailing';
 
+export type ButtonSize =
+  | 'extra-small'
+  | 'small'
+  | 'medium'
+  | 'large'
+  | 'extra-large';
+
+export type ButtonLabelVariant =
+  | 'labelLarge'
+  | 'titleMedium'
+  | 'headlineSmall'
+  | 'headlineLarge';
+
+export type ButtonSizeStyle = {
+  minHeight: number;
+  paddingHorizontal: number;
+  iconSize: number;
+  iconGap: number;
+  labelVariant: ButtonLabelVariant;
+};
+
+/**
+ * Per-size metrics for the Material Design 3 (expressive) button sizes.
+ * Used when the `size` prop is explicitly set; if `size` is omitted, the
+ * Button keeps its legacy visuals.
+ */
+const BUTTON_SIZE_STYLES: Record<ButtonSize, ButtonSizeStyle> = {
+  'extra-small': {
+    minHeight: 32,
+    paddingHorizontal: 12,
+    iconSize: 16,
+    iconGap: 4,
+    labelVariant: 'labelLarge',
+  },
+  small: {
+    minHeight: 40,
+    paddingHorizontal: 16,
+    iconSize: 20,
+    iconGap: 8,
+    labelVariant: 'labelLarge',
+  },
+  medium: {
+    minHeight: 56,
+    paddingHorizontal: 24,
+    iconSize: 24,
+    iconGap: 8,
+    labelVariant: 'titleMedium',
+  },
+  large: {
+    minHeight: 96,
+    paddingHorizontal: 48,
+    iconSize: 32,
+    iconGap: 12,
+    labelVariant: 'headlineSmall',
+  },
+  'extra-large': {
+    minHeight: 136,
+    paddingHorizontal: 64,
+    iconSize: 40,
+    iconGap: 16,
+    labelVariant: 'headlineLarge',
+  },
+};
+
+export const getButtonSizeStyle = (size: ButtonSize): ButtonSizeStyle =>
+  BUTTON_SIZE_STYLES[size];
+
 /**
  * Returns the margins applied to the button's icon (or loading indicator)
  * depending on the button mode, density and the position of the icon relative
diff --git a/src/components/__tests__/Button.test.tsx b/src/components/__tests__/Button.test.tsx
index 94cf3ab0db..df026b86b3 100644
--- a/src/components/__tests__/Button.test.tsx
+++ b/src/components/__tests__/Button.test.tsx
@@ -9,7 +9,11 @@ import { render } from '../../test-utils';
 import { pink500, white } from '../../theme/colors';
 import { tokens } from '../../theme/tokens';
 import Button from '../Button/Button';
-import { getButtonColors, getButtonRippleColor } from '../Button/utils';
+import {
+  getButtonColors,
+  getButtonRippleColor,
+  getButtonSizeStyle,
+} from '../Button/utils';
 
 const { stateOpacity } = tokens.md.ref;
 
@@ -825,6 +829,56 @@ describe('getButtonRippleColor', () => {
   });
 });
 
+describe('getButtonSizeStyle', () => {
+  it.each([
+    ['extra-small', 32, 12, 16, 4, 'labelLarge'],
+    ['small', 40, 16, 20, 8, 'labelLarge'],
+    ['medium', 56, 24, 24, 8, 'titleMedium'],
+    ['large', 96, 48, 32, 12, 'headlineSmall'],
+    ['extra-large', 136, 64, 40, 16, 'headlineLarge'],
+  ] as const)(
+    'returns expected metrics for %s',
+    (size, minHeight, paddingHorizontal, iconSize, iconGap, labelVariant) => {
+      expect(getButtonSizeStyle(size)).toEqual({
+        minHeight,
+        paddingHorizontal,
+        iconSize,
+        iconGap,
+        labelVariant,
+      });
+    }
+  );
+});
+
+describe('size prop', () => {
+  it('renders a button with per-size metrics', () => {
+    const tree = render(
+      <Button size="medium" icon="camera" label="Medium" />
+    ).toJSON();
+
+    expect(tree).toMatchSnapshot();
+  });
+
+  (
+    [
+      ['extra-small', 14],
+      ['small', 14],
+      ['medium', 16],
+      ['large', 24],
+      ['extra-large', 32],
+    ] as const
+  ).forEach(([size, expectedFontSize]) =>
+    it(`applies the ${size} typescale to the label`, () => {
+      const { getByTestId } = render(
+        <Button size={size} testID="button" label="X" />
+      );
+      expect(getByTestId('button-text')).toHaveStyle({
+        fontSize: expectedFontSize,
+      });
+    })
+  );
+});
+
 it('animated value changes correctly', () => {
   const value = new Animated.Value(1);
   const { getByTestId } = render(
diff --git a/src/components/__tests__/__snapshots__/Button.test.tsx.snap b/src/components/__tests__/__snapshots__/Button.test.tsx.snap
index 069451e1a4..75e53412a5 100644
--- a/src/components/__tests__/__snapshots__/Button.test.tsx.snap
+++ b/src/components/__tests__/__snapshots__/Button.test.tsx.snap
@@ -2272,3 +2272,195 @@ exports[`renders text button with mode 1`] = `
   </View>
 </View>
 `;
+
+exports[`size prop renders a button with per-size metrics 1`] = `
+<View
+  collapsable={false}
+  style={
+    {
+      "backgroundColor": "transparent",
+      "borderRadius": 20,
+      "shadowColor": "rgba(0, 0, 0, 1)",
+      "shadowOffset": {
+        "height": 0,
+        "width": 0,
+      },
+      "shadowOpacity": 0,
+      "shadowRadius": 0,
+    }
+  }
+  testID="button-container-outer-layer"
+>
+  <View
+    collapsable={false}
+    style={
+      {
+        "backgroundColor": "transparent",
+        "borderColor": "transparent",
+        "borderRadius": 20,
+        "borderStyle": "solid",
+        "borderWidth": 0,
+        "flex": undefined,
+        "minWidth": 64,
+        "shadowColor": "rgba(0, 0, 0, 1)",
+        "shadowOffset": {
+          "height": 0,
+          "width": 0,
+        },
+        "shadowOpacity": 0,
+        "shadowRadius": 0,
+      }
+    }
+    testID="button-container"
+  >
+    <View
+      accessibilityRole="button"
+      accessibilityState={
+        {
+          "busy": undefined,
+          "checked": undefined,
+          "disabled": true,
+          "expanded": undefined,
+          "selected": undefined,
+        }
+      }
+      accessibilityValue={
+        {
+          "max": undefined,
+          "min": undefined,
+          "now": undefined,
+          "text": undefined,
+        }
+      }
+      accessible={true}
+      collapsable={false}
+      focusable={true}
+      onBlur={[Function]}
+      onClick={[Function]}
+      onFocus={[Function]}
+      onResponderGrant={[Function]}
+      onResponderMove={[Function]}
+      onResponderRelease={[Function]}
+      onResponderTerminate={[Function]}
+      onResponderTerminationRequest={[Function]}
+      onStartShouldSetResponder={[Function]}
+      style={
+        [
+          {
+            "overflow": "hidden",
+          },
+          {
+            "borderRadius": 20,
+          },
+        ]
+      }
+      testID="button"
+    >
+      <View
+        style={
+          [
+            {
+              "alignItems": "center",
+              "flexDirection": "row",
+              "justifyContent": "center",
+            },
+            false,
+            {
+              "gap": 8,
+              "minHeight": 56,
+              "paddingHorizontal": 24,
+            },
+            {
+              "opacity": 1,
+            },
+            undefined,
+          ]
+        }
+      >
+        <View
+          testID="button-icon-container"
+        >
+          <Text
+            accessibilityElementsHidden={true}
+            importantForAccessibility="no-hide-descendants"
+            pointerEvents="none"
+            selectable={false}
+            style={
+              [
+                {
+                  "color": "rgba(103, 80, 164, 1)",
+                  "fontSize": 24,
+                },
+                [
+                  {
+                    "lineHeight": 24,
+                    "transform": [
+                      {
+                        "scaleX": 1,
+                      },
+                    ],
+                  },
+                  {
+                    "backgroundColor": "transparent",
+                  },
+                ],
+              ]
+            }
+          >
+            camera
+          </Text>
+        </View>
+        <Text
+          numberOfLines={1}
+          selectable={false}
+          style={
+            [
+              {
+                "textAlign": "left",
+              },
+              {
+                "color": "rgba(29, 27, 32, 1)",
+                "writingDirection": "ltr",
+              },
+              [
+                {
+                  "fontFamily": "System",
+                  "fontSize": 16,
+                  "fontWeight": "500",
+                  "letterSpacing": 0.15,
+                  "lineHeight": 24,
+                },
+                [
+                  {
+                    "marginHorizontal": 16,
+                    "marginVertical": 9,
+                    "textAlign": "center",
+                  },
+                  {
+                    "marginHorizontal": 0,
+                    "marginVertical": 0,
+                  },
+                  false,
+                  false,
+                  {
+                    "color": "rgba(103, 80, 164, 1)",
+                    "fontFamily": "System",
+                    "fontSize": 16,
+                    "fontWeight": "500",
+                    "letterSpacing": 0.15,
+                    "lineHeight": 24,
+                  },
+                  undefined,
+                ],
+              ],
+            ]
+          }
+          testID="button-text"
+        >
+          Medium
+        </Text>
+      </View>
+    </View>
+  </View>
+</View>
+`;

From c19dd55ce8ae5a5f09a2211bdfdb9877751c8051 Mon Sep 17 00:00:00 2001
From: Aziz Becha <aziz07becha@gmail.com>
Date: Wed, 13 May 2026 14:04:14 +0100
Subject: [PATCH 09/24] feat: add Button shape prop (MD3 expressive)

Add a `shape?: 'round' | 'square'` prop. When omitted, the button keeps
its legacy corner radius. When set, `'round'` uses the full-pill radius
and `'square'` uses a per-size smaller corner; the mapping comes from a
new `getButtonShapeRadius` helper. An explicit `borderRadius` in `style`
still wins.
---
 src/components/Button/Button.tsx         | 15 ++++++-
 src/components/Button/utils.tsx          | 30 +++++++++++++
 src/components/__tests__/Button.test.tsx | 57 ++++++++++++++++++++++++
 3 files changed, 101 insertions(+), 1 deletion(-)

diff --git a/src/components/Button/Button.tsx b/src/components/Button/Button.tsx
index 075afc2b63..081dd54914 100644
--- a/src/components/Button/Button.tsx
+++ b/src/components/Button/Button.tsx
@@ -15,10 +15,12 @@ import {
 
 import {
   ButtonMode,
+  ButtonShape,
   ButtonSize,
   getButtonColors,
   getButtonIconStyle,
   getButtonRippleColor,
+  getButtonShapeRadius,
   getButtonSizeStyle,
   getButtonTouchableRippleStyle,
 } from './utils';
@@ -67,6 +69,14 @@ export type Props = $Omit<
    * between icon and label, and the label typescale.
    */
   size?: ButtonSize;
+  /**
+   * Shape variant of the button (Material Design 3 expressive). `'round'`
+   * uses the full-pill corner radius; `'square'` uses a smaller per-size
+   * corner radius. When omitted, the button keeps its legacy corner radius
+   * (`theme.shapes.corner.largeIncreased`). Overridden by an explicit
+   * `borderRadius` in `style`.
+   */
+  shape?: ButtonShape;
   /**
    * Custom button's background color.
    */
@@ -214,6 +224,7 @@ const Button = (
     compact,
     mode = 'text',
     size,
+    shape,
     dark,
     loading,
     icon,
@@ -339,7 +350,9 @@ const Button = (
     return radiusStyles;
   }, [style]);
 
-  const borderRadius = theme.shapes.corner.largeIncreased;
+  const borderRadius = shape
+    ? getButtonShapeRadius({ size, shape })
+    : theme.shapes.corner.largeIncreased;
 
   const {
     backgroundColor,
diff --git a/src/components/Button/utils.tsx b/src/components/Button/utils.tsx
index 8710fe2371..12fa763aad 100644
--- a/src/components/Button/utils.tsx
+++ b/src/components/Button/utils.tsx
@@ -4,6 +4,7 @@ import color from 'color';
 
 import { black, white } from '../../theme/colors';
 import { tokens } from '../../theme/tokens';
+import { cornerFull } from '../../theme/tokens/sys/shape';
 import type { InternalTheme, Theme } from '../../types';
 import { splitStyles } from '../../utils/splitStyles';
 
@@ -85,6 +86,35 @@ const BUTTON_SIZE_STYLES: Record<ButtonSize, ButtonSizeStyle> = {
 export const getButtonSizeStyle = (size: ButtonSize): ButtonSizeStyle =>
   BUTTON_SIZE_STYLES[size];
 
+export type ButtonShape = 'round' | 'square';
+
+/**
+ * Per-size corner radii for the Material Design 3 expressive shape variants.
+ * `round` is always the full-pill radius; `square` uses a per-size smaller
+ * corner. Used only when the `shape` prop is set on `Button`.
+ */
+const BUTTON_SHAPE_RADIUS: Record<ButtonSize, Record<ButtonShape, number>> = {
+  'extra-small': { round: cornerFull, square: 12 },
+  small: { round: cornerFull, square: 12 },
+  medium: { round: cornerFull, square: 16 },
+  large: { round: cornerFull, square: 28 },
+  'extra-large': { round: cornerFull, square: 28 },
+};
+
+const DEFAULT_SHAPE_RADIUS: Record<ButtonShape, number> = {
+  round: cornerFull,
+  square: 12,
+};
+
+export const getButtonShapeRadius = ({
+  size,
+  shape,
+}: {
+  size?: ButtonSize;
+  shape: ButtonShape;
+}): number =>
+  size ? BUTTON_SHAPE_RADIUS[size][shape] : DEFAULT_SHAPE_RADIUS[shape];
+
 /**
  * Returns the margins applied to the button's icon (or loading indicator)
  * depending on the button mode, density and the position of the icon relative
diff --git a/src/components/__tests__/Button.test.tsx b/src/components/__tests__/Button.test.tsx
index df026b86b3..c1aad1bf2f 100644
--- a/src/components/__tests__/Button.test.tsx
+++ b/src/components/__tests__/Button.test.tsx
@@ -12,6 +12,7 @@ import Button from '../Button/Button';
 import {
   getButtonColors,
   getButtonRippleColor,
+  getButtonShapeRadius,
   getButtonSizeStyle,
 } from '../Button/utils';
 
@@ -30,6 +31,9 @@ const styles = StyleSheet.create({
   noRadius: {
     borderRadius: 0,
   },
+  overrideRadius: {
+    borderRadius: 4,
+  },
 });
 
 it('renders text button by default', () => {
@@ -879,6 +883,59 @@ describe('size prop', () => {
   );
 });
 
+describe('getButtonShapeRadius', () => {
+  it.each([
+    ['extra-small', 9999, 12],
+    ['small', 9999, 12],
+    ['medium', 9999, 16],
+    ['large', 9999, 28],
+    ['extra-large', 9999, 28],
+  ] as const)('returns expected radii for size=%s', (size, round, square) => {
+    expect(getButtonShapeRadius({ size, shape: 'round' })).toBe(round);
+    expect(getButtonShapeRadius({ size, shape: 'square' })).toBe(square);
+  });
+
+  it('falls back to default radii when size is omitted', () => {
+    expect(getButtonShapeRadius({ shape: 'round' })).toBe(9999);
+    expect(getButtonShapeRadius({ shape: 'square' })).toBe(12);
+  });
+});
+
+describe('shape prop', () => {
+  it('applies the round (full-pill) radius', () => {
+    const { getByTestId } = render(
+      <Button testID="button" shape="round" label="X" />
+    );
+    expect(getByTestId('button-container')).toHaveStyle({ borderRadius: 9999 });
+  });
+
+  it('applies the square radius (default size)', () => {
+    const { getByTestId } = render(
+      <Button testID="button" shape="square" label="X" />
+    );
+    expect(getByTestId('button-container')).toHaveStyle({ borderRadius: 12 });
+  });
+
+  it('uses the per-size square radius when both size and shape are set', () => {
+    const { getByTestId } = render(
+      <Button testID="button" size="large" shape="square" label="X" />
+    );
+    expect(getByTestId('button-container')).toHaveStyle({ borderRadius: 28 });
+  });
+
+  it('lets an explicit borderRadius in `style` override the shape', () => {
+    const { getByTestId } = render(
+      <Button
+        testID="button"
+        shape="round"
+        style={styles.overrideRadius}
+        label="X"
+      />
+    );
+    expect(getByTestId('button-container')).toHaveStyle({ borderRadius: 4 });
+  });
+});
+
 it('animated value changes correctly', () => {
   const value = new Animated.Value(1);
   const { getByTestId } = render(

From 2fdf0cc8c50fdfa09b9f366b4a51cfbbf2c9cc07 Mon Sep 17 00:00:00 2001
From: Aziz Becha <aziz07becha@gmail.com>
Date: Wed, 13 May 2026 15:40:14 +0100
Subject: [PATCH 10/24] feat: add Button selected toggle state (MD3 expressive)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Add a `selected?: boolean` prop. When `true`, the button flips its
`shape` (round ↔ square) so the selected/unselected pair contrasts, and
for `outlined`/`text` modes adopts a filled tonal-selected appearance
(`secondaryContainer` background, `onSecondaryContainer` label, no
border). `accessibilityState.selected` is set so screen readers announce
the toggle state. Other modes keep their colors and only flip the shape.

The `selected` flag is threaded through `getButtonColors` and its
sub-helpers.
---
 src/components/Button/Button.tsx         | 32 +++++++++--
 src/components/Button/utils.tsx          | 37 +++++++++++--
 src/components/__tests__/Button.test.tsx | 69 ++++++++++++++++++++++++
 3 files changed, 130 insertions(+), 8 deletions(-)

diff --git a/src/components/Button/Button.tsx b/src/components/Button/Button.tsx
index 081dd54914..600d07342a 100644
--- a/src/components/Button/Button.tsx
+++ b/src/components/Button/Button.tsx
@@ -77,6 +77,19 @@ export type Props = $Omit<
    * `borderRadius` in `style`.
    */
   shape?: ButtonShape;
+  /**
+   * Whether this button is in the selected state (Material Design 3
+   * expressive toggle). When `true`:
+   *
+   * - The `shape` is flipped: `'round'` becomes `'square'` and vice versa.
+   * - For `outlined` and `text` modes, the button adopts a filled
+   *   `secondaryContainer` appearance (matches `contained-tonal`).
+   * - `accessibilityState.selected` is set so screen readers announce the
+   *   toggle state.
+   *
+   * Other modes only flip the shape.
+   */
+  selected?: boolean;
   /**
    * Custom button's background color.
    */
@@ -225,6 +238,7 @@ const Button = (
     mode = 'text',
     size,
     shape,
+    selected,
     dark,
     loading,
     icon,
@@ -350,8 +364,17 @@ const Button = (
     return radiusStyles;
   }, [style]);
 
-  const borderRadius = shape
-    ? getButtonShapeRadius({ size, shape })
+  // When the button is `selected`, flip the requested shape so the
+  // unselected/selected pair contrasts visually (round ↔ square).
+  const effectiveShape: ButtonShape | undefined = shape
+    ? selected
+      ? shape === 'round'
+        ? 'square'
+        : 'round'
+      : shape
+    : undefined;
+  const borderRadius = effectiveShape
+    ? getButtonShapeRadius({ size, shape: effectiveShape })
     : theme.shapes.corner.largeIncreased;
 
   const {
@@ -370,8 +393,9 @@ const Button = (
         mode,
         disabled,
         dark,
+        selected,
       }),
-    [customButtonColor, customTextColor, theme, mode, disabled, dark]
+    [customButtonColor, customTextColor, theme, mode, disabled, dark, selected]
   );
 
   const rippleColor = React.useMemo(
@@ -479,7 +503,7 @@ const Button = (
         accessibilityLabel={accessibilityLabel}
         accessibilityHint={accessibilityHint}
         accessibilityRole={accessibilityRole}
-        accessibilityState={{ disabled }}
+        accessibilityState={{ disabled, selected }}
         accessible={accessible}
         hitSlop={hitSlop}
         disabled={disabled}
diff --git a/src/components/Button/utils.tsx b/src/components/Button/utils.tsx
index 12fa763aad..c252537573 100644
--- a/src/components/Button/utils.tsx
+++ b/src/components/Button/utils.tsx
@@ -152,6 +152,7 @@ type BaseProps = {
   isMode: (mode: ButtonMode) => boolean;
   theme: InternalTheme;
   disabled?: boolean;
+  selected?: boolean;
 };
 
 const isDark = ({
@@ -177,6 +178,7 @@ const getButtonBackgroundColor = ({
   theme,
   disabled,
   customButtonColor,
+  selected,
 }: BaseProps & {
   customButtonColor?: ColorValue;
 }) => {
@@ -192,6 +194,12 @@ const getButtonBackgroundColor = ({
     return colors.onSurface;
   }
 
+  // Selected toggle (only outlined/text adopt a filled "tonal-selected" look;
+  // contained / contained-tonal / elevated already render filled).
+  if (selected && (isMode('outlined') || isMode('text'))) {
+    return colors.secondaryContainer;
+  }
+
   if (isMode('elevated')) {
     return colors.surfaceContainerLow;
   }
@@ -214,6 +222,7 @@ const getButtonTextColor = ({
   customTextColor,
   backgroundColor,
   dark,
+  selected,
 }: BaseProps & {
   customTextColor?: ColorValue;
   backgroundColor: ColorValue;
@@ -228,6 +237,11 @@ const getButtonTextColor = ({
     return theme.colors.onSurface;
   }
 
+  // Selected toggle for outlined/text mirrors the contained-tonal label color.
+  if (selected && (isMode('outlined') || isMode('text'))) {
+    return colors.onSecondaryContainer;
+  }
+
   if (typeof dark === 'boolean') {
     if (
       isMode('contained') ||
@@ -253,7 +267,12 @@ const getButtonTextColor = ({
   return colors.primary;
 };
 
-const getButtonBorderColor = ({ isMode, theme }: BaseProps) => {
+const getButtonBorderColor = ({ isMode, theme, selected }: BaseProps) => {
+  // A selected outlined toggle drops its outline (the filled background takes
+  // over as the visual affordance).
+  if (selected && isMode('outlined')) {
+    return 'transparent';
+  }
   if (isMode('outlined')) {
     return theme.colors.outlineVariant;
   }
@@ -261,7 +280,13 @@ const getButtonBorderColor = ({ isMode, theme }: BaseProps) => {
   return 'transparent';
 };
 
-const getButtonBorderWidth = ({ isMode }: Omit<BaseProps, 'disabled'>) => {
+const getButtonBorderWidth = ({
+  isMode,
+  selected,
+}: Omit<BaseProps, 'disabled' | 'theme'>) => {
+  if (selected && isMode('outlined')) {
+    return 0;
+  }
   if (isMode('outlined')) {
     return 1;
   }
@@ -276,6 +301,7 @@ export const getButtonColors = ({
   customTextColor,
   disabled,
   dark,
+  selected,
 }: {
   theme: InternalTheme;
   mode: ButtonMode;
@@ -283,6 +309,7 @@ export const getButtonColors = ({
   customTextColor?: ColorValue;
   disabled?: boolean;
   dark?: boolean;
+  selected?: boolean;
 }) => {
   const isMode = (modeToCompare: ButtonMode) => {
     return mode === modeToCompare;
@@ -293,6 +320,7 @@ export const getButtonColors = ({
     theme,
     disabled,
     customButtonColor,
+    selected,
   });
 
   const textColor = getButtonTextColor({
@@ -302,11 +330,12 @@ export const getButtonColors = ({
     customTextColor,
     backgroundColor,
     dark,
+    selected,
   });
 
-  const borderColor = getButtonBorderColor({ isMode, theme });
+  const borderColor = getButtonBorderColor({ isMode, theme, selected });
 
-  const borderWidth = getButtonBorderWidth({ isMode, theme });
+  const borderWidth = getButtonBorderWidth({ isMode, selected });
 
   const textOpacity = disabled ? stateOpacity.disabled : stateOpacity.enabled;
 
diff --git a/src/components/__tests__/Button.test.tsx b/src/components/__tests__/Button.test.tsx
index c1aad1bf2f..17c4fca13c 100644
--- a/src/components/__tests__/Button.test.tsx
+++ b/src/components/__tests__/Button.test.tsx
@@ -936,6 +936,75 @@ describe('shape prop', () => {
   });
 });
 
+describe('selected prop', () => {
+  it('sets accessibilityState.selected', () => {
+    const { getByTestId } = render(
+      <Button testID="button" selected onPress={() => {}} label="X" />
+    );
+
+    expect(getByTestId('button').props.accessibilityState).toMatchObject({
+      selected: true,
+    });
+  });
+
+  it('flips a round button into the square radius when selected', () => {
+    const { getByTestId } = render(
+      <Button testID="button" size="large" shape="round" selected label="X" />
+    );
+
+    expect(getByTestId('button-container')).toHaveStyle({ borderRadius: 28 });
+  });
+
+  it('flips a square button into the round radius when selected', () => {
+    const { getByTestId } = render(
+      <Button testID="button" shape="square" selected label="X" />
+    );
+
+    expect(getByTestId('button-container')).toHaveStyle({ borderRadius: 9999 });
+  });
+
+  it('gives an outlined button the tonal-selected appearance', () => {
+    expect(
+      getButtonColors({
+        theme: getTheme(),
+        mode: 'outlined',
+        selected: true,
+      })
+    ).toMatchObject({
+      backgroundColor: getTheme().colors.secondaryContainer,
+      textColor: getTheme().colors.onSecondaryContainer,
+      borderColor: 'transparent',
+      borderWidth: 0,
+    });
+  });
+
+  it('gives a text-mode button the tonal-selected appearance', () => {
+    expect(
+      getButtonColors({
+        theme: getTheme(),
+        mode: 'text',
+        selected: true,
+      })
+    ).toMatchObject({
+      backgroundColor: getTheme().colors.secondaryContainer,
+      textColor: getTheme().colors.onSecondaryContainer,
+    });
+  });
+
+  it('does not change contained colors when selected', () => {
+    expect(
+      getButtonColors({
+        theme: getTheme(),
+        mode: 'contained',
+        selected: true,
+      })
+    ).toMatchObject({
+      backgroundColor: getTheme().colors.primary,
+      textColor: getTheme().colors.onPrimary,
+    });
+  });
+});
+
 it('animated value changes correctly', () => {
   const value = new Animated.Value(1);
   const { getByTestId } = render(

From d339f8f2eb673976777c2f9be7ee1da264c560f1 Mon Sep 17 00:00:00 2001
From: Aziz Becha <aziz07becha@gmail.com>
Date: Wed, 13 May 2026 15:44:47 +0100
Subject: [PATCH 11/24] chore(example): add ButtonExample sections for size,
 shape and toggle

Showcase the new expressive props in the example app: one button per
size in the Size section, a round and a square row across sizes in the
Shape section, and stateful selected/unselected toggles in the Toggle
section.
---
 example/src/Examples/ButtonExample.tsx | 77 ++++++++++++++++++++++++++
 1 file changed, 77 insertions(+)

diff --git a/example/src/Examples/ButtonExample.tsx b/example/src/Examples/ButtonExample.tsx
index 9b2884f24d..4636afd557 100644
--- a/example/src/Examples/ButtonExample.tsx
+++ b/example/src/Examples/ButtonExample.tsx
@@ -10,6 +10,13 @@ const ButtonExample = () => {
 
   const color = theme.colors.inversePrimary;
 
+  const [selectedToggles, setSelectedToggles] = React.useState<
+    Record<string, boolean>
+  >({});
+
+  const toggle = (key: string) =>
+    setSelectedToggles((prev) => ({ ...prev, [key]: !prev[key] }));
+
   return (
     <ScreenWrapper>
       <List.Section title="Text button (text)">
@@ -341,6 +348,76 @@ const ButtonExample = () => {
           })}
         </View>
       </List.Section>
+      <List.Section title="Size (expressive)">
+        <View style={styles.row}>
+          {(
+            ['extra-small', 'small', 'medium', 'large', 'extra-large'] as const
+          ).map((size) => (
+            <Button
+              key={size}
+              mode="contained"
+              size={size}
+              icon="star"
+              onPress={() => {}}
+              style={styles.button}
+              label={size}
+            />
+          ))}
+        </View>
+      </List.Section>
+      <List.Section title="Shape (expressive)">
+        <View style={styles.row}>
+          {(['extra-small', 'small', 'medium', 'large'] as const).map(
+            (size) => (
+              <Button
+                key={`round-${size}`}
+                mode="outlined"
+                size={size}
+                shape="round"
+                onPress={() => {}}
+                style={styles.button}
+                label={`${size} round`}
+              />
+            )
+          )}
+        </View>
+        <View style={styles.row}>
+          {(['extra-small', 'small', 'medium', 'large'] as const).map(
+            (size) => (
+              <Button
+                key={`square-${size}`}
+                mode="outlined"
+                size={size}
+                shape="square"
+                onPress={() => {}}
+                style={styles.button}
+                label={`${size} square`}
+              />
+            )
+          )}
+        </View>
+      </List.Section>
+      <List.Section title="Toggle (expressive)">
+        <View style={styles.row}>
+          {(['outlined', 'text', 'contained-tonal'] as const).map((mode) => {
+            const key = `toggle-${mode}`;
+            const selected = !!selectedToggles[key];
+            return (
+              <Button
+                key={key}
+                mode={mode}
+                size="small"
+                shape="round"
+                selected={selected}
+                onPress={() => toggle(key)}
+                style={styles.button}
+                icon={selected ? 'check' : 'plus'}
+                label={mode}
+              />
+            );
+          })}
+        </View>
+      </List.Section>
     </ScreenWrapper>
   );
 };

From e4f8c435a53f941261aaa31a0c1d6537a49bdf21 Mon Sep 17 00:00:00 2001
From: Hristo Totov <47380018+hristototov@users.noreply.github.com>
Date: Wed, 20 May 2026 12:21:08 +0300
Subject: [PATCH 12/24] docs: update react-native-web guide to reflect
 Expo-based setup (#4953)

---
 docs/docs/guides/05-react-native-web.md | 278 ++----------------------
 1 file changed, 19 insertions(+), 259 deletions(-)

diff --git a/docs/docs/guides/05-react-native-web.md b/docs/docs/guides/05-react-native-web.md
index af0331a7d9..d9b69b8250 100644
--- a/docs/docs/guides/05-react-native-web.md
+++ b/docs/docs/guides/05-react-native-web.md
@@ -4,279 +4,39 @@ title: Using on the Web
 
 # Using on the Web
 
-## Pre-requisites
+React Native Paper supports web via [React Native for Web](https://necolas.github.io/react-native-web/), which lets you run React Native components in a browser using React DOM.
 
-Make sure that you have followed the getting started guide and have `react-native-paper` installed and configured before following this guide.
+Before continuing, make sure you have React Native Paper installed and configured by following the [Getting Started guide](getting-started.md).
 
-We're going to use [react-native-web](https://github.com/necolas/react-native-web) and [webpack](https://webpack.js.org/) to use React Native Paper on the web, so let's install them as well.
+## Setting up web support with Expo
 
-To install `react-native-web`, run:
+The recommended way to run React Native Paper on the web is with Expo, which has built-in web support via React Native for Web. Install the required dependencies:
 
-```bash npm2yarn
-npm install react-native-web react-dom react-art
+```bash
+npx expo install react-dom react-native-web @expo/metro-runtime
 ```
 
-### Using CRA ([Create React App](https://github.com/facebook/create-react-app))
+Then start the web server:
 
-Install [`react-app-rewired`](https://github.com/timarney/react-app-rewired) to override `webpack` configuration:
-
-```bash npm2yarn
-npm install --save-dev react-app-rewired
-```
-
-[Configure `babel-loader`](#2-configure-babel-loader) using a new file called `config-overrides.js`:
-
-```js
-module.exports = function override(config, env) {
-  config.module.rules.push({
-    test: /\.js$/,
-    exclude: /node_modules[/\\](?!react-native-vector-icons)/,
-    use: {
-      loader: 'babel-loader',
-      options: {
-        // Disable reading babel configuration
-        babelrc: false,
-        configFile: false,
-
-        // The configuration for compilation
-        presets: [
-          ['@babel/preset-env', { useBuiltIns: 'usage' }],
-          '@babel/preset-react',
-          '@babel/preset-flow',
-          '@babel/preset-typescript',
-        ],
-        plugins: [
-          '@babel/plugin-proposal-class-properties',
-          '@babel/plugin-proposal-object-rest-spread',
-        ],
-      },
-    },
-  });
-
-  return config;
-};
-```
-
-Change your script in `package.json`:
-
-```diff
-/* package.json */
-
-  "scripts": {
--   "start": "react-scripts start",
-+   "start": "react-app-rewired start",
--   "build": "react-scripts build",
-+   "build": "react-app-rewired build",
--   "test": "react-scripts test --env=jsdom",
-+   "test": "react-app-rewired test --env=jsdom"
-}
-```
-
-### Custom webpack setup
-
-To install `webpack`, run:
-
-```bash npm2yarn
-npm install --save-dev webpack webpack-cli webpack-dev-server
-```
-
-If you don't have a webpack config in your project, copy the following to `webpack.config.js` get started:
-
-```js
-const path = require('path');
-
-module.exports = {
-  mode: 'development',
-
-  // Path to the entry file, change it according to the path you have
-  entry: path.join(__dirname, 'App.js'),
-
-  // Path for the output files
-  output: {
-    path: path.join(__dirname, 'dist'),
-    filename: 'app.bundle.js',
-  },
-
-  // Enable source map support
-  devtool: 'source-map',
-
-  // Loaders and resolver config
-  module: {
-    rules: [],
-  },
-  resolve: {},
-
-  // Development server config
-  devServer: {
-    contentBase: [path.join(__dirname, 'public')],
-    historyApiFallback: true,
-  },
-};
-```
-
-Also create a folder named `public` and add the following file named `index.html`:
-
-```html
-<!DOCTYPE html>
-<head>
-  <meta charset="utf-8" />
-  <meta httpEquiv="X-UA-Compatible" content="IE=edge" />
-
-  <meta
-    name="viewport"
-    content="width=device-width,minimum-scale=1,initial-scale=1"
-  />
-
-  <title>App</title>
-
-  <style>
-    html,
-    body,
-    #root {
-      height: 100%;
-    }
-
-    #root {
-      display: flex;
-      flex-direction: column;
-    }
-  </style>
-</head>
-<body>
-  <div id="root"></div>
-  <script src="app.bundle.js"></script>
-</body>
-```
-
-Now we're ready to start configuring the project.
-
-## Configure webpack
-
-### 1. Alias `react-native` to `react-native-web`
-
-First, we have to tell webpack to use `react-native-web` instead of `react-native`. Add the following alias in your webpack config under `resolve`:
-
-```js
-alias: {
-  'react-native$': require.resolve('react-native-web'),
-}
-```
-
-### 2. Configure `babel-loader`
-
-Next, we want to tell `babel-loader` to compile `react-native-paper` and `react-native-vector-icons`. We would also want to disable reading the babel configuration files to prevent any conflicts.
-
-First install the required dependencies:
-
-```bash npm2yarn
-npm install --save-dev babel-loader @babel/preset-env @babel/preset-react @babel/preset-flow @babel/preset-typescript @babel/plugin-proposal-class-properties @babel/plugin-proposal-object-rest-spread
-```
-
-Now, add the following in the `module.rules` array in your webpack config:
-
-```js
-{
-  test: /\.js$/,
-  exclude: /node_modules[/\\](?!react-native-vector-icons)/,
-  use: {
-    loader: 'babel-loader',
-    options: {
-      // Disable reading babel configuration
-      babelrc: false,
-      configFile: false,
-
-      // The configuration for compilation
-      presets: [
-        ['@babel/preset-env', { useBuiltIns: 'usage' }],
-        '@babel/preset-react',
-        '@babel/preset-flow',
-        "@babel/preset-typescript"
-      ],
-      plugins: [
-        '@babel/plugin-proposal-class-properties',
-        '@babel/plugin-proposal-object-rest-spread'
-      ],
-    },
-  },
-},
+```bash
+npx expo start --web
 ```
 
-### 3. Configure `file-loader`
+No additional bundler configuration is required. See the [Expo Web docs](https://docs.expo.dev/workflow/web/) for details on how Expo configures React Native for Web under the hood.
 
-#### webpack < 5.0
+## Without Expo
 
-To be able to import images and other assets using `require`, we need to configure `file-loader`. Let's install it:
-
-```bash npm2yarn
-npm install --save-dev file-loader
-```
+If you're not using Expo, follow the [React Native for Web setup guide](https://necolas.github.io/react-native-web/docs/setup/) to configure your bundler. The setup covers aliasing `react-native` to `react-native-web` in webpack, Babel, and Jest.
 
-To configure it, add the following in the `module.rules` array in your webpack config:
+You will also need to manually load the Material Design icon font used by Paper. Add the following to your HTML shell or inject it at the root of your app:
 
-```js
-{
-  test: /\.(jpg|png|woff|woff2|eot|ttf|svg)$/,
-  loader: 'file-loader',
+```css
+@font-face {
+  font-family: 'MaterialDesignIcons';
+  src: url('~@react-native-vector-icons/material-design-icons/fonts/MaterialDesignIcons.ttf') format('truetype');
 }
 ```
 
-##### webpack >= 5.0
-
-Use `asset/resource`, since `file-loader` was deprecated in webpack v5.
-
-```js
-{
-  test: /\.(jpg|png|woff|woff2|eot|ttf|svg)$/,
-  type: 'asset/resource'
-}
-```
-
-## Load the Material Design Icons
-
-If you followed the getting started guide, you should have the following code in your root component:
-
-```js
-<PaperProvider>
-  <App />
-</PaperProvider>
-```
-
-Now we need tweak this section to load the Material Design Icons from the [`react-native-vector-icons`](https://github.com/oblador/react-native-vector-icons) library:
-
-```js
-<PaperProvider>
-  <React.Fragment>
-    {Platform.OS === 'web' ? (
-      <style type="text/css">{`
-        @font-face {
-          font-family: 'MaterialDesignIcons';
-          src: url(${require('@react-native-vector-icons/material-design-icons/fonts/MaterialDesignIcons.ttf')}) format('truetype');
-        }
-      `}</style>
-    ) : null}
-    <App />
-  </React.Fragment>
-</PaperProvider>
-```
-
-Remember to import `Platform` from `react-native` at the top:
-
-```js
-import { Platform } from 'react-native';
-```
-
-You can also load these fonts using [`css-loader`](https://github.com/webpack-contrib/css-loader) if you prefer.
-
-## Load the Roboto fonts (optional)
-
-The default theme in React Native Paper uses the Roboto font. You can add them to your project following [the instructions on its Google Fonts page](https://fonts.google.com/specimen/Roboto?selection.family=Roboto:100,300,400,500).
-
-## We're done!
-
-You can run `webpack-dev-server` to run the webpack server and open your project in the browser. You can add the following script in your `package.json` under the `"scripts"` section to make it easier:
-
-```json
-"web": "webpack-dev-server --open"
-```
+## Load the Roboto font (optional)
 
-Now you can run `yarn web` to run the project on web.
+The default Paper theme uses the Roboto typeface. With Expo, use the [`@expo-google-fonts/roboto`](https://github.com/expo/google-fonts/tree/master/font-packages/roboto) package. For other setups, follow the instructions on the [Roboto specimen page](https://fonts.google.com/specimen/Roboto).

From a7108a949b3cf840f1596b656ec93537311f4b41 Mon Sep 17 00:00:00 2001
From: Fabrizio Cucci <fabrizio.cucci@gmail.com>
Date: Tue, 19 May 2026 16:09:14 +0100
Subject: [PATCH 13/24] feat(checkbox): add error state via MD3 error tokens

Adds an `error?: boolean` prop to Checkbox, CheckboxAndroid and
CheckboxIOS. When true, the outline (unchecked) and container (checked /
indeterminate) use `theme.colors.error`. The `disabled` state and
explicit `color` / `uncheckedColor` overrides take precedence.

Addresses one bullet from #4937 / #4949 (Checkbox section,
"Error state not implemented"). Verified visually on iOS Simulator
and Android Emulator across light and dark themes.
---
 src/components/Checkbox/Checkbox.tsx          |   7 +
 src/components/Checkbox/CheckboxAndroid.tsx   |   9 ++
 src/components/Checkbox/CheckboxIOS.tsx       |   8 ++
 src/components/Checkbox/utils.ts              |  32 ++++-
 .../__tests__/Checkbox/utils.test.tsx         | 123 ++++++++++++++++++
 5 files changed, 177 insertions(+), 2 deletions(-)

diff --git a/src/components/Checkbox/Checkbox.tsx b/src/components/Checkbox/Checkbox.tsx
index b6cfd9a64b..a035e951fa 100644
--- a/src/components/Checkbox/Checkbox.tsx
+++ b/src/components/Checkbox/Checkbox.tsx
@@ -27,6 +27,13 @@ export type Props = {
    * Custom color for checkbox.
    */
   color?: string;
+  /**
+   * Whether the checkbox is in an error state. When true, the outline
+   * (unchecked) and container (checked / indeterminate) use
+   * `theme.colors.error`. `disabled` and explicit `color`/`uncheckedColor`
+   * overrides take precedence.
+   */
+  error?: boolean;
   /**
    * @optional
    */
diff --git a/src/components/Checkbox/CheckboxAndroid.tsx b/src/components/Checkbox/CheckboxAndroid.tsx
index 8a93cc6a70..d73bdf57c5 100644
--- a/src/components/Checkbox/CheckboxAndroid.tsx
+++ b/src/components/Checkbox/CheckboxAndroid.tsx
@@ -34,6 +34,13 @@ export type Props = $RemoveChildren<typeof TouchableRipple> & {
    * Custom color for checkbox.
    */
   color?: ColorValue;
+  /**
+   * Whether the checkbox is in an error state. When true, the outline
+   * (unchecked) and container (checked / indeterminate) use
+   * `theme.colors.error`. `disabled` and explicit `color`/`uncheckedColor`
+   * overrides take precedence.
+   */
+  error?: boolean;
   /**
    * @optional
    */
@@ -60,6 +67,7 @@ const CheckboxAndroid = ({
   disabled,
   onPress,
   testID,
+  error,
   ...rest
 }: Props) => {
   const theme = useInternalTheme(themeOverrides);
@@ -107,6 +115,7 @@ const CheckboxAndroid = ({
       checked,
       customColor: rest.color,
       customUncheckedColor: rest.uncheckedColor,
+      error,
     });
 
   const borderWidth = scaleAnim.interpolate({
diff --git a/src/components/Checkbox/CheckboxIOS.tsx b/src/components/Checkbox/CheckboxIOS.tsx
index d4a8127180..5830359372 100644
--- a/src/components/Checkbox/CheckboxIOS.tsx
+++ b/src/components/Checkbox/CheckboxIOS.tsx
@@ -29,6 +29,12 @@ export type Props = $RemoveChildren<typeof TouchableRipple> & {
    * Custom color for checkbox.
    */
   color?: ColorValue;
+  /**
+   * Whether the checkbox is in an error state. When true, the checked /
+   * indeterminate icon uses `theme.colors.error`. `disabled` and explicit
+   * `color` overrides take precedence.
+   */
+  error?: boolean;
   /**
    * @optional
    */
@@ -52,6 +58,7 @@ const CheckboxIOS = ({
   onPress,
   theme: themeOverrides,
   testID,
+  error,
   ...rest
 }: Props) => {
   const theme = useInternalTheme(themeOverrides);
@@ -62,6 +69,7 @@ const CheckboxIOS = ({
     theme,
     disabled,
     customColor: rest.color,
+    error,
   });
 
   const icon = indeterminate ? 'minus' : 'check';
diff --git a/src/components/Checkbox/utils.ts b/src/components/Checkbox/utils.ts
index f47457151b..87362df00c 100644
--- a/src/components/Checkbox/utils.ts
+++ b/src/components/Checkbox/utils.ts
@@ -8,28 +8,40 @@ const { stateOpacity } = tokens.md.ref;
 const getAndroidCheckedColor = ({
   theme,
   customColor,
+  error,
 }: {
   theme: InternalTheme;
   customColor?: ColorValue;
+  error?: boolean;
 }) => {
   if (customColor) {
     return customColor;
   }
 
+  if (error) {
+    return theme.colors.error;
+  }
+
   return theme.colors.primary;
 };
 
 const getAndroidUncheckedColor = ({
   theme,
   customUncheckedColor,
+  error,
 }: {
   theme: InternalTheme;
   customUncheckedColor?: ColorValue;
+  error?: boolean;
 }) => {
   if (customUncheckedColor) {
     return customUncheckedColor;
   }
 
+  if (error) {
+    return theme.colors.error;
+  }
+
   return theme.colors.onSurfaceVariant;
 };
 
@@ -62,17 +74,20 @@ export const getAndroidSelectionControlColor = ({
   checked,
   customColor,
   customUncheckedColor,
+  error,
 }: {
   theme: InternalTheme;
   checked: boolean;
   disabled?: boolean;
   customColor?: ColorValue;
   customUncheckedColor?: ColorValue;
+  error?: boolean;
 }) => {
-  const checkedColor = getAndroidCheckedColor({ theme, customColor });
+  const checkedColor = getAndroidCheckedColor({ theme, customColor, error });
   const uncheckedColor = getAndroidUncheckedColor({
     theme,
     customUncheckedColor,
+    error,
   });
   const selectionControlOpacity = disabled
     ? stateOpacity.disabled
@@ -94,10 +109,12 @@ const getIOSCheckedColor = ({
   theme,
   disabled,
   customColor,
+  error,
 }: {
   theme: InternalTheme;
   customColor?: ColorValue;
   disabled?: boolean;
+  error?: boolean;
 }) => {
   if (disabled) {
     return theme.colors.primary;
@@ -107,6 +124,10 @@ const getIOSCheckedColor = ({
     return customColor;
   }
 
+  if (error) {
+    return theme.colors.error;
+  }
+
   return theme.colors.primary;
 };
 
@@ -114,12 +135,19 @@ export const getSelectionControlIOSColor = ({
   theme,
   disabled,
   customColor,
+  error,
 }: {
   theme: InternalTheme;
   disabled?: boolean;
   customColor?: ColorValue;
+  error?: boolean;
 }) => {
-  const checkedColor = getIOSCheckedColor({ theme, disabled, customColor });
+  const checkedColor = getIOSCheckedColor({
+    theme,
+    disabled,
+    customColor,
+    error,
+  });
   const checkedColorOpacity = disabled
     ? stateOpacity.disabled
     : stateOpacity.enabled;
diff --git a/src/components/__tests__/Checkbox/utils.test.tsx b/src/components/__tests__/Checkbox/utils.test.tsx
index a18dd2f78e..2aa20fd688 100644
--- a/src/components/__tests__/Checkbox/utils.test.tsx
+++ b/src/components/__tests__/Checkbox/utils.test.tsx
@@ -87,6 +87,82 @@ describe('getAndroidSelectionControlColor - checkbox color', () => {
       selectionControlColor: getTheme(false).colors.onSurfaceVariant,
     });
   });
+
+  it('should return error color, checked, when error is true', () => {
+    expect(
+      getAndroidSelectionControlColor({
+        theme: getTheme(),
+        checked: true,
+        error: true,
+      })
+    ).toMatchObject({
+      selectionControlColor: getTheme().colors.error,
+    });
+  });
+
+  it('should return error color, unchecked, when error is true', () => {
+    expect(
+      getAndroidSelectionControlColor({
+        theme: getTheme(),
+        checked: false,
+        error: true,
+      })
+    ).toMatchObject({
+      selectionControlColor: getTheme().colors.error,
+    });
+  });
+
+  it('should return error color, checked, dark mode, when error is true', () => {
+    expect(
+      getAndroidSelectionControlColor({
+        theme: getTheme(true),
+        checked: true,
+        error: true,
+      })
+    ).toMatchObject({
+      selectionControlColor: getTheme(true).colors.error,
+    });
+  });
+
+  it('should return disabled color when both disabled and error are true (disabled wins)', () => {
+    expect(
+      getAndroidSelectionControlColor({
+        theme: getTheme(),
+        disabled: true,
+        checked: true,
+        error: true,
+      })
+    ).toMatchObject({
+      selectionControlColor: getTheme().colors.onSurface,
+      selectionControlOpacity: stateOpacity.disabled,
+    });
+  });
+
+  it('should return custom color when both customColor and error are true, checked (customColor wins)', () => {
+    expect(
+      getAndroidSelectionControlColor({
+        theme: getTheme(),
+        checked: true,
+        customColor: 'purple',
+        error: true,
+      })
+    ).toMatchObject({
+      selectionControlColor: 'purple',
+    });
+  });
+
+  it('should return custom unchecked color when both customUncheckedColor and error are true, unchecked (customUncheckedColor wins)', () => {
+    expect(
+      getAndroidSelectionControlColor({
+        theme: getTheme(),
+        checked: false,
+        customUncheckedColor: 'purple',
+        error: true,
+      })
+    ).toMatchObject({
+      selectionControlColor: 'purple',
+    });
+  });
 });
 
 describe('getSelectionControlIOSColor - checked color', () => {
@@ -122,4 +198,51 @@ describe('getSelectionControlIOSColor - checked color', () => {
       checkedColor: getTheme().colors.primary,
     });
   });
+
+  it('should return error color when error is true', () => {
+    expect(
+      getSelectionControlIOSColor({
+        theme: getTheme(),
+        error: true,
+      })
+    ).toMatchObject({
+      checkedColor: getTheme().colors.error,
+    });
+  });
+
+  it('should return error color, dark mode, when error is true', () => {
+    expect(
+      getSelectionControlIOSColor({
+        theme: getTheme(true),
+        error: true,
+      })
+    ).toMatchObject({
+      checkedColor: getTheme(true).colors.error,
+    });
+  });
+
+  it('should return disabled color when both disabled and error are true (disabled wins)', () => {
+    expect(
+      getSelectionControlIOSColor({
+        theme: getTheme(),
+        disabled: true,
+        error: true,
+      })
+    ).toMatchObject({
+      checkedColor: getTheme().colors.primary,
+      checkedColorOpacity: stateOpacity.disabled,
+    });
+  });
+
+  it('should return custom color when both customColor and error are true (customColor wins)', () => {
+    expect(
+      getSelectionControlIOSColor({
+        theme: getTheme(),
+        customColor: 'purple',
+        error: true,
+      })
+    ).toMatchObject({
+      checkedColor: 'purple',
+    });
+  });
 });

From 2d46867a5ded991b67423d28df8bd6a80fe974a7 Mon Sep 17 00:00:00 2001
From: Aziz Becha <aziz07becha@gmail.com>
Date: Wed, 20 May 2026 18:41:28 +0100
Subject: [PATCH 14/24] feat(button): localize iconPosition via useLocale
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Treat `iconPosition` as logical (reading-order) and swap leading/trailing
under RTL. The layout engine already mirrors `flexDirection` and physical
margins when the platform direction is RTL (native I18nManager, or
react-native-web with an active I18nManager), so we only flip manually when
the locale direction disagrees with the platform default — e.g. a web
LocaleProvider override where I18nManager is a no-op. This avoids a
double-flip on native RTL.
---
 src/components/Button/Button.tsx         |  9 ++++++++-
 src/components/__tests__/Button.test.tsx | 23 +++++++++++++++++++++++
 2 files changed, 31 insertions(+), 1 deletion(-)

diff --git a/src/components/Button/Button.tsx b/src/components/Button/Button.tsx
index 600d07342a..8f52d6345d 100644
--- a/src/components/Button/Button.tsx
+++ b/src/components/Button/Button.tsx
@@ -24,6 +24,7 @@ import {
   getButtonSizeStyle,
   getButtonTouchableRippleStyle,
 } from './utils';
+import { getDefaultDirection, useLocale } from '../../core/locale';
 import { useInternalTheme } from '../../core/theming';
 import type { $Omit, Theme, ThemeProp } from '../../types';
 import { forwardRef } from '../../utils/forwardRef';
@@ -272,6 +273,7 @@ const Button = (
   ref: React.ForwardedRef<View>
 ) => {
   const theme = useInternalTheme(themeOverrides);
+  const { direction } = useLocale();
   const isMode = (modeToCompare: ButtonMode) => mode === modeToCompare;
   const { animation } = theme;
   const uppercase = uppercaseProp ?? false;
@@ -298,7 +300,12 @@ const Button = (
     );
   }
 
-  const isTrailingIcon = iconPosition === 'trailing' || usesReverseContentStyle;
+  const requestedTrailingIcon =
+    iconPosition === 'trailing' || usesReverseContentStyle;
+  const shouldFlipForRTL = direction !== getDefaultDirection();
+  const isTrailingIcon = shouldFlipForRTL
+    ? !requestedTrailingIcon
+    : requestedTrailingIcon;
 
   const hasPassedTouchHandler = hasTouchHandler({
     onPress,
diff --git a/src/components/__tests__/Button.test.tsx b/src/components/__tests__/Button.test.tsx
index 17c4fca13c..5cedd647da 100644
--- a/src/components/__tests__/Button.test.tsx
+++ b/src/components/__tests__/Button.test.tsx
@@ -4,6 +4,7 @@ import { Animated, PlatformColor, StyleSheet } from 'react-native';
 import { act, fireEvent } from '@testing-library/react-native';
 import color from 'color';
 
+import { LocaleProvider } from '../../core/locale';
 import { getTheme } from '../../core/theming';
 import { render } from '../../test-utils';
 import { pink500, white } from '../../theme/colors';
@@ -82,6 +83,28 @@ it('renders button with icon in reverse order', () => {
   expect(tree).toMatchSnapshot();
 });
 
+it('swaps the icon to the trailing edge under RTL', () => {
+  const { getByTestId: getByTestIdLTR } = render(
+    <Button icon="camera" iconPosition="leading" label="Icon" />
+  );
+  const { getByTestId: getByTestIdRTL } = render(
+    <LocaleProvider direction="rtl">
+      <Button icon="camera" iconPosition="leading" label="Icon" />
+    </LocaleProvider>
+  );
+
+  const ltrIconStyle = StyleSheet.flatten(
+    getByTestIdLTR('button-icon-container').props.style
+  );
+  const rtlIconStyle = StyleSheet.flatten(
+    getByTestIdRTL('button-icon-container').props.style
+  );
+
+  // The physical margins swap so a "leading" icon sits on the right in RTL.
+  expect(rtlIconStyle.marginLeft).toBe(ltrIconStyle.marginRight);
+  expect(rtlIconStyle.marginRight).toBe(ltrIconStyle.marginLeft);
+});
+
 it('renders loading button', () => {
   const tree = render(<Button loading label="Loading Button" />).toJSON();
 

From bccc3ae7a0f75bc6e64455f5ac310c988d00cc28 Mon Sep 17 00:00:00 2001
From: Aziz Becha <aziz07becha@gmail.com>
Date: Wed, 20 May 2026 18:47:06 +0100
Subject: [PATCH 15/24] refactor(button): unify naming to label and drop md3
 style prefix

Use a single `label` vocabulary internally to match the public `label` prop
and the MD3 spec:
- getButtonColors returns labelColor/labelOpacity (was textColor/textOpacity)
- getButtonTextColor -> getButtonLabelColor; customTextColor -> customLabelColor
- getButtonRippleColor takes labelColor

Also drop the md3 prefix from the no-size styles (md3Label* -> legacyLabel*).
The public `textColor` prop is unchanged. Internal-only rename; no behavior or
snapshot change.
---
 src/components/Button/Button.tsx         | 54 ++++++++++++------------
 src/components/Button/utils.tsx          | 32 +++++++-------
 src/components/__tests__/Button.test.tsx | 44 +++++++++----------
 3 files changed, 65 insertions(+), 65 deletions(-)

diff --git a/src/components/Button/Button.tsx b/src/components/Button/Button.tsx
index 8f52d6345d..3940702df8 100644
--- a/src/components/Button/Button.tsx
+++ b/src/components/Button/Button.tsx
@@ -245,7 +245,7 @@ const Button = (
     icon,
     iconPosition,
     buttonColor: customButtonColor,
-    textColor: customTextColor,
+    textColor: customLabelColor,
     label,
     children,
     accessibilityLabel,
@@ -387,27 +387,27 @@ const Button = (
   const {
     backgroundColor,
     borderColor,
-    textColor,
-    textOpacity,
+    labelColor,
+    labelOpacity,
     borderWidth,
     backgroundOpacity,
   } = React.useMemo(
     () =>
       getButtonColors({
         customButtonColor,
-        customTextColor,
+        customLabelColor,
         theme,
         mode,
         disabled,
         dark,
         selected,
       }),
-    [customButtonColor, customTextColor, theme, mode, disabled, dark, selected]
+    [customButtonColor, customLabelColor, theme, mode, disabled, dark, selected]
   );
 
   const rippleColor = React.useMemo(
-    () => getButtonRippleColor({ textColor, customRippleColor }),
-    [textColor, customRippleColor]
+    () => getButtonRippleColor({ labelColor, customRippleColor }),
+    [labelColor, customRippleColor]
   );
 
   const touchableStyle = React.useMemo(
@@ -439,7 +439,7 @@ const Button = (
     [touchableStyle, borderWidth]
   );
 
-  const { color: customLabelColor, fontSize: customLabelSize } = React.useMemo(
+  const { color: labelStyleColor, fontSize: labelStyleSize } = React.useMemo(
     () => StyleSheet.flatten(labelStyle) || {},
     [labelStyle]
   );
@@ -449,12 +449,12 @@ const Button = (
     [size]
   );
 
-  const textStyle = React.useMemo(
+  const labelTypeStyle = React.useMemo(
     () => ({
-      color: textColor,
+      color: labelColor,
       ...(theme as Theme).fonts[sizeStyle?.labelVariant ?? 'labelLarge'],
     }),
-    [textColor, theme, sizeStyle]
+    [labelColor, theme, sizeStyle]
   );
 
   const iconStyle = React.useMemo(
@@ -532,7 +532,7 @@ const Button = (
                   },
                 ]
               : []),
-            { opacity: textOpacity },
+            { opacity: labelOpacity },
             contentStyle,
           ]}
         >
@@ -543,22 +543,22 @@ const Button = (
             >
               <Icon
                 source={icon}
-                size={sizeStyle?.iconSize ?? customLabelSize ?? iconSize}
+                size={sizeStyle?.iconSize ?? labelStyleSize ?? iconSize}
                 color={
-                  typeof customLabelColor === 'string'
-                    ? customLabelColor
-                    : textColor
+                  typeof labelStyleColor === 'string'
+                    ? labelStyleColor
+                    : labelColor
                 }
               />
             </View>
           ) : null}
           {loading ? (
             <ActivityIndicator
-              size={sizeStyle?.iconSize ?? customLabelSize ?? iconSize}
+              size={sizeStyle?.iconSize ?? labelStyleSize ?? iconSize}
               color={
-                typeof customLabelColor === 'string'
-                  ? customLabelColor
-                  : textColor
+                typeof labelStyleColor === 'string'
+                  ? labelStyleColor
+                  : labelColor
               }
               style={iconStyle ?? undefined}
             />
@@ -574,12 +574,12 @@ const Button = (
                 ? styles.sizedLabel
                 : isMode('text')
                 ? icon || loading
-                  ? styles.md3LabelTextAddons
-                  : styles.md3LabelText
-                : styles.md3Label,
+                  ? styles.legacyLabelTextAddons
+                  : styles.legacyLabelText
+                : styles.legacyLabel,
               !sizeStyle && compact && styles.compactLabel,
               uppercase && styles.uppercaseLabel,
-              textStyle,
+              labelTypeStyle,
               labelStyle,
             ]}
             maxFontSizeMultiplier={maxFontSizeMultiplier}
@@ -623,14 +623,14 @@ const styles = StyleSheet.create({
   uppercaseLabel: {
     textTransform: 'uppercase',
   },
-  md3Label: {
+  legacyLabel: {
     marginVertical: 10,
     marginHorizontal: 24,
   },
-  md3LabelText: {
+  legacyLabelText: {
     marginHorizontal: 12,
   },
-  md3LabelTextAddons: {
+  legacyLabelTextAddons: {
     marginHorizontal: 16,
   },
 });
diff --git a/src/components/Button/utils.tsx b/src/components/Button/utils.tsx
index c252537573..9fe95ac8d5 100644
--- a/src/components/Button/utils.tsx
+++ b/src/components/Button/utils.tsx
@@ -215,22 +215,22 @@ const getButtonBackgroundColor = ({
   return 'transparent';
 };
 
-const getButtonTextColor = ({
+const getButtonLabelColor = ({
   isMode,
   theme,
   disabled,
-  customTextColor,
+  customLabelColor,
   backgroundColor,
   dark,
   selected,
 }: BaseProps & {
-  customTextColor?: ColorValue;
+  customLabelColor?: ColorValue;
   backgroundColor: ColorValue;
   dark?: boolean;
 }) => {
   const { colors } = theme as Theme;
-  if (customTextColor && !disabled) {
-    return customTextColor;
+  if (customLabelColor && !disabled) {
+    return customLabelColor;
   }
 
   if (disabled) {
@@ -298,7 +298,7 @@ export const getButtonColors = ({
   theme,
   mode,
   customButtonColor,
-  customTextColor,
+  customLabelColor,
   disabled,
   dark,
   selected,
@@ -306,7 +306,7 @@ export const getButtonColors = ({
   theme: InternalTheme;
   mode: ButtonMode;
   customButtonColor?: ColorValue;
-  customTextColor?: ColorValue;
+  customLabelColor?: ColorValue;
   disabled?: boolean;
   dark?: boolean;
   selected?: boolean;
@@ -323,11 +323,11 @@ export const getButtonColors = ({
     selected,
   });
 
-  const textColor = getButtonTextColor({
+  const labelColor = getButtonLabelColor({
     isMode,
     theme,
     disabled,
-    customTextColor,
+    customLabelColor,
     backgroundColor,
     dark,
     selected,
@@ -337,7 +337,7 @@ export const getButtonColors = ({
 
   const borderWidth = getButtonBorderWidth({ isMode, selected });
 
-  const textOpacity = disabled ? stateOpacity.disabled : stateOpacity.enabled;
+  const labelOpacity = disabled ? stateOpacity.disabled : stateOpacity.enabled;
 
   const backgroundOpacity =
     disabled && !isMode('outlined') && !isMode('text')
@@ -347,8 +347,8 @@ export const getButtonColors = ({
   return {
     backgroundColor,
     borderColor,
-    textColor,
-    textOpacity,
+    labelColor,
+    labelOpacity,
     borderWidth,
     backgroundOpacity,
   };
@@ -364,21 +364,21 @@ export const getButtonColors = ({
  * its own default state-layer color.
  */
 export const getButtonRippleColor = ({
-  textColor,
+  labelColor,
   customRippleColor,
 }: {
-  textColor: ColorValue;
+  labelColor: ColorValue;
   customRippleColor?: ColorValue;
 }): ColorValue | undefined => {
   if (customRippleColor) {
     return customRippleColor;
   }
 
-  if (typeof textColor !== 'string') {
+  if (typeof labelColor !== 'string') {
     return undefined;
   }
 
-  return color(textColor).alpha(stateOpacity.pressed).rgb().string();
+  return color(labelColor).alpha(stateOpacity.pressed).rgb().string();
 };
 
 type ViewStyleBorderRadiusStyles = Partial<
diff --git a/src/components/__tests__/Button.test.tsx b/src/components/__tests__/Button.test.tsx
index 5cedd647da..858bff3a6a 100644
--- a/src/components/__tests__/Button.test.tsx
+++ b/src/components/__tests__/Button.test.tsx
@@ -607,44 +607,44 @@ describe('getButtonColors - background color', () => {
 });
 
 describe('getButtonColors - text color', () => {
-  const customTextColor = '#313131';
+  const customLabelColor = '#313131';
 
   it('should return custom text color no matter what is the theme version, when not disabled', () => {
     expect(
       getButtonColors({
-        customTextColor,
+        customLabelColor,
         theme: getTheme(),
         disabled: false,
         mode: 'text',
       })
-    ).toMatchObject({ textColor: customTextColor });
+    ).toMatchObject({ labelColor: customLabelColor });
   });
 
   it('should return correct disabled text color, for theme version 3, no matter what the mode is', () => {
     expect(
       getButtonColors({
-        customTextColor,
+        customLabelColor,
         theme: getTheme(),
         disabled: true,
         mode: 'text',
       })
     ).toMatchObject({
-      textColor: getTheme().colors.onSurface,
-      textOpacity: stateOpacity.disabled,
+      labelColor: getTheme().colors.onSurface,
+      labelOpacity: stateOpacity.disabled,
     });
   });
 
   it('should return correct disabled text color, for theme version 3, dark theme, no matter what the mode is', () => {
     expect(
       getButtonColors({
-        customTextColor,
+        customLabelColor,
         theme: getTheme(true),
         disabled: true,
         mode: 'text',
       })
     ).toMatchObject({
-      textColor: getTheme(true).colors.onSurface,
-      textOpacity: stateOpacity.disabled,
+      labelColor: getTheme(true).colors.onSurface,
+      labelOpacity: stateOpacity.disabled,
     });
   });
 
@@ -657,7 +657,7 @@ describe('getButtonColors - text color', () => {
           dark: true,
         })
       ).toMatchObject({
-        textColor: white,
+        labelColor: white,
       });
     })
   );
@@ -670,7 +670,7 @@ describe('getButtonColors - text color', () => {
           mode,
         })
       ).toMatchObject({
-        textColor: getTheme().colors.primary,
+        labelColor: getTheme().colors.primary,
       });
     })
   );
@@ -683,7 +683,7 @@ describe('getButtonColors - text color', () => {
           mode,
         })
       ).toMatchObject({
-        textColor: getTheme(true).colors.primary,
+        labelColor: getTheme(true).colors.primary,
       });
     })
   );
@@ -695,7 +695,7 @@ describe('getButtonColors - text color', () => {
         mode: 'contained',
       })
     ).toMatchObject({
-      textColor: getTheme().colors.onPrimary,
+      labelColor: getTheme().colors.onPrimary,
     });
   });
 
@@ -706,7 +706,7 @@ describe('getButtonColors - text color', () => {
         mode: 'contained',
       })
     ).toMatchObject({
-      textColor: getTheme(true).colors.onPrimary,
+      labelColor: getTheme(true).colors.onPrimary,
     });
   });
 
@@ -717,7 +717,7 @@ describe('getButtonColors - text color', () => {
         mode: 'contained-tonal',
       })
     ).toMatchObject({
-      textColor: getTheme().colors.onSecondaryContainer,
+      labelColor: getTheme().colors.onSecondaryContainer,
     });
   });
 
@@ -728,7 +728,7 @@ describe('getButtonColors - text color', () => {
         mode: 'contained-tonal',
       })
     ).toMatchObject({
-      textColor: getTheme(true).colors.onSecondaryContainer,
+      labelColor: getTheme(true).colors.onSecondaryContainer,
     });
   });
 });
@@ -839,19 +839,19 @@ describe('getButtonColors - border width', () => {
 describe('getButtonRippleColor', () => {
   it('returns the custom ripple color when one is provided', () => {
     expect(
-      getButtonRippleColor({ textColor: '#123456', customRippleColor: 'red' })
+      getButtonRippleColor({ labelColor: '#123456', customRippleColor: 'red' })
     ).toBe('red');
   });
 
   it('defaults to the label color at the pressed-state opacity', () => {
-    expect(getButtonRippleColor({ textColor: '#123456' })).toBe(
+    expect(getButtonRippleColor({ labelColor: '#123456' })).toBe(
       color('#123456').alpha(stateOpacity.pressed).rgb().string()
     );
   });
 
   it('returns undefined when the label color is not a plain string', () => {
     expect(
-      getButtonRippleColor({ textColor: PlatformColor('?attr/colorPrimary') })
+      getButtonRippleColor({ labelColor: PlatformColor('?attr/colorPrimary') })
     ).toBeUndefined();
   });
 });
@@ -995,7 +995,7 @@ describe('selected prop', () => {
       })
     ).toMatchObject({
       backgroundColor: getTheme().colors.secondaryContainer,
-      textColor: getTheme().colors.onSecondaryContainer,
+      labelColor: getTheme().colors.onSecondaryContainer,
       borderColor: 'transparent',
       borderWidth: 0,
     });
@@ -1010,7 +1010,7 @@ describe('selected prop', () => {
       })
     ).toMatchObject({
       backgroundColor: getTheme().colors.secondaryContainer,
-      textColor: getTheme().colors.onSecondaryContainer,
+      labelColor: getTheme().colors.onSecondaryContainer,
     });
   });
 
@@ -1023,7 +1023,7 @@ describe('selected prop', () => {
       })
     ).toMatchObject({
       backgroundColor: getTheme().colors.primary,
-      textColor: getTheme().colors.onPrimary,
+      labelColor: getTheme().colors.onPrimary,
     });
   });
 });

From 333313395fade8170b04141b080afa52377e483e Mon Sep 17 00:00:00 2001
From: Aziz Becha <aziz07becha@gmail.com>
Date: Wed, 20 May 2026 18:56:37 +0100
Subject: [PATCH 16/24] fix(button): use outline and onSurfaceVariant for
 outlined mode

Align the outlined variant with the MD3 spec:
- border color: theme.colors.outline (was outlineVariant)
- label color: theme.colors.onSurfaceVariant (was primary)

text and elevated modes keep the primary accent; the selected-outlined tonal
branch is unchanged. Snapshot updates in Menu and DataTable reflect the same
outlined Button color change.
---
 src/components/Button/utils.tsx               | 10 ++++--
 src/components/__tests__/Button.test.tsx      | 34 +++++++++++++++----
 .../__snapshots__/Button.test.tsx.snap        |  4 +--
 .../__snapshots__/DataTable.test.tsx.snap     |  6 ++--
 .../__snapshots__/Menu.test.tsx.snap          | 12 +++----
 5 files changed, 47 insertions(+), 19 deletions(-)

diff --git a/src/components/Button/utils.tsx b/src/components/Button/utils.tsx
index 9fe95ac8d5..d7afda62ec 100644
--- a/src/components/Button/utils.tsx
+++ b/src/components/Button/utils.tsx
@@ -252,7 +252,13 @@ const getButtonLabelColor = ({
     }
   }
 
-  if (isMode('outlined') || isMode('text') || isMode('elevated')) {
+  // Outlined uses the neutral on-surface-variant label per MD3 spec; text and
+  // elevated keep the primary accent.
+  if (isMode('outlined')) {
+    return colors.onSurfaceVariant;
+  }
+
+  if (isMode('text') || isMode('elevated')) {
     return colors.primary;
   }
 
@@ -274,7 +280,7 @@ const getButtonBorderColor = ({ isMode, theme, selected }: BaseProps) => {
     return 'transparent';
   }
   if (isMode('outlined')) {
-    return theme.colors.outlineVariant;
+    return theme.colors.outline;
   }
 
   return 'transparent';
diff --git a/src/components/__tests__/Button.test.tsx b/src/components/__tests__/Button.test.tsx
index 858bff3a6a..4868c5ec66 100644
--- a/src/components/__tests__/Button.test.tsx
+++ b/src/components/__tests__/Button.test.tsx
@@ -662,7 +662,7 @@ describe('getButtonColors - text color', () => {
     })
   );
 
-  (['outlined', 'text', 'elevated'] as const).forEach((mode) =>
+  (['text', 'elevated'] as const).forEach((mode) =>
     it(`should return correct theme text color, for theme version 3, ${mode} mode`, () => {
       expect(
         getButtonColors({
@@ -675,7 +675,7 @@ describe('getButtonColors - text color', () => {
     })
   );
 
-  (['outlined', 'text', 'elevated'] as const).forEach((mode) =>
+  (['text', 'elevated'] as const).forEach((mode) =>
     it(`should return correct theme text color, for theme version 3, dark theme, ${mode} mode`, () => {
       expect(
         getButtonColors({
@@ -688,6 +688,28 @@ describe('getButtonColors - text color', () => {
     })
   );
 
+  it('should return onSurfaceVariant label color, for theme version 3, outlined mode', () => {
+    expect(
+      getButtonColors({
+        theme: getTheme(),
+        mode: 'outlined',
+      })
+    ).toMatchObject({
+      labelColor: getTheme().colors.onSurfaceVariant,
+    });
+  });
+
+  it('should return onSurfaceVariant label color, for theme version 3, dark theme, outlined mode', () => {
+    expect(
+      getButtonColors({
+        theme: getTheme(true),
+        mode: 'outlined',
+      })
+    ).toMatchObject({
+      labelColor: getTheme(true).colors.onSurfaceVariant,
+    });
+  });
+
   it('should return correct theme text color, for theme version 3, contained mode', () => {
     expect(
       getButtonColors({
@@ -742,7 +764,7 @@ describe('getButtonColors - border color', () => {
         mode: 'outlined',
       })
     ).toMatchObject({
-      borderColor: getTheme().colors.outlineVariant,
+      borderColor: getTheme().colors.outline,
     });
   });
 
@@ -754,7 +776,7 @@ describe('getButtonColors - border color', () => {
         mode: 'outlined',
       })
     ).toMatchObject({
-      borderColor: getTheme(true).colors.outlineVariant,
+      borderColor: getTheme(true).colors.outline,
     });
   });
 
@@ -765,7 +787,7 @@ describe('getButtonColors - border color', () => {
         mode: 'outlined',
       })
     ).toMatchObject({
-      borderColor: getTheme().colors.outlineVariant,
+      borderColor: getTheme().colors.outline,
     });
   });
 
@@ -776,7 +798,7 @@ describe('getButtonColors - border color', () => {
         mode: 'outlined',
       })
     ).toMatchObject({
-      borderColor: getTheme(true).colors.outlineVariant,
+      borderColor: getTheme(true).colors.outline,
     });
   });
 
diff --git a/src/components/__tests__/__snapshots__/Button.test.tsx.snap b/src/components/__tests__/__snapshots__/Button.test.tsx.snap
index 75e53412a5..58523dc4eb 100644
--- a/src/components/__tests__/__snapshots__/Button.test.tsx.snap
+++ b/src/components/__tests__/__snapshots__/Button.test.tsx.snap
@@ -1836,7 +1836,7 @@ exports[`renders outlined button with mode 1`] = `
     style={
       {
         "backgroundColor": "transparent",
-        "borderColor": "rgba(202, 196, 208, 1)",
+        "borderColor": "rgba(121, 116, 126, 1)",
         "borderRadius": 20,
         "borderStyle": "solid",
         "borderWidth": 1,
@@ -1945,7 +1945,7 @@ exports[`renders outlined button with mode 1`] = `
                   undefined,
                   false,
                   {
-                    "color": "rgba(103, 80, 164, 1)",
+                    "color": "rgba(73, 69, 79, 1)",
                     "fontFamily": "System",
                     "fontSize": 14,
                     "fontWeight": "500",
diff --git a/src/components/__tests__/__snapshots__/DataTable.test.tsx.snap b/src/components/__tests__/__snapshots__/DataTable.test.tsx.snap
index f486d1db3e..386c104861 100644
--- a/src/components/__tests__/__snapshots__/DataTable.test.tsx.snap
+++ b/src/components/__tests__/__snapshots__/DataTable.test.tsx.snap
@@ -1718,7 +1718,7 @@ exports[`DataTable.Pagination renders data table pagination with options select
           style={
             {
               "backgroundColor": "transparent",
-              "borderColor": "rgba(202, 196, 208, 1)",
+              "borderColor": "rgba(121, 116, 126, 1)",
               "borderRadius": 20,
               "borderStyle": "solid",
               "borderWidth": 1,
@@ -1814,7 +1814,7 @@ exports[`DataTable.Pagination renders data table pagination with options select
                   style={
                     [
                       {
-                        "color": "rgba(103, 80, 164, 1)",
+                        "color": "rgba(73, 69, 79, 1)",
                         "fontSize": 18,
                       },
                       [
@@ -1869,7 +1869,7 @@ exports[`DataTable.Pagination renders data table pagination with options select
                         undefined,
                         false,
                         {
-                          "color": "rgba(103, 80, 164, 1)",
+                          "color": "rgba(73, 69, 79, 1)",
                           "fontFamily": "System",
                           "fontSize": 14,
                           "fontWeight": "500",
diff --git a/src/components/__tests__/__snapshots__/Menu.test.tsx.snap b/src/components/__tests__/__snapshots__/Menu.test.tsx.snap
index 40aba65e7c..dae930daf6 100644
--- a/src/components/__tests__/__snapshots__/Menu.test.tsx.snap
+++ b/src/components/__tests__/__snapshots__/Menu.test.tsx.snap
@@ -36,7 +36,7 @@ exports[`renders menu with content styles 1`] = `
           style={
             {
               "backgroundColor": "transparent",
-              "borderColor": "rgba(202, 196, 208, 1)",
+              "borderColor": "rgba(121, 116, 126, 1)",
               "borderRadius": 20,
               "borderStyle": "solid",
               "borderWidth": 1,
@@ -145,7 +145,7 @@ exports[`renders menu with content styles 1`] = `
                         undefined,
                         false,
                         {
-                          "color": "rgba(103, 80, 164, 1)",
+                          "color": "rgba(73, 69, 79, 1)",
                           "fontFamily": "System",
                           "fontSize": 14,
                           "fontWeight": "500",
@@ -600,7 +600,7 @@ exports[`renders not visible menu 1`] = `
         style={
           {
             "backgroundColor": "transparent",
-            "borderColor": "rgba(202, 196, 208, 1)",
+            "borderColor": "rgba(121, 116, 126, 1)",
             "borderRadius": 20,
             "borderStyle": "solid",
             "borderWidth": 1,
@@ -709,7 +709,7 @@ exports[`renders not visible menu 1`] = `
                       undefined,
                       false,
                       {
-                        "color": "rgba(103, 80, 164, 1)",
+                        "color": "rgba(73, 69, 79, 1)",
                         "fontFamily": "System",
                         "fontSize": 14,
                         "fontWeight": "500",
@@ -769,7 +769,7 @@ exports[`renders visible menu 1`] = `
           style={
             {
               "backgroundColor": "transparent",
-              "borderColor": "rgba(202, 196, 208, 1)",
+              "borderColor": "rgba(121, 116, 126, 1)",
               "borderRadius": 20,
               "borderStyle": "solid",
               "borderWidth": 1,
@@ -878,7 +878,7 @@ exports[`renders visible menu 1`] = `
                         undefined,
                         false,
                         {
-                          "color": "rgba(103, 80, 164, 1)",
+                          "color": "rgba(73, 69, 79, 1)",
                           "fontFamily": "System",
                           "fontSize": 14,
                           "fontWeight": "500",

From 0e48531a482acfdb4fae4efd4dff7be82f6a1358 Mon Sep 17 00:00:00 2001
From: Aziz Becha <aziz07becha@gmail.com>
Date: Wed, 20 May 2026 19:03:10 +0100
Subject: [PATCH 17/24] fix(button): align legacy icon size, padding and icon
 gap to MD3 spec

For the legacy (no-`size`) button:
- icon size 18 -> 20dp
- horizontal padding 24 -> 16dp (legacyLabel marginHorizontal)
- keep the 8dp icon-label gap: the icon's negative margin is calibrated
  against the label margin, so the non-text icon margins go -16 -> -8 to
  compensate for the smaller label margin (otherwise the gap collapses to 0).

Snapshot updates in Menu and DataTable reflect the same legacy Button metrics.
---
 src/components/Button/Button.tsx              |  5 +-
 src/components/Button/utils.tsx               |  4 +-
 src/components/__tests__/Button.test.tsx      |  8 +--
 .../__snapshots__/Button.test.tsx.snap        | 68 +++++++++----------
 .../__snapshots__/DataTable.test.tsx.snap     |  8 +--
 .../__snapshots__/Menu.test.tsx.snap          |  6 +-
 6 files changed, 50 insertions(+), 49 deletions(-)

diff --git a/src/components/Button/Button.tsx b/src/components/Button/Button.tsx
index 3940702df8..1ccd05ef71 100644
--- a/src/components/Button/Button.tsx
+++ b/src/components/Button/Button.tsx
@@ -230,7 +230,8 @@ export type Props = $Omit<
 // level 2 while pressed.
 const initialElevation = 1;
 const activeElevation = 2;
-const iconSize = 18;
+// MD3 leading/trailing icon size for the legacy (no-`size`) button.
+const iconSize = 20;
 
 const Button = (
   {
@@ -625,7 +626,7 @@ const styles = StyleSheet.create({
   },
   legacyLabel: {
     marginVertical: 10,
-    marginHorizontal: 24,
+    marginHorizontal: 16,
   },
   legacyLabelText: {
     marginHorizontal: 12,
diff --git a/src/components/Button/utils.tsx b/src/components/Button/utils.tsx
index d7afda62ec..7948cb8207 100644
--- a/src/components/Button/utils.tsx
+++ b/src/components/Button/utils.tsx
@@ -137,7 +137,7 @@ export const getButtonIconStyle = ({
     }
     return isTextMode
       ? { marginLeft: -8, marginRight: 12 }
-      : { marginLeft: -16, marginRight: 16 };
+      : { marginLeft: -8, marginRight: 16 };
   }
 
   if (compact) {
@@ -145,7 +145,7 @@ export const getButtonIconStyle = ({
   }
   return isTextMode
     ? { marginLeft: 12, marginRight: -8 }
-    : { marginLeft: 16, marginRight: -16 };
+    : { marginLeft: 16, marginRight: -8 };
 };
 
 type BaseProps = {
diff --git a/src/components/__tests__/Button.test.tsx b/src/components/__tests__/Button.test.tsx
index 4868c5ec66..673a5eb5b1 100644
--- a/src/components/__tests__/Button.test.tsx
+++ b/src/components/__tests__/Button.test.tsx
@@ -383,7 +383,7 @@ describe('button icon styles', () => {
         );
         expect(getByTestId('compact-button-icon-container')).toHaveStyle({
           marginLeft: 16,
-          marginRight: -16,
+          marginRight: -8,
         });
       })
   );
@@ -397,7 +397,7 @@ describe('icon position', () => {
 
     expect(getByTestId('button-icon-container')).toHaveStyle({
       marginLeft: 16,
-      marginRight: -16,
+      marginRight: -8,
     });
   });
 
@@ -413,7 +413,7 @@ describe('icon position', () => {
     );
 
     expect(getByTestId('button-icon-container')).toHaveStyle({
-      marginLeft: -16,
+      marginLeft: -8,
       marginRight: 16,
     });
   });
@@ -431,7 +431,7 @@ describe('icon position', () => {
     );
 
     expect(getByTestId('button-icon-container')).toHaveStyle({
-      marginLeft: -16,
+      marginLeft: -8,
       marginRight: 16,
     });
     expect(warn).toHaveBeenCalledWith(
diff --git a/src/components/__tests__/__snapshots__/Button.test.tsx.snap b/src/components/__tests__/__snapshots__/Button.test.tsx.snap
index 58523dc4eb..0e37d57ae0 100644
--- a/src/components/__tests__/__snapshots__/Button.test.tsx.snap
+++ b/src/components/__tests__/__snapshots__/Button.test.tsx.snap
@@ -884,11 +884,11 @@ exports[`renders button with icon 1`] = `
               [
                 {
                   "color": "rgba(103, 80, 164, 1)",
-                  "fontSize": 18,
+                  "fontSize": 20,
                 },
                 [
                   {
-                    "lineHeight": 18,
+                    "lineHeight": 20,
                     "transform": [
                       {
                         "scaleX": 1,
@@ -1080,11 +1080,11 @@ exports[`renders button with icon in reverse order 1`] = `
               [
                 {
                   "color": "rgba(103, 80, 164, 1)",
-                  "fontSize": 18,
+                  "fontSize": 20,
                 },
                 [
                   {
-                    "lineHeight": 18,
+                    "lineHeight": 20,
                     "transform": [
                       {
                         "scaleX": 1,
@@ -1281,7 +1281,7 @@ exports[`renders contained contained with mode 1`] = `
                     "textAlign": "center",
                   },
                   {
-                    "marginHorizontal": 24,
+                    "marginHorizontal": 16,
                     "marginVertical": 10,
                   },
                   undefined,
@@ -1586,9 +1586,9 @@ exports[`renders loading button 1`] = `
             collapsable={false}
             style={
               {
-                "height": 18,
+                "height": 20,
                 "opacity": 1,
-                "width": 18,
+                "width": 20,
               }
             }
           >
@@ -1610,13 +1610,13 @@ exports[`renders loading button 1`] = `
                 collapsable={false}
                 style={
                   {
-                    "height": 18,
+                    "height": 20,
                     "transform": [
                       {
                         "rotate": "45deg",
                       },
                     ],
-                    "width": 18,
+                    "width": 20,
                   }
                 }
               >
@@ -1624,9 +1624,9 @@ exports[`renders loading button 1`] = `
                   collapsable={false}
                   style={
                     {
-                      "height": 9,
+                      "height": 10,
                       "overflow": "hidden",
-                      "width": 18,
+                      "width": 20,
                     }
                   }
                 >
@@ -1634,7 +1634,7 @@ exports[`renders loading button 1`] = `
                     collapsable={false}
                     style={
                       {
-                        "height": 18,
+                        "height": 20,
                         "transform": [
                           {
                             "translateY": 0,
@@ -1643,7 +1643,7 @@ exports[`renders loading button 1`] = `
                             "rotate": "-165deg",
                           },
                         ],
-                        "width": 18,
+                        "width": 20,
                       }
                     }
                   >
@@ -1651,9 +1651,9 @@ exports[`renders loading button 1`] = `
                       collapsable={false}
                       style={
                         {
-                          "height": 9,
+                          "height": 10,
                           "overflow": "hidden",
-                          "width": 18,
+                          "width": 20,
                         }
                       }
                     >
@@ -1662,10 +1662,10 @@ exports[`renders loading button 1`] = `
                         style={
                           {
                             "borderColor": "rgba(103, 80, 164, 1)",
-                            "borderRadius": 9,
-                            "borderWidth": 1.8,
-                            "height": 18,
-                            "width": 18,
+                            "borderRadius": 10,
+                            "borderWidth": 2,
+                            "height": 20,
+                            "width": 20,
                           }
                         }
                       />
@@ -1692,13 +1692,13 @@ exports[`renders loading button 1`] = `
                 collapsable={false}
                 style={
                   {
-                    "height": 18,
+                    "height": 20,
                     "transform": [
                       {
                         "rotate": "45deg",
                       },
                     ],
-                    "width": 18,
+                    "width": 20,
                   }
                 }
               >
@@ -1706,10 +1706,10 @@ exports[`renders loading button 1`] = `
                   collapsable={false}
                   style={
                     {
-                      "height": 9,
+                      "height": 10,
                       "overflow": "hidden",
-                      "top": 9,
-                      "width": 18,
+                      "top": 10,
+                      "width": 20,
                     }
                   }
                 >
@@ -1717,16 +1717,16 @@ exports[`renders loading button 1`] = `
                     collapsable={false}
                     style={
                       {
-                        "height": 18,
+                        "height": 20,
                         "transform": [
                           {
-                            "translateY": -9,
+                            "translateY": -10,
                           },
                           {
                             "rotate": "345deg",
                           },
                         ],
-                        "width": 18,
+                        "width": 20,
                       }
                     }
                   >
@@ -1734,9 +1734,9 @@ exports[`renders loading button 1`] = `
                       collapsable={false}
                       style={
                         {
-                          "height": 9,
+                          "height": 10,
                           "overflow": "hidden",
-                          "width": 18,
+                          "width": 20,
                         }
                       }
                     >
@@ -1745,10 +1745,10 @@ exports[`renders loading button 1`] = `
                         style={
                           {
                             "borderColor": "rgba(103, 80, 164, 1)",
-                            "borderRadius": 9,
-                            "borderWidth": 1.8,
-                            "height": 18,
-                            "width": 18,
+                            "borderRadius": 10,
+                            "borderWidth": 2,
+                            "height": 20,
+                            "width": 20,
                           }
                         }
                       />
@@ -1939,7 +1939,7 @@ exports[`renders outlined button with mode 1`] = `
                     "textAlign": "center",
                   },
                   {
-                    "marginHorizontal": 24,
+                    "marginHorizontal": 16,
                     "marginVertical": 10,
                   },
                   undefined,
diff --git a/src/components/__tests__/__snapshots__/DataTable.test.tsx.snap b/src/components/__tests__/__snapshots__/DataTable.test.tsx.snap
index 386c104861..765b144ed9 100644
--- a/src/components/__tests__/__snapshots__/DataTable.test.tsx.snap
+++ b/src/components/__tests__/__snapshots__/DataTable.test.tsx.snap
@@ -1800,7 +1800,7 @@ exports[`DataTable.Pagination renders data table pagination with options select
               <View
                 style={
                   {
-                    "marginLeft": -16,
+                    "marginLeft": -8,
                     "marginRight": 16,
                   }
                 }
@@ -1815,11 +1815,11 @@ exports[`DataTable.Pagination renders data table pagination with options select
                     [
                       {
                         "color": "rgba(73, 69, 79, 1)",
-                        "fontSize": 18,
+                        "fontSize": 20,
                       },
                       [
                         {
-                          "lineHeight": 18,
+                          "lineHeight": 20,
                           "transform": [
                             {
                               "scaleX": 1,
@@ -1863,7 +1863,7 @@ exports[`DataTable.Pagination renders data table pagination with options select
                           "textAlign": "center",
                         },
                         {
-                          "marginHorizontal": 24,
+                          "marginHorizontal": 16,
                           "marginVertical": 10,
                         },
                         undefined,
diff --git a/src/components/__tests__/__snapshots__/Menu.test.tsx.snap b/src/components/__tests__/__snapshots__/Menu.test.tsx.snap
index dae930daf6..f7e198784b 100644
--- a/src/components/__tests__/__snapshots__/Menu.test.tsx.snap
+++ b/src/components/__tests__/__snapshots__/Menu.test.tsx.snap
@@ -139,7 +139,7 @@ exports[`renders menu with content styles 1`] = `
                           "textAlign": "center",
                         },
                         {
-                          "marginHorizontal": 24,
+                          "marginHorizontal": 16,
                           "marginVertical": 10,
                         },
                         undefined,
@@ -703,7 +703,7 @@ exports[`renders not visible menu 1`] = `
                         "textAlign": "center",
                       },
                       {
-                        "marginHorizontal": 24,
+                        "marginHorizontal": 16,
                         "marginVertical": 10,
                       },
                       undefined,
@@ -872,7 +872,7 @@ exports[`renders visible menu 1`] = `
                           "textAlign": "center",
                         },
                         {
-                          "marginHorizontal": 24,
+                          "marginHorizontal": 16,
                           "marginVertical": 10,
                         },
                         undefined,

From 9927b3623d3debcdc54ea47221279b809b9089a2 Mon Sep 17 00:00:00 2001
From: Aziz Becha <aziz07becha@gmail.com>
Date: Wed, 20 May 2026 19:12:10 +0100
Subject: [PATCH 18/24] refactor(button): extract per-size component tokens

Add src/components/Button/tokens.ts with one token object per MD3 expressive
size (modelled on Jetpack Compose's Button{Size}Tokens), replacing the inline
BUTTON_SIZE_STYLES and BUTTON_SHAPE_RADIUS maps. Corner radii now reference
shape keys (full / medium / large / extraLarge) resolved against
theme.shapes.corner instead of magic numbers.

- getButtonSizeStyle derives from the tokens
- getButtonShapeRadius takes theme and resolves corner keys (resolveButtonCorner)
- fix extra-small iconSize 16 -> 20 per MD3 spec
- tokens also carry pressed/selected shape fields for the upcoming shape morph

No metric/radius change other than the extra-small icon size.
---
 src/components/Button/Button.tsx         |   2 +-
 src/components/Button/tokens.ts          | 115 +++++++++++++++++++++++
 src/components/Button/utils.tsx          |  99 ++++++++-----------
 src/components/__tests__/Button.test.tsx |  12 ++-
 4 files changed, 163 insertions(+), 65 deletions(-)
 create mode 100644 src/components/Button/tokens.ts

diff --git a/src/components/Button/Button.tsx b/src/components/Button/Button.tsx
index 1ccd05ef71..129a7365f1 100644
--- a/src/components/Button/Button.tsx
+++ b/src/components/Button/Button.tsx
@@ -382,7 +382,7 @@ const Button = (
       : shape
     : undefined;
   const borderRadius = effectiveShape
-    ? getButtonShapeRadius({ size, shape: effectiveShape })
+    ? getButtonShapeRadius({ size, shape: effectiveShape, theme })
     : theme.shapes.corner.largeIncreased;
 
   const {
diff --git a/src/components/Button/tokens.ts b/src/components/Button/tokens.ts
new file mode 100644
index 0000000000..5efd7ca8d8
--- /dev/null
+++ b/src/components/Button/tokens.ts
@@ -0,0 +1,115 @@
+import type { ButtonLabelVariant, ButtonSize } from './utils';
+
+/**
+ * Shape keys for the button container corners. `'full'` resolves to the
+ * full-pill radius (`cornerFull`); every other key resolves against
+ * `theme.shapes.corner[key]`. Mirrors MD3 `ShapeKeyTokens`.
+ */
+export type ButtonCornerKey =
+  | 'full'
+  | 'small'
+  | 'medium'
+  | 'large'
+  | 'extraLarge';
+
+/**
+ * Per-size component tokens for the Material Design 3 (expressive) button
+ * sizes, modelled on Jetpack Compose's `Button{Size}Tokens`. Centralising
+ * these here keeps every size-specific metric in one place and references the
+ * theme shape tokens instead of magic numbers for the corner radii.
+ */
+export type ButtonSizeTokens = {
+  containerHeight: number;
+  iconSize: number;
+  iconLabelSpace: number;
+  leadingSpace: number;
+  trailingSpace: number;
+  outlinedOutlineWidth: number;
+  labelVariant: ButtonLabelVariant;
+  containerShapeRound: ButtonCornerKey;
+  containerShapeSquare: ButtonCornerKey;
+  /** Corner the container morphs to while pressed (MD3: always `small`). */
+  pressedContainerShape: ButtonCornerKey;
+  selectedContainerShapeRound: ButtonCornerKey;
+  selectedContainerShapeSquare: ButtonCornerKey;
+};
+
+export const buttonSizeTokens: Record<ButtonSize, ButtonSizeTokens> = {
+  'extra-small': {
+    containerHeight: 32,
+    iconSize: 20,
+    iconLabelSpace: 4,
+    leadingSpace: 12,
+    trailingSpace: 12,
+    outlinedOutlineWidth: 1,
+    labelVariant: 'labelLarge',
+    containerShapeRound: 'full',
+    containerShapeSquare: 'medium',
+    pressedContainerShape: 'small',
+    selectedContainerShapeRound: 'full',
+    selectedContainerShapeSquare: 'medium',
+  },
+  small: {
+    containerHeight: 40,
+    iconSize: 20,
+    iconLabelSpace: 8,
+    leadingSpace: 16,
+    trailingSpace: 16,
+    outlinedOutlineWidth: 1,
+    labelVariant: 'labelLarge',
+    containerShapeRound: 'full',
+    containerShapeSquare: 'medium',
+    pressedContainerShape: 'small',
+    selectedContainerShapeRound: 'full',
+    selectedContainerShapeSquare: 'medium',
+  },
+  medium: {
+    containerHeight: 56,
+    iconSize: 24,
+    iconLabelSpace: 8,
+    leadingSpace: 24,
+    trailingSpace: 24,
+    outlinedOutlineWidth: 1,
+    labelVariant: 'titleMedium',
+    containerShapeRound: 'full',
+    containerShapeSquare: 'large',
+    pressedContainerShape: 'small',
+    selectedContainerShapeRound: 'full',
+    selectedContainerShapeSquare: 'large',
+  },
+  large: {
+    containerHeight: 96,
+    iconSize: 32,
+    iconLabelSpace: 12,
+    leadingSpace: 48,
+    trailingSpace: 48,
+    outlinedOutlineWidth: 1,
+    labelVariant: 'headlineSmall',
+    containerShapeRound: 'full',
+    containerShapeSquare: 'extraLarge',
+    pressedContainerShape: 'small',
+    selectedContainerShapeRound: 'full',
+    selectedContainerShapeSquare: 'extraLarge',
+  },
+  'extra-large': {
+    containerHeight: 136,
+    iconSize: 40,
+    iconLabelSpace: 16,
+    leadingSpace: 64,
+    trailingSpace: 64,
+    outlinedOutlineWidth: 1,
+    labelVariant: 'headlineLarge',
+    containerShapeRound: 'full',
+    containerShapeSquare: 'extraLarge',
+    pressedContainerShape: 'small',
+    selectedContainerShapeRound: 'full',
+    selectedContainerShapeSquare: 'extraLarge',
+  },
+};
+
+/** Corner used by the legacy (no-`size`) button for each shape variant. */
+export const legacyContainerShape: Record<'round' | 'square', ButtonCornerKey> =
+  {
+    round: 'full',
+    square: 'medium',
+  };
diff --git a/src/components/Button/utils.tsx b/src/components/Button/utils.tsx
index 7948cb8207..8047437e2b 100644
--- a/src/components/Button/utils.tsx
+++ b/src/components/Button/utils.tsx
@@ -2,6 +2,11 @@ import type { ColorValue, ViewStyle } from 'react-native';
 
 import color from 'color';
 
+import {
+  buttonSizeTokens,
+  legacyContainerShape,
+  type ButtonCornerKey,
+} from './tokens';
 import { black, white } from '../../theme/colors';
 import { tokens } from '../../theme/tokens';
 import { cornerFull } from '../../theme/tokens/sys/shape';
@@ -41,79 +46,55 @@ export type ButtonSizeStyle = {
 };
 
 /**
- * Per-size metrics for the Material Design 3 (expressive) button sizes.
- * Used when the `size` prop is explicitly set; if `size` is omitted, the
- * Button keeps its legacy visuals.
+ * Per-size metrics for the Material Design 3 (expressive) button sizes, read
+ * from the component tokens. Used when the `size` prop is explicitly set; if
+ * `size` is omitted, the Button keeps its legacy visuals.
  */
-const BUTTON_SIZE_STYLES: Record<ButtonSize, ButtonSizeStyle> = {
-  'extra-small': {
-    minHeight: 32,
-    paddingHorizontal: 12,
-    iconSize: 16,
-    iconGap: 4,
-    labelVariant: 'labelLarge',
-  },
-  small: {
-    minHeight: 40,
-    paddingHorizontal: 16,
-    iconSize: 20,
-    iconGap: 8,
-    labelVariant: 'labelLarge',
-  },
-  medium: {
-    minHeight: 56,
-    paddingHorizontal: 24,
-    iconSize: 24,
-    iconGap: 8,
-    labelVariant: 'titleMedium',
-  },
-  large: {
-    minHeight: 96,
-    paddingHorizontal: 48,
-    iconSize: 32,
-    iconGap: 12,
-    labelVariant: 'headlineSmall',
-  },
-  'extra-large': {
-    minHeight: 136,
-    paddingHorizontal: 64,
-    iconSize: 40,
-    iconGap: 16,
-    labelVariant: 'headlineLarge',
-  },
+export const getButtonSizeStyle = (size: ButtonSize): ButtonSizeStyle => {
+  const t = buttonSizeTokens[size];
+  return {
+    minHeight: t.containerHeight,
+    paddingHorizontal: t.leadingSpace,
+    iconSize: t.iconSize,
+    iconGap: t.iconLabelSpace,
+    labelVariant: t.labelVariant,
+  };
 };
 
-export const getButtonSizeStyle = (size: ButtonSize): ButtonSizeStyle =>
-  BUTTON_SIZE_STYLES[size];
-
 export type ButtonShape = 'round' | 'square';
 
 /**
- * Per-size corner radii for the Material Design 3 expressive shape variants.
- * `round` is always the full-pill radius; `square` uses a per-size smaller
- * corner. Used only when the `shape` prop is set on `Button`.
+ * Resolves a shape key against the theme: `'full'` is the full-pill radius;
+ * every other key maps to `theme.shapes.corner[key]`.
  */
-const BUTTON_SHAPE_RADIUS: Record<ButtonSize, Record<ButtonShape, number>> = {
-  'extra-small': { round: cornerFull, square: 12 },
-  small: { round: cornerFull, square: 12 },
-  medium: { round: cornerFull, square: 16 },
-  large: { round: cornerFull, square: 28 },
-  'extra-large': { round: cornerFull, square: 28 },
-};
-
-const DEFAULT_SHAPE_RADIUS: Record<ButtonShape, number> = {
-  round: cornerFull,
-  square: 12,
-};
+export const resolveButtonCorner = (
+  theme: InternalTheme,
+  key: ButtonCornerKey
+): number =>
+  key === 'full' ? cornerFull : (theme as Theme).shapes.corner[key];
 
+/**
+ * Corner radius for the requested shape, read from the component tokens and
+ * resolved against the theme shape tokens. `round` is the full-pill radius;
+ * `square` uses a per-size smaller corner. When `size` is omitted the legacy
+ * shape mapping is used.
+ */
 export const getButtonShapeRadius = ({
   size,
   shape,
+  theme,
 }: {
   size?: ButtonSize;
   shape: ButtonShape;
-}): number =>
-  size ? BUTTON_SHAPE_RADIUS[size][shape] : DEFAULT_SHAPE_RADIUS[shape];
+  theme: InternalTheme;
+}): number => {
+  const key = size
+    ? shape === 'round'
+      ? buttonSizeTokens[size].containerShapeRound
+      : buttonSizeTokens[size].containerShapeSquare
+    : legacyContainerShape[shape];
+  return resolveButtonCorner(theme, key);
+};
 
 /**
  * Returns the margins applied to the button's icon (or loading indicator)
diff --git a/src/components/__tests__/Button.test.tsx b/src/components/__tests__/Button.test.tsx
index 673a5eb5b1..e1f2893ff2 100644
--- a/src/components/__tests__/Button.test.tsx
+++ b/src/components/__tests__/Button.test.tsx
@@ -880,7 +880,7 @@ describe('getButtonRippleColor', () => {
 
 describe('getButtonSizeStyle', () => {
   it.each([
-    ['extra-small', 32, 12, 16, 4, 'labelLarge'],
+    ['extra-small', 32, 12, 20, 4, 'labelLarge'],
     ['small', 40, 16, 20, 8, 'labelLarge'],
     ['medium', 56, 24, 24, 8, 'titleMedium'],
     ['large', 96, 48, 32, 12, 'headlineSmall'],
@@ -936,13 +936,15 @@ describe('getButtonShapeRadius', () => {
     ['large', 9999, 28],
     ['extra-large', 9999, 28],
   ] as const)('returns expected radii for size=%s', (size, round, square) => {
-    expect(getButtonShapeRadius({ size, shape: 'round' })).toBe(round);
-    expect(getButtonShapeRadius({ size, shape: 'square' })).toBe(square);
+    const theme = getTheme();
+    expect(getButtonShapeRadius({ size, shape: 'round', theme })).toBe(round);
+    expect(getButtonShapeRadius({ size, shape: 'square', theme })).toBe(square);
   });
 
   it('falls back to default radii when size is omitted', () => {
-    expect(getButtonShapeRadius({ shape: 'round' })).toBe(9999);
-    expect(getButtonShapeRadius({ shape: 'square' })).toBe(12);
+    const theme = getTheme();
+    expect(getButtonShapeRadius({ shape: 'round', theme })).toBe(9999);
+    expect(getButtonShapeRadius({ shape: 'square', theme })).toBe(12);
   });
 });
 

From be5ff8c06540d20e1e429a7614ffa540867b79c8 Mon Sep 17 00:00:00 2001
From: Aziz Becha <aziz07becha@gmail.com>
Date: Wed, 20 May 2026 19:55:48 +0100
Subject: [PATCH 19/24] refactor(button)!: rename modes to filled and tonal

Align Button mode names with the MD3 spec. This is a breaking rename (no
aliases), matching the v6 breaking-change window:
- contained -> filled
- contained-tonal -> tonal

The resolved styles are unchanged, so there is no visual difference. Updates
the Button mode type, internal isMode checks, CardActions' injected default,
and all consumers (example, docs, tests). Card/IconButton/SegmentedButtons/
ToggleButton keep their own independent contained modes.
---
 docs/src/components/BannerExample.tsx         |   9 +-
 docs/src/components/GetStartedButtons.tsx     |   2 +-
 example/src/Examples/ButtonExample.tsx        |  72 ++++---
 src/components/Button/Button.tsx              |  18 +-
 src/components/Button/utils.tsx               |  25 +--
 src/components/Card/CardActions.tsx           |   3 +-
 src/components/__tests__/Button.test.tsx      | 179 +++++++++---------
 src/components/__tests__/Card/Card.test.tsx   |   6 +-
 .../__snapshots__/Button.test.tsx.snap        |  30 +--
 9 files changed, 158 insertions(+), 186 deletions(-)

diff --git a/docs/src/components/BannerExample.tsx b/docs/src/components/BannerExample.tsx
index 0bae591bac..c5d0c7df09 100644
--- a/docs/src/components/BannerExample.tsx
+++ b/docs/src/components/BannerExample.tsx
@@ -75,15 +75,10 @@ const BannerExample = () => {
       <Stack spacing={16}>
         <Stack direction="row" spacing={8} style={styles.row}>
           <Button loading onPress={() => {}} label="Loading" />
+          <Button mode="tonal" icon="camera" onPress={() => {}} label="Icon" />
           <Button
-            mode="contained-tonal"
             icon="camera"
-            onPress={() => {}}
-            label="Icon"
-          />
-          <Button
-            icon="camera"
-            mode="contained"
+            mode="filled"
             onPress={() => {}}
             label="Press me"
           />
diff --git a/docs/src/components/GetStartedButtons.tsx b/docs/src/components/GetStartedButtons.tsx
index 906c51be13..72aef205ab 100644
--- a/docs/src/components/GetStartedButtons.tsx
+++ b/docs/src/components/GetStartedButtons.tsx
@@ -37,7 +37,7 @@ const GetStartedButton = () => {
     <View style={styles.container}>
       <Link to="/docs/guides/getting-started" style={noTextDecoration}>
         <Button
-          mode="contained"
+          mode="filled"
           style={styles.button}
           onPress={noop}
           label="Get started"
diff --git a/example/src/Examples/ButtonExample.tsx b/example/src/Examples/ButtonExample.tsx
index 4636afd557..c61426f96d 100644
--- a/example/src/Examples/ButtonExample.tsx
+++ b/example/src/Examples/ButtonExample.tsx
@@ -58,41 +58,41 @@ const ButtonExample = () => {
       <List.Section title="Contained-tonal button (tonal)">
         <View style={styles.row}>
           <Button
-            mode="contained-tonal"
+            mode="tonal"
             onPress={() => {}}
             style={styles.button}
             label="Default"
           />
           <Button
-            mode="contained-tonal"
+            mode="tonal"
             buttonColor={color}
             onPress={() => {}}
             style={styles.button}
             label="Custom"
           />
           <Button
-            mode="contained-tonal"
+            mode="tonal"
             disabled
             onPress={() => {}}
             style={styles.button}
             label="Disabled"
           />
           <Button
-            mode="contained-tonal"
+            mode="tonal"
             icon="camera"
             onPress={() => {}}
             style={styles.button}
             label="Icon"
           />
           <Button
-            mode="contained-tonal"
+            mode="tonal"
             loading
             onPress={() => {}}
             style={styles.button}
             label="Loading"
           />
           <Button
-            mode="contained-tonal"
+            mode="tonal"
             icon="camera"
             onPress={() => {}}
             style={styles.button}
@@ -150,41 +150,41 @@ const ButtonExample = () => {
       <List.Section title="Contained button (filled)">
         <View style={styles.row}>
           <Button
-            mode="contained"
+            mode="filled"
             onPress={() => {}}
             style={styles.button}
             label="Default"
           />
           <Button
-            mode="contained"
+            mode="filled"
             buttonColor={color}
             onPress={() => {}}
             style={styles.button}
             label="Custom"
           />
           <Button
-            mode="contained"
+            mode="filled"
             disabled
             onPress={() => {}}
             style={styles.button}
             label="Disabled"
           />
           <Button
-            mode="contained"
+            mode="filled"
             icon="camera"
             onPress={() => {}}
             style={styles.button}
             label="Icon"
           />
           <Button
-            mode="contained"
+            mode="filled"
             loading
             onPress={() => {}}
             style={styles.button}
             label="Loading"
           />
           <Button
-            mode="contained"
+            mode="filled"
             icon="camera"
             onPress={() => {}}
             style={styles.button}
@@ -292,13 +292,13 @@ const ButtonExample = () => {
             label="Custom radius"
           />
           <Button
-            mode="contained"
+            mode="filled"
             onPress={() => {}}
             style={styles.noRadius}
             label="Without radius"
           />
           <Button
-            mode="contained-tonal"
+            mode="tonal"
             onPress={() => {}}
             style={{ borderRadius: styles.customRadiusAndPadding.borderRadius }}
             contentStyle={styles.customRadiusAndPadding}
@@ -308,7 +308,7 @@ const ButtonExample = () => {
 
         <View style={styles.row}>
           <Button
-            mode="contained"
+            mode="filled"
             onPress={() => {}}
             style={styles.flexGrow1Button}
             label="flex-grow: 1"
@@ -316,7 +316,7 @@ const ButtonExample = () => {
         </View>
         <View style={styles.row}>
           <Button
-            mode="contained"
+            mode="filled"
             onPress={() => {}}
             style={styles.width100PercentButton}
             label="width: 100%"
@@ -325,27 +325,21 @@ const ButtonExample = () => {
       </List.Section>
       <List.Section title="Compact">
         <View style={styles.row}>
-          {(
-            [
-              'text',
-              'outlined',
-              'contained',
-              'elevated',
-              'contained-tonal',
-            ] as const
-          ).map((mode) => {
-            return (
-              <Button
-                key={mode}
-                mode={mode}
-                compact
-                onPress={() => {}}
-                style={styles.button}
-                icon="camera"
-                label={`Compact ${mode}`}
-              />
-            );
-          })}
+          {(['text', 'outlined', 'filled', 'elevated', 'tonal'] as const).map(
+            (mode) => {
+              return (
+                <Button
+                  key={mode}
+                  mode={mode}
+                  compact
+                  onPress={() => {}}
+                  style={styles.button}
+                  icon="camera"
+                  label={`Compact ${mode}`}
+                />
+              );
+            }
+          )}
         </View>
       </List.Section>
       <List.Section title="Size (expressive)">
@@ -355,7 +349,7 @@ const ButtonExample = () => {
           ).map((size) => (
             <Button
               key={size}
-              mode="contained"
+              mode="filled"
               size={size}
               icon="star"
               onPress={() => {}}
@@ -399,7 +393,7 @@ const ButtonExample = () => {
       </List.Section>
       <List.Section title="Toggle (expressive)">
         <View style={styles.row}>
-          {(['outlined', 'text', 'contained-tonal'] as const).map((mode) => {
+          {(['outlined', 'text', 'tonal'] as const).map((mode) => {
             const key = `toggle-${mode}`;
             const selected = !!selectedToggles[key];
             return (
diff --git a/src/components/Button/Button.tsx b/src/components/Button/Button.tsx
index 129a7365f1..7c6ce132bf 100644
--- a/src/components/Button/Button.tsx
+++ b/src/components/Button/Button.tsx
@@ -44,17 +44,15 @@ export type Props = $Omit<
 > & {
   /**
    * Mode of the button. You can change the mode to adjust the styling to give it desired emphasis.
-   * - `text` - flat button without background or outline, used for the lowest priority actions, especially when presenting multiple options.
+   * - `filled` - button with a background color, used for the most important action, has the most visual impact and high emphasis.
+   * - `tonal` - button with a secondary background color, an alternative middle ground between filled and outlined buttons.
+   * - `elevated` - button with a background color and elevation, used when absolutely necessary e.g. button requires visual separation from a patterned background.
    * - `outlined` - button with an outline without background, typically used for important, but not primary action – represents medium emphasis.
-   * - `contained` - button with a background color, used for important action, have the most visual impact and high emphasis.
-   * - `elevated` - button with a background color and elevation, used when absolutely necessary e.g. button requires visual separation from a patterned background. @supported Available in v5.x with theme version 3
-   * - `contained-tonal` - button with a secondary background color, an alternative middle ground between contained and outlined buttons. @supported Available in v5.x with theme version 3
+   * - `text` - flat button without background or outline, used for the lowest priority actions, especially when presenting multiple options.
    */
-  mode?: 'text' | 'outlined' | 'contained' | 'elevated' | 'contained-tonal';
+  mode?: 'text' | 'outlined' | 'filled' | 'elevated' | 'tonal';
   /**
-   * Whether the color is a dark color. A dark button will render light text and vice-versa. Only applicable for:
-   *  * `contained` mode for theme version 2
-   *  * `contained`, `contained-tonal` and `elevated` modes for theme version 3.
+   * Whether the color is a dark color. A dark button will render light text and vice-versa. Only applicable for the `filled`, `tonal` and `elevated` modes.
    */
   dark?: boolean;
   /**
@@ -84,7 +82,7 @@ export type Props = $Omit<
    *
    * - The `shape` is flipped: `'round'` becomes `'square'` and vice versa.
    * - For `outlined` and `text` modes, the button adopts a filled
-   *   `secondaryContainer` appearance (matches `contained-tonal`).
+   *   `secondaryContainer` appearance (matches `tonal`).
    * - `accessibilityState.selected` is set so screen readers announce the
    *   toggle state.
    *
@@ -216,7 +214,7 @@ export type Props = $Omit<
  * const MyComponent = () => (
  *   <Button
  *     icon="camera"
- *     mode="contained"
+ *     mode="filled"
  *     onPress={() => console.log('Pressed')}
  *     label="Press me"
  *   />
diff --git a/src/components/Button/utils.tsx b/src/components/Button/utils.tsx
index 8047437e2b..46f9704580 100644
--- a/src/components/Button/utils.tsx
+++ b/src/components/Button/utils.tsx
@@ -15,12 +15,7 @@ import { splitStyles } from '../../utils/splitStyles';
 
 const { stateOpacity } = tokens.md.ref;
 
-export type ButtonMode =
-  | 'text'
-  | 'outlined'
-  | 'contained'
-  | 'elevated'
-  | 'contained-tonal';
+export type ButtonMode = 'text' | 'outlined' | 'filled' | 'elevated' | 'tonal';
 
 export type ButtonIconPosition = 'leading' | 'trailing';
 
@@ -176,7 +171,7 @@ const getButtonBackgroundColor = ({
   }
 
   // Selected toggle (only outlined/text adopt a filled "tonal-selected" look;
-  // contained / contained-tonal / elevated already render filled).
+  // filled / tonal / elevated already render filled).
   if (selected && (isMode('outlined') || isMode('text'))) {
     return colors.secondaryContainer;
   }
@@ -185,11 +180,11 @@ const getButtonBackgroundColor = ({
     return colors.surfaceContainerLow;
   }
 
-  if (isMode('contained')) {
+  if (isMode('filled')) {
     return colors.primary;
   }
 
-  if (isMode('contained-tonal')) {
+  if (isMode('tonal')) {
     return colors.secondaryContainer;
   }
 
@@ -218,17 +213,13 @@ const getButtonLabelColor = ({
     return theme.colors.onSurface;
   }
 
-  // Selected toggle for outlined/text mirrors the contained-tonal label color.
+  // Selected toggle for outlined/text mirrors the tonal label color.
   if (selected && (isMode('outlined') || isMode('text'))) {
     return colors.onSecondaryContainer;
   }
 
   if (typeof dark === 'boolean') {
-    if (
-      isMode('contained') ||
-      isMode('contained-tonal') ||
-      isMode('elevated')
-    ) {
+    if (isMode('filled') || isMode('tonal') || isMode('elevated')) {
       return isDark({ dark, backgroundColor }) ? white : black;
     }
   }
@@ -243,11 +234,11 @@ const getButtonLabelColor = ({
     return colors.primary;
   }
 
-  if (isMode('contained')) {
+  if (isMode('filled')) {
     return colors.onPrimary;
   }
 
-  if (isMode('contained-tonal')) {
+  if (isMode('tonal')) {
     return colors.onSecondaryContainer;
   }
 
diff --git a/src/components/Card/CardActions.tsx b/src/components/Card/CardActions.tsx
index cee98b6f0d..a795619483 100644
--- a/src/components/Card/CardActions.tsx
+++ b/src/components/Card/CardActions.tsx
@@ -48,8 +48,7 @@ const CardActions = ({ theme, style, children, ...rest }: Props) => {
         }
 
         const compact = child.props.compact;
-        const mode =
-          child.props.mode ?? (index === 0 ? 'outlined' : 'contained');
+        const mode = child.props.mode ?? (index === 0 ? 'outlined' : 'filled');
         const childStyle = [styles.button, child.props.style];
 
         return React.cloneElement(child, {
diff --git a/src/components/__tests__/Button.test.tsx b/src/components/__tests__/Button.test.tsx
index e1f2893ff2..b749aec462 100644
--- a/src/components/__tests__/Button.test.tsx
+++ b/src/components/__tests__/Button.test.tsx
@@ -57,9 +57,9 @@ it('renders outlined button with mode', () => {
   expect(tree).toMatchSnapshot();
 });
 
-it('renders contained contained with mode', () => {
+it('renders filled button with mode', () => {
   const tree = render(
-    <Button mode="contained" label="Contained Button" />
+    <Button mode="filled" label="Contained Button" />
   ).toJSON();
 
   expect(tree).toMatchSnapshot();
@@ -336,23 +336,22 @@ describe('button icon styles', () => {
     });
   });
 
-  (['outlined', 'contained', 'contained-tonal', 'elevated'] as const).forEach(
-    (mode) =>
-      it(`should return correct icon styles for compact ${mode} button`, () => {
-        const { getByTestId } = render(
-          <Button
-            mode={mode}
-            compact
-            icon="camera"
-            testID="compact-button"
-            label={`Compact ${mode} button`}
-          />
-        );
-        expect(getByTestId('compact-button-icon-container')).toHaveStyle({
-          marginLeft: 8,
-          marginRight: 0,
-        });
-      })
+  (['outlined', 'filled', 'tonal', 'elevated'] as const).forEach((mode) =>
+    it(`should return correct icon styles for compact ${mode} button`, () => {
+      const { getByTestId } = render(
+        <Button
+          mode={mode}
+          compact
+          icon="camera"
+          testID="compact-button"
+          label={`Compact ${mode} button`}
+        />
+      );
+      expect(getByTestId('compact-button-icon-container')).toHaveStyle({
+        marginLeft: 8,
+        marginRight: 0,
+      });
+    })
   );
 
   it('should return correct icon styles for text button', () => {
@@ -370,22 +369,21 @@ describe('button icon styles', () => {
     });
   });
 
-  (['outlined', 'contained', 'contained-tonal', 'elevated'] as const).forEach(
-    (mode) =>
-      it(`should return correct icon styles for compact ${mode} button`, () => {
-        const { getByTestId } = render(
-          <Button
-            mode={mode}
-            icon="camera"
-            testID="compact-button"
-            label={`${mode} button`}
-          />
-        );
-        expect(getByTestId('compact-button-icon-container')).toHaveStyle({
-          marginLeft: 16,
-          marginRight: -8,
-        });
-      })
+  (['outlined', 'filled', 'tonal', 'elevated'] as const).forEach((mode) =>
+    it(`should return correct icon styles for compact ${mode} button`, () => {
+      const { getByTestId } = render(
+        <Button
+          mode={mode}
+          icon="camera"
+          testID="compact-button"
+          label={`${mode} button`}
+        />
+      );
+      expect(getByTestId('compact-button-icon-container')).toHaveStyle({
+        marginLeft: 16,
+        marginRight: -8,
+      });
+    })
   );
 });
 
@@ -481,7 +479,7 @@ describe('getButtonColors - background color', () => {
     })
   );
 
-  (['contained', 'contained-tonal', 'elevated'] as const).forEach((mode) =>
+  (['filled', 'tonal', 'elevated'] as const).forEach((mode) =>
     it(`should return correct disabled color, for theme version 3, ${mode} mode`, () => {
       return expect(
         getButtonColors({
@@ -497,7 +495,7 @@ describe('getButtonColors - background color', () => {
     })
   );
 
-  (['contained', 'contained-tonal', 'elevated'] as const).forEach((mode) =>
+  (['filled', 'tonal', 'elevated'] as const).forEach((mode) =>
     it(`should return correct disabled color, for theme version 3, dark theme, ${mode} mode`, () => {
       return expect(
         getButtonColors({
@@ -535,44 +533,44 @@ describe('getButtonColors - background color', () => {
     });
   });
 
-  it('should return correct theme color, for theme version 3, contained mode', () => {
+  it('should return correct theme color, for theme version 3, filled mode', () => {
     expect(
       getButtonColors({
         theme: getTheme(),
-        mode: 'contained',
+        mode: 'filled',
       })
     ).toMatchObject({
       backgroundColor: getTheme().colors.primary,
     });
   });
 
-  it('should return correct theme color, for theme version 3, dark theme, contained mode', () => {
+  it('should return correct theme color, for theme version 3, dark theme, filled mode', () => {
     expect(
       getButtonColors({
         theme: getTheme(true),
-        mode: 'contained',
+        mode: 'filled',
       })
     ).toMatchObject({
       backgroundColor: getTheme(true).colors.primary,
     });
   });
 
-  it('should return correct theme color, for theme version 3, contained-tonal mode', () => {
+  it('should return correct theme color, for theme version 3, tonal mode', () => {
     expect(
       getButtonColors({
         theme: getTheme(),
-        mode: 'contained-tonal',
+        mode: 'tonal',
       })
     ).toMatchObject({
       backgroundColor: getTheme().colors.secondaryContainer,
     });
   });
 
-  it('should return correct theme color, for theme version 3, dark theme, contained-tonal mode', () => {
+  it('should return correct theme color, for theme version 3, dark theme, tonal mode', () => {
     expect(
       getButtonColors({
         theme: getTheme(true),
-        mode: 'contained-tonal',
+        mode: 'tonal',
       })
     ).toMatchObject({
       backgroundColor: getTheme(true).colors.secondaryContainer,
@@ -648,7 +646,7 @@ describe('getButtonColors - text color', () => {
     });
   });
 
-  (['contained', 'contained-tonal', 'elevated'] as const).forEach((mode) =>
+  (['filled', 'tonal', 'elevated'] as const).forEach((mode) =>
     it(`should return correct text color for dark prop, for theme version 3, ${mode} mode`, () => {
       expect(
         getButtonColors({
@@ -710,44 +708,44 @@ describe('getButtonColors - text color', () => {
     });
   });
 
-  it('should return correct theme text color, for theme version 3, contained mode', () => {
+  it('should return correct theme text color, for theme version 3, filled mode', () => {
     expect(
       getButtonColors({
         theme: getTheme(),
-        mode: 'contained',
+        mode: 'filled',
       })
     ).toMatchObject({
       labelColor: getTheme().colors.onPrimary,
     });
   });
 
-  it('should return correct theme text color, for theme version 3, dark theme, contained mode', () => {
+  it('should return correct theme text color, for theme version 3, dark theme, filled mode', () => {
     expect(
       getButtonColors({
         theme: getTheme(true),
-        mode: 'contained',
+        mode: 'filled',
       })
     ).toMatchObject({
       labelColor: getTheme(true).colors.onPrimary,
     });
   });
 
-  it('should return correct theme text color, for theme version 3, contained-tonal mode', () => {
+  it('should return correct theme text color, for theme version 3, tonal mode', () => {
     expect(
       getButtonColors({
         theme: getTheme(),
-        mode: 'contained-tonal',
+        mode: 'tonal',
       })
     ).toMatchObject({
       labelColor: getTheme().colors.onSecondaryContainer,
     });
   });
 
-  it('should return correct theme text color, for theme version 3, dark theme contained-tonal mode', () => {
+  it('should return correct theme text color, for theme version 3, dark theme tonal mode', () => {
     expect(
       getButtonColors({
         theme: getTheme(true),
-        mode: 'contained-tonal',
+        mode: 'tonal',
       })
     ).toMatchObject({
       labelColor: getTheme(true).colors.onSecondaryContainer,
@@ -802,32 +800,30 @@ describe('getButtonColors - border color', () => {
     });
   });
 
-  (['text', 'contained', 'contained-tonal', 'elevated'] as const).forEach(
-    (mode) =>
-      it(`should return transparent border, for theme version 3, ${mode} mode`, () => {
-        expect(
-          getButtonColors({
-            theme: getTheme(),
-            mode,
-          })
-        ).toMatchObject({
-          borderColor: 'transparent',
-        });
-      })
+  (['text', 'filled', 'tonal', 'elevated'] as const).forEach((mode) =>
+    it(`should return transparent border, for theme version 3, ${mode} mode`, () => {
+      expect(
+        getButtonColors({
+          theme: getTheme(),
+          mode,
+        })
+      ).toMatchObject({
+        borderColor: 'transparent',
+      });
+    })
   );
 
-  (['text', 'contained', 'contained-tonal', 'elevated'] as const).forEach(
-    (mode) =>
-      it(`should return transparent border, for theme version 3, dark theme, ${mode} mode`, () => {
-        expect(
-          getButtonColors({
-            theme: getTheme(true),
-            mode,
-          })
-        ).toMatchObject({
-          borderColor: 'transparent',
-        });
-      })
+  (['text', 'filled', 'tonal', 'elevated'] as const).forEach((mode) =>
+    it(`should return transparent border, for theme version 3, dark theme, ${mode} mode`, () => {
+      expect(
+        getButtonColors({
+          theme: getTheme(true),
+          mode,
+        })
+      ).toMatchObject({
+        borderColor: 'transparent',
+      });
+    })
   );
 });
 
@@ -843,18 +839,17 @@ describe('getButtonColors - border width', () => {
     });
   });
 
-  (['text', 'contained', 'contained-tonal', 'elevated'] as const).forEach(
-    (mode) =>
-      it(`should return correct border width, for ${mode} mode`, () => {
-        expect(
-          getButtonColors({
-            theme: getTheme(),
-            mode,
-          })
-        ).toMatchObject({
-          borderWidth: 0,
-        });
-      })
+  (['text', 'filled', 'tonal', 'elevated'] as const).forEach((mode) =>
+    it(`should return correct border width, for ${mode} mode`, () => {
+      expect(
+        getButtonColors({
+          theme: getTheme(),
+          mode,
+        })
+      ).toMatchObject({
+        borderWidth: 0,
+      });
+    })
   );
 });
 
@@ -1038,11 +1033,11 @@ describe('selected prop', () => {
     });
   });
 
-  it('does not change contained colors when selected', () => {
+  it('does not change filled colors when selected', () => {
     expect(
       getButtonColors({
         theme: getTheme(),
-        mode: 'contained',
+        mode: 'filled',
         selected: true,
       })
     ).toMatchObject({
diff --git a/src/components/__tests__/Card/Card.test.tsx b/src/components/__tests__/Card/Card.test.tsx
index 95cebf98ec..5439e4148d 100644
--- a/src/components/__tests__/Card/Card.test.tsx
+++ b/src/components/__tests__/Card/Card.test.tsx
@@ -132,13 +132,13 @@ describe('CardActions', () => {
     const { getByTestId } = render(
       <Card>
         <Card.Actions testID="card-actions">
-          <Button mode="contained" label="Agree" />
+          <Button mode="filled" label="Agree" />
         </Card.Actions>
       </Card>
     );
 
     expect(getByTestId('card-actions').props.children[0].props.mode).toBe(
-      'contained'
+      'filled'
     );
   });
 
@@ -148,7 +148,7 @@ describe('CardActions', () => {
         <Card.Actions>
           <Button
             testID="card-actions-button"
-            mode="contained"
+            mode="filled"
             style={styles.customBorderRadius}
             label="Agree"
           />
diff --git a/src/components/__tests__/__snapshots__/Button.test.tsx.snap b/src/components/__tests__/__snapshots__/Button.test.tsx.snap
index 0e37d57ae0..af65c09444 100644
--- a/src/components/__tests__/__snapshots__/Button.test.tsx.snap
+++ b/src/components/__tests__/__snapshots__/Button.test.tsx.snap
@@ -1155,12 +1155,12 @@ exports[`renders button with icon in reverse order 1`] = `
 </View>
 `;
 
-exports[`renders contained contained with mode 1`] = `
+exports[`renders disabled button 1`] = `
 <View
   collapsable={false}
   style={
     {
-      "backgroundColor": "rgba(103, 80, 164, 1)",
+      "backgroundColor": "transparent",
       "borderRadius": 20,
       "shadowColor": "rgba(0, 0, 0, 1)",
       "shadowOffset": {
@@ -1177,7 +1177,7 @@ exports[`renders contained contained with mode 1`] = `
     collapsable={false}
     style={
       {
-        "backgroundColor": "rgba(103, 80, 164, 1)",
+        "backgroundColor": "transparent",
         "borderColor": "transparent",
         "borderRadius": 20,
         "borderStyle": "solid",
@@ -1248,7 +1248,7 @@ exports[`renders contained contained with mode 1`] = `
             },
             false,
             {
-              "opacity": 1,
+              "opacity": 0.38,
             },
             undefined,
           ]
@@ -1281,13 +1281,12 @@ exports[`renders contained contained with mode 1`] = `
                     "textAlign": "center",
                   },
                   {
-                    "marginHorizontal": 16,
-                    "marginVertical": 10,
+                    "marginHorizontal": 12,
                   },
                   undefined,
                   false,
                   {
-                    "color": "rgba(255, 255, 255, 1)",
+                    "color": "rgba(29, 27, 32, 1)",
                     "fontFamily": "System",
                     "fontSize": 14,
                     "fontWeight": "500",
@@ -1301,7 +1300,7 @@ exports[`renders contained contained with mode 1`] = `
           }
           testID="button-text"
         >
-          Contained Button
+          Disabled Button
         </Text>
       </View>
     </View>
@@ -1309,12 +1308,12 @@ exports[`renders contained contained with mode 1`] = `
 </View>
 `;
 
-exports[`renders disabled button 1`] = `
+exports[`renders filled button with mode 1`] = `
 <View
   collapsable={false}
   style={
     {
-      "backgroundColor": "transparent",
+      "backgroundColor": "rgba(103, 80, 164, 1)",
       "borderRadius": 20,
       "shadowColor": "rgba(0, 0, 0, 1)",
       "shadowOffset": {
@@ -1331,7 +1330,7 @@ exports[`renders disabled button 1`] = `
     collapsable={false}
     style={
       {
-        "backgroundColor": "transparent",
+        "backgroundColor": "rgba(103, 80, 164, 1)",
         "borderColor": "transparent",
         "borderRadius": 20,
         "borderStyle": "solid",
@@ -1402,7 +1401,7 @@ exports[`renders disabled button 1`] = `
             },
             false,
             {
-              "opacity": 0.38,
+              "opacity": 1,
             },
             undefined,
           ]
@@ -1435,12 +1434,13 @@ exports[`renders disabled button 1`] = `
                     "textAlign": "center",
                   },
                   {
-                    "marginHorizontal": 12,
+                    "marginHorizontal": 16,
+                    "marginVertical": 10,
                   },
                   undefined,
                   false,
                   {
-                    "color": "rgba(29, 27, 32, 1)",
+                    "color": "rgba(255, 255, 255, 1)",
                     "fontFamily": "System",
                     "fontSize": 14,
                     "fontWeight": "500",
@@ -1454,7 +1454,7 @@ exports[`renders disabled button 1`] = `
           }
           testID="button-text"
         >
-          Disabled Button
+          Contained Button
         </Text>
       </View>
     </View>

From f734941be86a8cd00d8ed93d218320cbd24fc044 Mon Sep 17 00:00:00 2001
From: Aziz Becha <aziz07becha@gmail.com>
Date: Wed, 20 May 2026 20:03:15 +0100
Subject: [PATCH 20/24] refactor(button)!: default mode is now filled

Change the default Button mode from text to filled to match the MD3 emphasis
hierarchy (filled is the highest-emphasis, primary button). A bare <Button>
now renders filled instead of text.

All library-internal usages pass an explicit mode, so none are affected.
Snapshots updated for bare buttons (transparent -> primary background,
primary -> onPrimary label).
---
 src/components/Button/Button.tsx              |   6 +-
 src/components/__tests__/Button.test.tsx      |   4 +-
 .../__snapshots__/Button.test.tsx.snap        | 411 ++++++++++--------
 3 files changed, 225 insertions(+), 196 deletions(-)

diff --git a/src/components/Button/Button.tsx b/src/components/Button/Button.tsx
index 7c6ce132bf..bc0efa49ff 100644
--- a/src/components/Button/Button.tsx
+++ b/src/components/Button/Button.tsx
@@ -43,8 +43,8 @@ export type Props = $Omit<
   'mode' | 'children'
 > & {
   /**
-   * Mode of the button. You can change the mode to adjust the styling to give it desired emphasis.
-   * - `filled` - button with a background color, used for the most important action, has the most visual impact and high emphasis.
+   * Mode of the button. You can change the mode to adjust the styling to give it desired emphasis. Defaults to `filled`.
+   * - `filled` - button with a background color, used for the most important action, has the most visual impact and high emphasis. (default)
    * - `tonal` - button with a secondary background color, an alternative middle ground between filled and outlined buttons.
    * - `elevated` - button with a background color and elevation, used when absolutely necessary e.g. button requires visual separation from a patterned background.
    * - `outlined` - button with an outline without background, typically used for important, but not primary action – represents medium emphasis.
@@ -235,7 +235,7 @@ const Button = (
   {
     disabled,
     compact,
-    mode = 'text',
+    mode = 'filled',
     size,
     shape,
     selected,
diff --git a/src/components/__tests__/Button.test.tsx b/src/components/__tests__/Button.test.tsx
index b749aec462..464cbbb99d 100644
--- a/src/components/__tests__/Button.test.tsx
+++ b/src/components/__tests__/Button.test.tsx
@@ -37,8 +37,8 @@ const styles = StyleSheet.create({
   },
 });
 
-it('renders text button by default', () => {
-  const tree = render(<Button label="Text Button" />).toJSON();
+it('renders filled button by default', () => {
+  const tree = render(<Button label="Filled Button" />).toJSON();
 
   expect(tree).toMatchSnapshot();
 });
diff --git a/src/components/__tests__/__snapshots__/Button.test.tsx.snap b/src/components/__tests__/__snapshots__/Button.test.tsx.snap
index af65c09444..1d96d9a7db 100644
--- a/src/components/__tests__/__snapshots__/Button.test.tsx.snap
+++ b/src/components/__tests__/__snapshots__/Button.test.tsx.snap
@@ -5,7 +5,7 @@ exports[`renders button with an accessibility hint 1`] = `
   collapsable={false}
   style={
     {
-      "backgroundColor": "transparent",
+      "backgroundColor": "rgba(103, 80, 164, 1)",
       "borderRadius": 20,
       "shadowColor": "rgba(0, 0, 0, 1)",
       "shadowOffset": {
@@ -22,7 +22,7 @@ exports[`renders button with an accessibility hint 1`] = `
     collapsable={false}
     style={
       {
-        "backgroundColor": "transparent",
+        "backgroundColor": "rgba(103, 80, 164, 1)",
         "borderColor": "transparent",
         "borderRadius": 20,
         "borderStyle": "solid",
@@ -127,12 +127,13 @@ exports[`renders button with an accessibility hint 1`] = `
                     "textAlign": "center",
                   },
                   {
-                    "marginHorizontal": 12,
+                    "marginHorizontal": 16,
+                    "marginVertical": 10,
                   },
                   undefined,
                   false,
                   {
-                    "color": "rgba(103, 80, 164, 1)",
+                    "color": "rgba(255, 255, 255, 1)",
                     "fontFamily": "System",
                     "fontSize": 14,
                     "fontWeight": "500",
@@ -159,7 +160,7 @@ exports[`renders button with an accessibility label 1`] = `
   collapsable={false}
   style={
     {
-      "backgroundColor": "transparent",
+      "backgroundColor": "rgba(103, 80, 164, 1)",
       "borderRadius": 20,
       "shadowColor": "rgba(0, 0, 0, 1)",
       "shadowOffset": {
@@ -176,7 +177,7 @@ exports[`renders button with an accessibility label 1`] = `
     collapsable={false}
     style={
       {
-        "backgroundColor": "transparent",
+        "backgroundColor": "rgba(103, 80, 164, 1)",
         "borderColor": "transparent",
         "borderRadius": 20,
         "borderStyle": "solid",
@@ -281,12 +282,13 @@ exports[`renders button with an accessibility label 1`] = `
                     "textAlign": "center",
                   },
                   {
-                    "marginHorizontal": 12,
+                    "marginHorizontal": 16,
+                    "marginVertical": 10,
                   },
                   undefined,
                   false,
                   {
-                    "color": "rgba(103, 80, 164, 1)",
+                    "color": "rgba(255, 255, 255, 1)",
                     "fontFamily": "System",
                     "fontSize": 14,
                     "fontWeight": "500",
@@ -434,12 +436,13 @@ exports[`renders button with button color 1`] = `
                     "textAlign": "center",
                   },
                   {
-                    "marginHorizontal": 12,
+                    "marginHorizontal": 16,
+                    "marginVertical": 10,
                   },
                   undefined,
                   false,
                   {
-                    "color": "rgba(103, 80, 164, 1)",
+                    "color": "rgba(255, 255, 255, 1)",
                     "fontFamily": "System",
                     "fontSize": 14,
                     "fontWeight": "500",
@@ -466,7 +469,7 @@ exports[`renders button with color 1`] = `
   collapsable={false}
   style={
     {
-      "backgroundColor": "transparent",
+      "backgroundColor": "rgba(103, 80, 164, 1)",
       "borderRadius": 20,
       "shadowColor": "rgba(0, 0, 0, 1)",
       "shadowOffset": {
@@ -483,7 +486,7 @@ exports[`renders button with color 1`] = `
     collapsable={false}
     style={
       {
-        "backgroundColor": "transparent",
+        "backgroundColor": "rgba(103, 80, 164, 1)",
         "borderColor": "transparent",
         "borderRadius": 20,
         "borderStyle": "solid",
@@ -587,7 +590,8 @@ exports[`renders button with color 1`] = `
                     "textAlign": "center",
                   },
                   {
-                    "marginHorizontal": 12,
+                    "marginHorizontal": 16,
+                    "marginVertical": 10,
                   },
                   undefined,
                   false,
@@ -619,7 +623,7 @@ exports[`renders button with custom testID 1`] = `
   collapsable={false}
   style={
     {
-      "backgroundColor": "transparent",
+      "backgroundColor": "rgba(103, 80, 164, 1)",
       "borderRadius": 20,
       "shadowColor": "rgba(0, 0, 0, 1)",
       "shadowOffset": {
@@ -636,7 +640,7 @@ exports[`renders button with custom testID 1`] = `
     collapsable={false}
     style={
       {
-        "backgroundColor": "transparent",
+        "backgroundColor": "rgba(103, 80, 164, 1)",
         "borderColor": "transparent",
         "borderRadius": 20,
         "borderStyle": "solid",
@@ -740,12 +744,13 @@ exports[`renders button with custom testID 1`] = `
                     "textAlign": "center",
                   },
                   {
-                    "marginHorizontal": 12,
+                    "marginHorizontal": 16,
+                    "marginVertical": 10,
                   },
                   undefined,
                   false,
                   {
-                    "color": "rgba(103, 80, 164, 1)",
+                    "color": "rgba(255, 255, 255, 1)",
                     "fontFamily": "System",
                     "fontSize": 14,
                     "fontWeight": "500",
@@ -772,7 +777,7 @@ exports[`renders button with icon 1`] = `
   collapsable={false}
   style={
     {
-      "backgroundColor": "transparent",
+      "backgroundColor": "rgba(103, 80, 164, 1)",
       "borderRadius": 20,
       "shadowColor": "rgba(0, 0, 0, 1)",
       "shadowOffset": {
@@ -789,7 +794,7 @@ exports[`renders button with icon 1`] = `
     collapsable={false}
     style={
       {
-        "backgroundColor": "transparent",
+        "backgroundColor": "rgba(103, 80, 164, 1)",
         "borderColor": "transparent",
         "borderRadius": 20,
         "borderStyle": "solid",
@@ -869,7 +874,7 @@ exports[`renders button with icon 1`] = `
         <View
           style={
             {
-              "marginLeft": 12,
+              "marginLeft": 16,
               "marginRight": -8,
             }
           }
@@ -883,7 +888,7 @@ exports[`renders button with icon 1`] = `
             style={
               [
                 {
-                  "color": "rgba(103, 80, 164, 1)",
+                  "color": "rgba(255, 255, 255, 1)",
                   "fontSize": 20,
                 },
                 [
@@ -933,11 +938,12 @@ exports[`renders button with icon 1`] = `
                   },
                   {
                     "marginHorizontal": 16,
+                    "marginVertical": 10,
                   },
                   undefined,
                   false,
                   {
-                    "color": "rgba(103, 80, 164, 1)",
+                    "color": "rgba(255, 255, 255, 1)",
                     "fontFamily": "System",
                     "fontSize": 14,
                     "fontWeight": "500",
@@ -964,7 +970,7 @@ exports[`renders button with icon in reverse order 1`] = `
   collapsable={false}
   style={
     {
-      "backgroundColor": "transparent",
+      "backgroundColor": "rgba(103, 80, 164, 1)",
       "borderRadius": 20,
       "shadowColor": "rgba(0, 0, 0, 1)",
       "shadowOffset": {
@@ -981,7 +987,7 @@ exports[`renders button with icon in reverse order 1`] = `
     collapsable={false}
     style={
       {
-        "backgroundColor": "transparent",
+        "backgroundColor": "rgba(103, 80, 164, 1)",
         "borderColor": "transparent",
         "borderRadius": 20,
         "borderStyle": "solid",
@@ -1066,7 +1072,7 @@ exports[`renders button with icon in reverse order 1`] = `
           style={
             {
               "marginLeft": -8,
-              "marginRight": 12,
+              "marginRight": 16,
             }
           }
           testID="button-icon-container"
@@ -1079,7 +1085,7 @@ exports[`renders button with icon in reverse order 1`] = `
             style={
               [
                 {
-                  "color": "rgba(103, 80, 164, 1)",
+                  "color": "rgba(255, 255, 255, 1)",
                   "fontSize": 20,
                 },
                 [
@@ -1129,11 +1135,12 @@ exports[`renders button with icon in reverse order 1`] = `
                   },
                   {
                     "marginHorizontal": 16,
+                    "marginVertical": 10,
                   },
                   undefined,
                   false,
                   {
-                    "color": "rgba(103, 80, 164, 1)",
+                    "color": "rgba(255, 255, 255, 1)",
                     "fontFamily": "System",
                     "fontSize": 14,
                     "fontWeight": "500",
@@ -1195,6 +1202,25 @@ exports[`renders disabled button 1`] = `
     }
     testID="button-container"
   >
+    <View
+      pointerEvents="none"
+      style={
+        [
+          {
+            "bottom": 0,
+            "left": 0,
+            "position": "absolute",
+            "right": 0,
+            "top": 0,
+          },
+          {
+            "backgroundColor": "rgba(29, 27, 32, 1)",
+            "borderRadius": 20,
+            "opacity": 0.1,
+          },
+        ]
+      }
+    />
     <View
       accessibilityRole="button"
       accessibilityState={
@@ -1281,7 +1307,8 @@ exports[`renders disabled button 1`] = `
                     "textAlign": "center",
                   },
                   {
-                    "marginHorizontal": 12,
+                    "marginHorizontal": 16,
+                    "marginVertical": 10,
                   },
                   undefined,
                   false,
@@ -1308,6 +1335,160 @@ exports[`renders disabled button 1`] = `
 </View>
 `;
 
+exports[`renders filled button by default 1`] = `
+<View
+  collapsable={false}
+  style={
+    {
+      "backgroundColor": "rgba(103, 80, 164, 1)",
+      "borderRadius": 20,
+      "shadowColor": "rgba(0, 0, 0, 1)",
+      "shadowOffset": {
+        "height": 0,
+        "width": 0,
+      },
+      "shadowOpacity": 0,
+      "shadowRadius": 0,
+    }
+  }
+  testID="button-container-outer-layer"
+>
+  <View
+    collapsable={false}
+    style={
+      {
+        "backgroundColor": "rgba(103, 80, 164, 1)",
+        "borderColor": "transparent",
+        "borderRadius": 20,
+        "borderStyle": "solid",
+        "borderWidth": 0,
+        "flex": undefined,
+        "minWidth": 64,
+        "shadowColor": "rgba(0, 0, 0, 1)",
+        "shadowOffset": {
+          "height": 0,
+          "width": 0,
+        },
+        "shadowOpacity": 0,
+        "shadowRadius": 0,
+      }
+    }
+    testID="button-container"
+  >
+    <View
+      accessibilityRole="button"
+      accessibilityState={
+        {
+          "busy": undefined,
+          "checked": undefined,
+          "disabled": true,
+          "expanded": undefined,
+          "selected": undefined,
+        }
+      }
+      accessibilityValue={
+        {
+          "max": undefined,
+          "min": undefined,
+          "now": undefined,
+          "text": undefined,
+        }
+      }
+      accessible={true}
+      collapsable={false}
+      focusable={true}
+      onBlur={[Function]}
+      onClick={[Function]}
+      onFocus={[Function]}
+      onResponderGrant={[Function]}
+      onResponderMove={[Function]}
+      onResponderRelease={[Function]}
+      onResponderTerminate={[Function]}
+      onResponderTerminationRequest={[Function]}
+      onStartShouldSetResponder={[Function]}
+      style={
+        [
+          {
+            "overflow": "hidden",
+          },
+          {
+            "borderRadius": 20,
+          },
+        ]
+      }
+      testID="button"
+    >
+      <View
+        style={
+          [
+            {
+              "alignItems": "center",
+              "flexDirection": "row",
+              "justifyContent": "center",
+            },
+            false,
+            {
+              "opacity": 1,
+            },
+            undefined,
+          ]
+        }
+      >
+        <Text
+          numberOfLines={1}
+          selectable={false}
+          style={
+            [
+              {
+                "textAlign": "left",
+              },
+              {
+                "color": "rgba(29, 27, 32, 1)",
+                "writingDirection": "ltr",
+              },
+              [
+                {
+                  "fontFamily": "System",
+                  "fontSize": 14,
+                  "fontWeight": "500",
+                  "letterSpacing": 0.1,
+                  "lineHeight": 20,
+                },
+                [
+                  {
+                    "marginHorizontal": 16,
+                    "marginVertical": 9,
+                    "textAlign": "center",
+                  },
+                  {
+                    "marginHorizontal": 16,
+                    "marginVertical": 10,
+                  },
+                  undefined,
+                  false,
+                  {
+                    "color": "rgba(255, 255, 255, 1)",
+                    "fontFamily": "System",
+                    "fontSize": 14,
+                    "fontWeight": "500",
+                    "letterSpacing": 0.1,
+                    "lineHeight": 20,
+                  },
+                  undefined,
+                ],
+              ],
+            ]
+          }
+          testID="button-text"
+        >
+          Filled Button
+        </Text>
+      </View>
+    </View>
+  </View>
+</View>
+`;
+
 exports[`renders filled button with mode 1`] = `
 <View
   collapsable={false}
@@ -1467,7 +1648,7 @@ exports[`renders loading button 1`] = `
   collapsable={false}
   style={
     {
-      "backgroundColor": "transparent",
+      "backgroundColor": "rgba(103, 80, 164, 1)",
       "borderRadius": 20,
       "shadowColor": "rgba(0, 0, 0, 1)",
       "shadowOffset": {
@@ -1484,7 +1665,7 @@ exports[`renders loading button 1`] = `
     collapsable={false}
     style={
       {
-        "backgroundColor": "transparent",
+        "backgroundColor": "rgba(103, 80, 164, 1)",
         "borderColor": "transparent",
         "borderRadius": 20,
         "borderStyle": "solid",
@@ -1576,7 +1757,7 @@ exports[`renders loading button 1`] = `
                 "justifyContent": "center",
               },
               {
-                "marginLeft": 12,
+                "marginLeft": 16,
                 "marginRight": -8,
               },
             ]
@@ -1661,7 +1842,7 @@ exports[`renders loading button 1`] = `
                         collapsable={false}
                         style={
                           {
-                            "borderColor": "rgba(103, 80, 164, 1)",
+                            "borderColor": "rgba(255, 255, 255, 1)",
                             "borderRadius": 10,
                             "borderWidth": 2,
                             "height": 20,
@@ -1744,7 +1925,7 @@ exports[`renders loading button 1`] = `
                         collapsable={false}
                         style={
                           {
-                            "borderColor": "rgba(103, 80, 164, 1)",
+                            "borderColor": "rgba(255, 255, 255, 1)",
                             "borderRadius": 10,
                             "borderWidth": 2,
                             "height": 20,
@@ -1787,11 +1968,12 @@ exports[`renders loading button 1`] = `
                   },
                   {
                     "marginHorizontal": 16,
+                    "marginVertical": 10,
                   },
                   undefined,
                   false,
                   {
-                    "color": "rgba(103, 80, 164, 1)",
+                    "color": "rgba(255, 255, 255, 1)",
                     "fontFamily": "System",
                     "fontSize": 14,
                     "fontWeight": "500",
@@ -1967,159 +2149,6 @@ exports[`renders outlined button with mode 1`] = `
 </View>
 `;
 
-exports[`renders text button by default 1`] = `
-<View
-  collapsable={false}
-  style={
-    {
-      "backgroundColor": "transparent",
-      "borderRadius": 20,
-      "shadowColor": "rgba(0, 0, 0, 1)",
-      "shadowOffset": {
-        "height": 0,
-        "width": 0,
-      },
-      "shadowOpacity": 0,
-      "shadowRadius": 0,
-    }
-  }
-  testID="button-container-outer-layer"
->
-  <View
-    collapsable={false}
-    style={
-      {
-        "backgroundColor": "transparent",
-        "borderColor": "transparent",
-        "borderRadius": 20,
-        "borderStyle": "solid",
-        "borderWidth": 0,
-        "flex": undefined,
-        "minWidth": 64,
-        "shadowColor": "rgba(0, 0, 0, 1)",
-        "shadowOffset": {
-          "height": 0,
-          "width": 0,
-        },
-        "shadowOpacity": 0,
-        "shadowRadius": 0,
-      }
-    }
-    testID="button-container"
-  >
-    <View
-      accessibilityRole="button"
-      accessibilityState={
-        {
-          "busy": undefined,
-          "checked": undefined,
-          "disabled": true,
-          "expanded": undefined,
-          "selected": undefined,
-        }
-      }
-      accessibilityValue={
-        {
-          "max": undefined,
-          "min": undefined,
-          "now": undefined,
-          "text": undefined,
-        }
-      }
-      accessible={true}
-      collapsable={false}
-      focusable={true}
-      onBlur={[Function]}
-      onClick={[Function]}
-      onFocus={[Function]}
-      onResponderGrant={[Function]}
-      onResponderMove={[Function]}
-      onResponderRelease={[Function]}
-      onResponderTerminate={[Function]}
-      onResponderTerminationRequest={[Function]}
-      onStartShouldSetResponder={[Function]}
-      style={
-        [
-          {
-            "overflow": "hidden",
-          },
-          {
-            "borderRadius": 20,
-          },
-        ]
-      }
-      testID="button"
-    >
-      <View
-        style={
-          [
-            {
-              "alignItems": "center",
-              "flexDirection": "row",
-              "justifyContent": "center",
-            },
-            false,
-            {
-              "opacity": 1,
-            },
-            undefined,
-          ]
-        }
-      >
-        <Text
-          numberOfLines={1}
-          selectable={false}
-          style={
-            [
-              {
-                "textAlign": "left",
-              },
-              {
-                "color": "rgba(29, 27, 32, 1)",
-                "writingDirection": "ltr",
-              },
-              [
-                {
-                  "fontFamily": "System",
-                  "fontSize": 14,
-                  "fontWeight": "500",
-                  "letterSpacing": 0.1,
-                  "lineHeight": 20,
-                },
-                [
-                  {
-                    "marginHorizontal": 16,
-                    "marginVertical": 9,
-                    "textAlign": "center",
-                  },
-                  {
-                    "marginHorizontal": 12,
-                  },
-                  undefined,
-                  false,
-                  {
-                    "color": "rgba(103, 80, 164, 1)",
-                    "fontFamily": "System",
-                    "fontSize": 14,
-                    "fontWeight": "500",
-                    "letterSpacing": 0.1,
-                    "lineHeight": 20,
-                  },
-                  undefined,
-                ],
-              ],
-            ]
-          }
-          testID="button-text"
-        >
-          Text Button
-        </Text>
-      </View>
-    </View>
-  </View>
-</View>
-`;
-
 exports[`renders text button with mode 1`] = `
 <View
   collapsable={false}
@@ -2278,7 +2307,7 @@ exports[`size prop renders a button with per-size metrics 1`] = `
   collapsable={false}
   style={
     {
-      "backgroundColor": "transparent",
+      "backgroundColor": "rgba(103, 80, 164, 1)",
       "borderRadius": 20,
       "shadowColor": "rgba(0, 0, 0, 1)",
       "shadowOffset": {
@@ -2295,7 +2324,7 @@ exports[`size prop renders a button with per-size metrics 1`] = `
     collapsable={false}
     style={
       {
-        "backgroundColor": "transparent",
+        "backgroundColor": "rgba(103, 80, 164, 1)",
         "borderColor": "transparent",
         "borderRadius": 20,
         "borderStyle": "solid",
@@ -2388,7 +2417,7 @@ exports[`size prop renders a button with per-size metrics 1`] = `
             style={
               [
                 {
-                  "color": "rgba(103, 80, 164, 1)",
+                  "color": "rgba(255, 255, 255, 1)",
                   "fontSize": 24,
                 },
                 [
@@ -2443,7 +2472,7 @@ exports[`size prop renders a button with per-size metrics 1`] = `
                   false,
                   false,
                   {
-                    "color": "rgba(103, 80, 164, 1)",
+                    "color": "rgba(255, 255, 255, 1)",
                     "fontFamily": "System",
                     "fontSize": 16,
                     "fontWeight": "500",

From feff6721f3575e3f576e4081e09d6914944b43df Mon Sep 17 00:00:00 2001
From: Aziz Becha <aziz07becha@gmail.com>
Date: Wed, 20 May 2026 20:20:15 +0100
Subject: [PATCH 21/24] fix(button): ensure 48dp minimum touch target for XS/S
 sizes

Extra-small (32dp) and small (40dp) buttons are shorter than the 48dp minimum
accessible touch target, so expand the press area with hitSlop without changing
the visual size (XS -> top/bottom 8, S -> top/bottom 4). A user-supplied
hitSlop wins on the axes it sets; a numeric hitSlop is respected as-is.
Verified on device that taps inside the slop zone register and taps outside
do not.
---
 src/components/Button/Button.tsx         | 29 ++++++++++++++-
 src/components/__tests__/Button.test.tsx | 46 ++++++++++++++++++++++++
 2 files changed, 74 insertions(+), 1 deletion(-)

diff --git a/src/components/Button/Button.tsx b/src/components/Button/Button.tsx
index bc0efa49ff..0aa545cd92 100644
--- a/src/components/Button/Button.tsx
+++ b/src/components/Button/Button.tsx
@@ -230,6 +230,9 @@ const initialElevation = 1;
 const activeElevation = 2;
 // MD3 leading/trailing icon size for the legacy (no-`size`) button.
 const iconSize = 20;
+// Minimum accessible touch target (dp). Extra-small/small buttons are shorter
+// than this and get expanded via hitSlop.
+const MIN_TOUCH_TARGET = 48;
 
 const Button = (
   {
@@ -448,6 +451,30 @@ const Button = (
     [size]
   );
 
+  // Extra-small/small buttons are shorter than the 48dp minimum accessible
+  // touch target, so expand the press area with hitSlop without changing the
+  // visual size. A user-supplied `hitSlop` wins on the axes it sets.
+  const hitSlopWithMinTarget = React.useMemo(() => {
+    const verticalSlop = sizeStyle
+      ? Math.max(0, (MIN_TOUCH_TARGET - sizeStyle.minHeight) / 2)
+      : 0;
+    if (verticalSlop === 0) {
+      return hitSlop;
+    }
+    if (hitSlop == null) {
+      return { top: verticalSlop, bottom: verticalSlop };
+    }
+    // A numeric hitSlop is an explicit uniform override — respect it as-is.
+    if (typeof hitSlop === 'number') {
+      return hitSlop;
+    }
+    return {
+      ...hitSlop,
+      top: hitSlop.top ?? verticalSlop,
+      bottom: hitSlop.bottom ?? verticalSlop,
+    };
+  }, [hitSlop, sizeStyle]);
+
   const labelTypeStyle = React.useMemo(
     () => ({
       color: labelColor,
@@ -511,7 +538,7 @@ const Button = (
         accessibilityRole={accessibilityRole}
         accessibilityState={{ disabled, selected }}
         accessible={accessible}
-        hitSlop={hitSlop}
+        hitSlop={hitSlopWithMinTarget}
         disabled={disabled}
         style={touchableRippleStyle}
         testID={testID}
diff --git a/src/components/__tests__/Button.test.tsx b/src/components/__tests__/Button.test.tsx
index 464cbbb99d..90afbc82c6 100644
--- a/src/components/__tests__/Button.test.tsx
+++ b/src/components/__tests__/Button.test.tsx
@@ -923,6 +923,52 @@ describe('size prop', () => {
   );
 });
 
+describe('accessible touch target', () => {
+  it('expands extra-small buttons to the 48dp minimum target', () => {
+    const { getByTestId } = render(
+      <Button size="extra-small" testID="button" label="X" />
+    );
+    // (48 - 32) / 2 = 8
+    expect(getByTestId('button').props.hitSlop).toMatchObject({
+      top: 8,
+      bottom: 8,
+    });
+  });
+
+  it('expands small buttons to the 48dp minimum target', () => {
+    const { getByTestId } = render(
+      <Button size="small" testID="button" label="X" />
+    );
+    // (48 - 40) / 2 = 4
+    expect(getByTestId('button').props.hitSlop).toMatchObject({
+      top: 4,
+      bottom: 4,
+    });
+  });
+
+  it('does not add hitSlop for buttons already at least 48dp tall', () => {
+    const { getByTestId } = render(
+      <Button size="medium" testID="button" label="X" />
+    );
+    expect(getByTestId('button').props.hitSlop).toBeUndefined();
+  });
+
+  it('keeps a user-supplied hitSlop axis while filling the rest', () => {
+    const { getByTestId } = render(
+      <Button
+        size="extra-small"
+        testID="button"
+        label="X"
+        hitSlop={{ top: 20 }}
+      />
+    );
+    expect(getByTestId('button').props.hitSlop).toMatchObject({
+      top: 20,
+      bottom: 8,
+    });
+  });
+});
+
 describe('getButtonShapeRadius', () => {
   it.each([
     ['extra-small', 9999, 12],

From 56dbce1f6ed274cbfd5a2871b1abfdb772821e1e Mon Sep 17 00:00:00 2001
From: Aziz Becha <aziz07becha@gmail.com>
Date: Thu, 21 May 2026 00:08:15 +0100
Subject: [PATCH 22/24] feat(button): animate shape morph on press and toggle

Shaped buttons animate their corner radius with the theme motion spring: to
corner.small (8dp) while pressed, and between the round/square radii when the
selected toggle flips the shape.

Stability: the animated path resolves round to the real pill radius
(minHeight/2) instead of the cornerFull sentinel so the spring stays bounded,
plus a >= 0 clamp guards against overshoot. Scoped to shaped buttons that
don't pin a radius via style; legacy/size-only buttons keep a static corner.

Web: the inner ripple can't follow an Animated value, so it's rendered as a
rectangle and the Surface clips it (overflow: hidden) to the morphing radius,
keeping the outline and state layer in sync.
---
 src/components/Button/Button.tsx         | 152 ++++++++++++++++++-----
 src/components/__tests__/Button.test.tsx |  98 +++++++++++++++
 2 files changed, 219 insertions(+), 31 deletions(-)

diff --git a/src/components/Button/Button.tsx b/src/components/Button/Button.tsx
index 0aa545cd92..6349184143 100644
--- a/src/components/Button/Button.tsx
+++ b/src/components/Button/Button.tsx
@@ -26,6 +26,7 @@ import {
 } from './utils';
 import { getDefaultDirection, useLocale } from '../../core/locale';
 import { useInternalTheme } from '../../core/theming';
+import { toRawSpring } from '../../theme/tokens/sys/motion';
 import type { $Omit, Theme, ThemeProp } from '../../types';
 import { forwardRef } from '../../utils/forwardRef';
 import hasTouchHandler from '../../utils/hasTouchHandler';
@@ -332,9 +333,67 @@ const Button = (
     });
   }, [isElevationEntitled, elevation]);
 
+  const borderRadiusStyles = React.useMemo(() => {
+    const flattenedStyles = (StyleSheet.flatten(style) || {}) as ViewStyle;
+    const [, radiusStyles] = splitStyles(
+      flattenedStyles,
+      (key) => key.startsWith('border') && key.endsWith('Radius')
+    );
+    return radiusStyles;
+  }, [style]);
+
+  // When the button is `selected`, flip the requested shape so the
+  // unselected/selected pair contrasts visually (round ↔ square).
+  const effectiveShape: ButtonShape | undefined = shape
+    ? selected
+      ? shape === 'round'
+        ? 'square'
+        : 'round'
+      : shape
+    : undefined;
+  const staticRadius = effectiveShape
+    ? getButtonShapeRadius({ size, shape: effectiveShape, theme })
+    : theme.shapes.corner.largeIncreased;
+
+  const sizeStyle = React.useMemo(
+    () => (size ? getButtonSizeStyle(size) : undefined),
+    [size]
+  );
+
+  // Shape morph: animate the corner on press (→ corner.small) and on the
+  // `selected`/shape toggle. Shaped buttons only; skip a user-pinned radius.
+  const hasPinnedRadius = Object.keys(borderRadiusStyles).length > 0;
+  const animateShape = shape != null && !hasPinnedRadius;
+  // Use the real pill radius (minHeight/2) for `round` so the spring stays
+  // bounded instead of animating from the full-pill sentinel.
+  const restingRadius =
+    effectiveShape === 'round' && sizeStyle
+      ? sizeStyle.minHeight / 2
+      : staticRadius;
+  const pressedRadius = theme.shapes.corner.small;
+  const { current: animatedRadius } = React.useRef<Animated.Value>(
+    new Animated.Value(restingRadius)
+  );
+  const restingRadiusRef = React.useRef(restingRadius);
+  const isRadiusMountedRef = React.useRef(false);
+
+  const springRadiusTo = React.useCallback(
+    (toValue: number) => {
+      Animated.spring(animatedRadius, {
+        toValue,
+        ...toRawSpring(theme.motion.spring.fast.spatial),
+        useNativeDriver: false,
+      }).start();
+    },
+    [animatedRadius, theme]
+  );
+
   const handlePressIn = React.useCallback(
     (e: GestureResponderEvent) => {
       onPressIn?.(e);
+      if (animateShape) {
+        springRadiusTo(pressedRadius);
+      }
       if (mode === 'elevated') {
         const { scale } = animation;
         Animated.timing(elevation, {
@@ -345,12 +404,24 @@ const Button = (
         }).start();
       }
     },
-    [onPressIn, mode, animation, elevation, isWeb]
+    [
+      onPressIn,
+      animateShape,
+      springRadiusTo,
+      pressedRadius,
+      mode,
+      animation,
+      elevation,
+      isWeb,
+    ]
   );
 
   const handlePressOut = React.useCallback(
     (e: GestureResponderEvent) => {
       onPressOut?.(e);
+      if (animateShape) {
+        springRadiusTo(restingRadiusRef.current);
+      }
       if (mode === 'elevated') {
         const { scale } = animation;
         Animated.timing(elevation, {
@@ -361,30 +432,43 @@ const Button = (
         }).start();
       }
     },
-    [onPressOut, mode, animation, elevation, isWeb]
+    [
+      onPressOut,
+      animateShape,
+      springRadiusTo,
+      mode,
+      animation,
+      elevation,
+      isWeb,
+    ]
   );
 
-  const borderRadiusStyles = React.useMemo(() => {
-    const flattenedStyles = (StyleSheet.flatten(style) || {}) as ViewStyle;
-    const [, radiusStyles] = splitStyles(
-      flattenedStyles,
-      (key) => key.startsWith('border') && key.endsWith('Radius')
-    );
-    return radiusStyles;
-  }, [style]);
+  // Snap on mount; animate when a toggle/shape change moves the resting radius.
+  React.useEffect(() => {
+    restingRadiusRef.current = restingRadius;
+    if (!isRadiusMountedRef.current) {
+      isRadiusMountedRef.current = true;
+      return;
+    }
+    if (animateShape) {
+      springRadiusTo(restingRadius);
+    } else {
+      animatedRadius.setValue(restingRadius);
+    }
+  }, [restingRadius, animateShape, animatedRadius, springRadiusTo]);
 
-  // When the button is `selected`, flip the requested shape so the
-  // unselected/selected pair contrasts visually (round ↔ square).
-  const effectiveShape: ButtonShape | undefined = shape
-    ? selected
-      ? shape === 'round'
-        ? 'square'
-        : 'round'
-      : shape
-    : undefined;
-  const borderRadius = effectiveShape
-    ? getButtonShapeRadius({ size, shape: effectiveShape, theme })
-    : theme.shapes.corner.largeIncreased;
+  // Clamp so a spring overshoot can never render a negative radius.
+  const surfaceRadius = React.useMemo(
+    () =>
+      animateShape
+        ? animatedRadius.interpolate({
+            inputRange: [0, 1],
+            outputRange: [0, 1],
+            extrapolateLeft: 'clamp',
+          })
+        : staticRadius,
+    [animateShape, animatedRadius, staticRadius]
+  );
 
   const {
     backgroundColor,
@@ -415,9 +499,9 @@ const Button = (
   const touchableStyle = React.useMemo(
     () => ({
       ...borderRadiusStyles,
-      borderRadius: borderRadiusStyles.borderRadius ?? borderRadius,
+      borderRadius: borderRadiusStyles.borderRadius ?? staticRadius,
     }),
-    [borderRadiusStyles, borderRadius]
+    [borderRadiusStyles, staticRadius]
   );
 
   const buttonStyle = React.useMemo(
@@ -426,6 +510,7 @@ const Button = (
       borderColor,
       borderWidth,
       ...touchableStyle,
+      borderRadius: surfaceRadius, // animated; ripple clip + overlay stay static
     }),
     [
       backgroundOpacity,
@@ -433,12 +518,17 @@ const Button = (
       borderColor,
       borderWidth,
       touchableStyle,
+      surfaceRadius,
     ]
   );
 
   const touchableRippleStyle = React.useMemo(
-    () => getButtonTouchableRippleStyle(touchableStyle, borderWidth),
-    [touchableStyle, borderWidth]
+    () =>
+      // Web can't animate the inner radius — use a rect clipped by the Surface.
+      isWeb && animateShape
+        ? { borderRadius: 0 }
+        : getButtonTouchableRippleStyle(touchableStyle, borderWidth),
+    [isWeb, animateShape, touchableStyle, borderWidth]
   );
 
   const { color: labelStyleColor, fontSize: labelStyleSize } = React.useMemo(
@@ -446,11 +536,6 @@ const Button = (
     [labelStyle]
   );
 
-  const sizeStyle = React.useMemo(
-    () => (size ? getButtonSizeStyle(size) : undefined),
-    [size]
-  );
-
   // Extra-small/small buttons are shorter than the 48dp minimum accessible
   // touch target, so expand the press area with hitSlop without changing the
   // visual size. A user-supplied `hitSlop` wins on the axes it sets.
@@ -505,6 +590,8 @@ const Button = (
           styles.button,
           compact && styles.compact,
           buttonStyle,
+          // Clip the rect ripple to the morphing radius (web; box-shadow safe).
+          isWeb && animateShape && styles.clip,
           style,
         ] as Animated.WithAnimatedValue<StyleProp<ViewStyle>>
       }
@@ -623,6 +710,9 @@ const styles = StyleSheet.create({
     minWidth: 64,
     borderStyle: 'solid',
   },
+  clip: {
+    overflow: 'hidden',
+  },
   compact: {
     minWidth: 'auto',
   },
diff --git a/src/components/__tests__/Button.test.tsx b/src/components/__tests__/Button.test.tsx
index 90afbc82c6..d19ae55be2 100644
--- a/src/components/__tests__/Button.test.tsx
+++ b/src/components/__tests__/Button.test.tsx
@@ -1121,3 +1121,101 @@ it('animated value changes correctly', () => {
     transform: [{ scale: 1.5 }],
   });
 });
+
+describe('shape morph animation', () => {
+  const lastSpringToValue = (spy: jest.SpyInstance) =>
+    spy.mock.calls.map((call) => call[1]?.toValue);
+
+  it('springs the corner radius to corner.small on press in', () => {
+    const spy = jest.spyOn(Animated, 'spring');
+    const { getByTestId } = render(
+      <Button shape="round" size="small" onPress={() => {}} testID="button" />
+    );
+    spy.mockClear();
+    fireEvent(getByTestId('button'), 'onPressIn');
+    expect(lastSpringToValue(spy)).toContain(getTheme().shapes.corner.small);
+    spy.mockRestore();
+  });
+
+  it('springs the corner radius back to the resting pill radius on press out', () => {
+    const spy = jest.spyOn(Animated, 'spring');
+    const { getByTestId } = render(
+      <Button shape="round" size="small" onPress={() => {}} testID="button" />
+    );
+    spy.mockClear();
+    fireEvent(getByTestId('button'), 'onPressOut');
+    // small round resting radius = minHeight (40) / 2 = 20
+    expect(lastSpringToValue(spy)).toContain(20);
+    spy.mockRestore();
+  });
+
+  it('animates between round and square radii when toggled (no spring on mount)', () => {
+    const spy = jest.spyOn(Animated, 'spring');
+    const { rerender } = render(
+      <Button shape="square" size="large" onPress={() => {}} testID="button" />
+    );
+    // Mount snaps to the resting radius — no spring.
+    expect(spy).not.toHaveBeenCalled();
+    rerender(
+      <Button
+        shape="square"
+        size="large"
+        selected
+        onPress={() => {}}
+        testID="button"
+      />
+    );
+    // selected flips square -> round; large round resting radius = 96 / 2 = 48
+    expect(lastSpringToValue(spy)).toContain(48);
+    spy.mockRestore();
+  });
+
+  it('does not morph legacy or size-only buttons', () => {
+    const spy = jest.spyOn(Animated, 'spring');
+    const { getByTestId, rerender } = render(
+      <Button onPress={() => {}} testID="button" label="Legacy" />
+    );
+    spy.mockClear();
+    fireEvent(getByTestId('button'), 'onPressIn');
+    expect(spy).not.toHaveBeenCalled();
+
+    rerender(
+      <Button size="small" onPress={() => {}} testID="button" label="Sized" />
+    );
+    spy.mockClear();
+    fireEvent(getByTestId('button'), 'onPressIn');
+    expect(spy).not.toHaveBeenCalled();
+    spy.mockRestore();
+  });
+
+  it('does not morph when the user pins a radius via style', () => {
+    const spy = jest.spyOn(Animated, 'spring');
+    const { getByTestId } = render(
+      <Button
+        shape="round"
+        size="small"
+        style={styles.overrideRadius}
+        onPress={() => {}}
+        testID="button"
+      />
+    );
+    spy.mockClear();
+    fireEvent(getByTestId('button'), 'onPressIn');
+    expect(spy).not.toHaveBeenCalled();
+    expect(getByTestId('button-container')).toHaveStyle({ borderRadius: 4 });
+    spy.mockRestore();
+  });
+
+  it('applies the pressed corner radius to the surface', () => {
+    const { getByTestId } = render(
+      <Button shape="round" size="small" onPress={() => {}} testID="button" />
+    );
+    fireEvent(getByTestId('button'), 'onPressIn');
+    act(() => {
+      jest.advanceTimersByTime(1000);
+    });
+    expect(getByTestId('button-container')).toHaveStyle({
+      borderRadius: getTheme().shapes.corner.small,
+    });
+  });
+});

From d0fb8415b489d7e6e1e17ba204cd83eb3e371986 Mon Sep 17 00:00:00 2001
From: Aziz Becha <aziz07becha@gmail.com>
Date: Thu, 21 May 2026 01:01:58 +0100
Subject: [PATCH 23/24] chore(example): revamp Button example as an interactive
 playground

Replace the long exhaustive grid with a compact playground: a live Button
driven by Chip controls (mode/size/shape/icon-position) and Switch rows
(show icon/disabled/loading/selected/compact), with smart gating so a control
is never a no-op (icon-position only with an icon; compact only when size is
unset). Keeps trimmed showcase sections: Modes, States, Size, Shape, Toggle,
Custom.
---
 example/src/Examples/ButtonExample.tsx | 613 +++++++++++--------------
 1 file changed, 273 insertions(+), 340 deletions(-)

diff --git a/example/src/Examples/ButtonExample.tsx b/example/src/Examples/ButtonExample.tsx
index c61426f96d..f4b3e8683b 100644
--- a/example/src/Examples/ButtonExample.tsx
+++ b/example/src/Examples/ButtonExample.tsx
@@ -1,166 +1,201 @@
 import * as React from 'react';
 import { Image, StyleSheet, View } from 'react-native';
 
-import { Button, List, useTheme } from 'react-native-paper';
+import { Button, Chip, List, Switch, Text, useTheme } from 'react-native-paper';
 
 import ScreenWrapper from '../ScreenWrapper';
 
+type Mode = 'text' | 'outlined' | 'elevated' | 'filled' | 'tonal';
+type SizeOption =
+  | 'unset'
+  | 'extra-small'
+  | 'small'
+  | 'medium'
+  | 'large'
+  | 'extra-large';
+type ShapeOption = 'unset' | 'round' | 'square';
+type IconPosition = 'leading' | 'trailing';
+
+const MODES: Mode[] = ['filled', 'tonal', 'elevated', 'outlined', 'text'];
+const SIZES: SizeOption[] = [
+  'unset',
+  'extra-small',
+  'small',
+  'medium',
+  'large',
+  'extra-large',
+];
+const SHAPES: ShapeOption[] = ['unset', 'round', 'square'];
+const ICON_POSITIONS: IconPosition[] = ['leading', 'trailing'];
+
+function OptionRow<T extends string>({
+  label,
+  value,
+  options,
+  onChange,
+}: {
+  label: string;
+  value: T;
+  options: readonly T[];
+  onChange: (value: T) => void;
+}) {
+  return (
+    <View style={styles.optionRow}>
+      <Text variant="labelLarge" style={styles.optionLabel}>
+        {label}
+      </Text>
+      <View style={styles.chips}>
+        {options.map((option) => (
+          <Chip
+            key={option}
+            mode="outlined"
+            compact
+            showSelectedOverlay
+            selected={value === option}
+            onPress={() => onChange(option)}
+            style={styles.chip}
+          >
+            {option}
+          </Chip>
+        ))}
+      </View>
+    </View>
+  );
+}
+
+const SwitchRow = ({
+  label,
+  value,
+  onValueChange,
+}: {
+  label: string;
+  value: boolean;
+  onValueChange: (value: boolean) => void;
+}) => (
+  <View style={styles.switchRow}>
+    <Text variant="labelLarge">{label}</Text>
+    <Switch value={value} onValueChange={onValueChange} />
+  </View>
+);
+
 const ButtonExample = () => {
   const theme = useTheme();
-
   const color = theme.colors.inversePrimary;
 
+  // Playground state.
+  const [mode, setMode] = React.useState<Mode>('filled');
+  const [size, setSize] = React.useState<SizeOption>('unset');
+  const [shape, setShape] = React.useState<ShapeOption>('unset');
+  const [iconPosition, setIconPosition] =
+    React.useState<IconPosition>('leading');
+  const [showIcon, setShowIcon] = React.useState(false);
+  const [disabled, setDisabled] = React.useState(false);
+  const [loading, setLoading] = React.useState(false);
+  const [selected, setSelected] = React.useState(false);
+  const [compact, setCompact] = React.useState(false);
+
+  // Selected state for the static toggle showcase below.
   const [selectedToggles, setSelectedToggles] = React.useState<
     Record<string, boolean>
   >({});
-
   const toggle = (key: string) =>
     setSelectedToggles((prev) => ({ ...prev, [key]: !prev[key] }));
 
   return (
     <ScreenWrapper>
-      <List.Section title="Text button (text)">
-        <View style={styles.row}>
-          <Button onPress={() => {}} style={styles.button} label="Default" />
-          <Button
-            textColor={color}
-            onPress={() => {}}
-            style={styles.button}
-            label="Custom"
-          />
-          <Button
-            disabled
-            onPress={() => {}}
-            style={styles.button}
-            label="Disabled"
-          />
-          <Button
-            icon="camera"
-            onPress={() => {}}
-            style={styles.button}
-            label="Icon"
-          />
-          <Button
-            loading
-            onPress={() => {}}
-            style={styles.button}
-            label="Loading"
-          />
-          <Button
-            icon="camera"
-            onPress={() => {}}
-            style={styles.button}
-            iconPosition="trailing"
-            label="Icon right"
-          />
-        </View>
-      </List.Section>
-      <List.Section title="Contained-tonal button (tonal)">
-        <View style={styles.row}>
-          <Button
-            mode="tonal"
-            onPress={() => {}}
-            style={styles.button}
-            label="Default"
-          />
-          <Button
-            mode="tonal"
-            buttonColor={color}
-            onPress={() => {}}
-            style={styles.button}
-            label="Custom"
-          />
-          <Button
-            mode="tonal"
-            disabled
-            onPress={() => {}}
-            style={styles.button}
-            label="Disabled"
-          />
-          <Button
-            mode="tonal"
-            icon="camera"
-            onPress={() => {}}
-            style={styles.button}
-            label="Icon"
-          />
-          <Button
-            mode="tonal"
-            loading
-            onPress={() => {}}
-            style={styles.button}
-            label="Loading"
-          />
-          <Button
-            mode="tonal"
-            icon="camera"
-            onPress={() => {}}
-            style={styles.button}
-            iconPosition="trailing"
-            label="Icon right"
+      <List.Section title="Playground">
+        <View style={styles.preview}>
+          <Button
+            mode={mode}
+            size={size === 'unset' ? undefined : size}
+            shape={shape === 'unset' ? undefined : shape}
+            iconPosition={iconPosition}
+            icon={showIcon ? 'camera' : undefined}
+            disabled={disabled}
+            loading={loading}
+            selected={selected}
+            // `compact` only affects the legacy (unset-size) button; the size
+            // tokens own spacing once a size is set.
+            compact={size === 'unset' && compact}
+            onPress={() => {}}
+            label="Play me"
           />
         </View>
+
+        <OptionRow
+          label="Mode"
+          value={mode}
+          options={MODES}
+          onChange={setMode}
+        />
+        <OptionRow
+          label="Size"
+          value={size}
+          options={SIZES}
+          onChange={setSize}
+        />
+        <OptionRow
+          label="Shape"
+          value={shape}
+          options={SHAPES}
+          onChange={setShape}
+        />
+
+        <SwitchRow
+          label="Show icon"
+          value={showIcon}
+          onValueChange={setShowIcon}
+        />
+        {showIcon && (
+          <OptionRow
+            label="Icon position"
+            value={iconPosition}
+            options={ICON_POSITIONS}
+            onChange={setIconPosition}
+          />
+        )}
+        <SwitchRow
+          label="Disabled"
+          value={disabled}
+          onValueChange={setDisabled}
+        />
+        <SwitchRow label="Loading" value={loading} onValueChange={setLoading} />
+        <SwitchRow
+          label="Selected"
+          value={selected}
+          onValueChange={setSelected}
+        />
+        {/* `compact` is a no-op once a size is set, so only offer it for unset. */}
+        {size === 'unset' && (
+          <SwitchRow
+            label="Compact"
+            value={compact}
+            onValueChange={setCompact}
+          />
+        )}
       </List.Section>
-      <List.Section title="Outlined button (outlined)">
+
+      <List.Section title="Modes">
         <View style={styles.row}>
-          <Button
-            mode="outlined"
-            onPress={() => {}}
-            style={styles.button}
-            label="Default"
-          />
-          <Button
-            mode="outlined"
-            textColor={color}
-            onPress={() => {}}
-            style={styles.button}
-            label="Custom"
-          />
-          <Button
-            mode="outlined"
-            disabled
-            onPress={() => {}}
-            style={styles.button}
-            label="Disabled"
-          />
-          <Button
-            mode="outlined"
-            icon="camera"
-            onPress={() => {}}
-            style={styles.button}
-            label="Icon"
-          />
-          <Button
-            mode="outlined"
-            loading
-            onPress={() => {}}
-            style={styles.button}
-            label="Loading"
-          />
-          <Button
-            mode="outlined"
-            icon="camera"
-            onPress={() => {}}
-            style={styles.button}
-            iconPosition="trailing"
-            label="Icon right"
-          />
+          {MODES.map((m) => (
+            <Button
+              key={m}
+              mode={m}
+              onPress={() => {}}
+              style={styles.button}
+              label={m}
+            />
+          ))}
         </View>
       </List.Section>
-      <List.Section title="Contained button (filled)">
+
+      <List.Section title="States">
         <View style={styles.row}>
           <Button
             mode="filled"
             onPress={() => {}}
             style={styles.button}
-            label="Default"
-          />
-          <Button
-            mode="filled"
-            buttonColor={color}
-            onPress={() => {}}
-            style={styles.button}
-            label="Custom"
+            label="Enabled"
           />
           <Button
             mode="filled"
@@ -169,13 +204,6 @@ const ButtonExample = () => {
             style={styles.button}
             label="Disabled"
           />
-          <Button
-            mode="filled"
-            icon="camera"
-            onPress={() => {}}
-            style={styles.button}
-            label="Icon"
-          />
           <Button
             mode="filled"
             loading
@@ -183,64 +211,76 @@ const ButtonExample = () => {
             style={styles.button}
             label="Loading"
           />
-          <Button
-            mode="filled"
-            icon="camera"
-            onPress={() => {}}
-            style={styles.button}
-            iconPosition="trailing"
-            label="Icon right"
-          />
         </View>
       </List.Section>
-      <List.Section title="Elevated button (elevated)">
+
+      <List.Section title="Size (expressive)">
+        <View style={styles.row}>
+          {SIZES.filter(
+            (s): s is Exclude<SizeOption, 'unset'> => s !== 'unset'
+          ).map((s) => (
+            <Button
+              key={s}
+              mode="filled"
+              size={s}
+              icon="star"
+              onPress={() => {}}
+              style={styles.button}
+              label={s}
+            />
+          ))}
+        </View>
+      </List.Section>
+
+      <List.Section title="Shape (expressive)">
+        {(['round', 'square'] as const).map((shapeVariant) => (
+          <View key={shapeVariant} style={styles.row}>
+            {(['extra-small', 'small', 'medium', 'large'] as const).map((s) => (
+              <Button
+                key={`${shapeVariant}-${s}`}
+                mode="outlined"
+                size={s}
+                shape={shapeVariant}
+                onPress={() => {}}
+                style={styles.button}
+                label={`${s} ${shapeVariant}`}
+              />
+            ))}
+          </View>
+        ))}
+      </List.Section>
+
+      <List.Section title="Toggle (expressive)">
+        <View style={styles.row}>
+          {(['outlined', 'text', 'tonal'] as const).map((m) => {
+            const key = `toggle-${m}`;
+            const isSelected = !!selectedToggles[key];
+            return (
+              <Button
+                key={key}
+                mode={m}
+                size="small"
+                shape="round"
+                selected={isSelected}
+                onPress={() => toggle(key)}
+                style={styles.button}
+                icon={isSelected ? 'check' : 'plus'}
+                label={m}
+              />
+            );
+          })}
+        </View>
+      </List.Section>
+
+      <List.Section title="Custom">
         <View style={styles.row}>
           <Button
-            mode="elevated"
-            onPress={() => {}}
-            style={styles.button}
-            label="Default"
-          />
-          <Button
-            mode="elevated"
+            mode="filled"
             buttonColor={color}
             onPress={() => {}}
             style={styles.button}
-            label="Custom"
-          />
-          <Button
-            mode="elevated"
-            disabled
-            onPress={() => {}}
-            style={styles.button}
-            label="Disabled"
-          />
-          <Button
-            mode="elevated"
-            icon="camera"
-            onPress={() => {}}
-            style={styles.button}
-            label="Icon"
+            label="Custom color"
           />
-          <Button
-            mode="elevated"
-            loading
-            onPress={() => {}}
-            style={styles.button}
-            label="Loading"
-          />
-          <Button
-            mode="elevated"
-            icon="camera"
-            onPress={() => {}}
-            style={styles.button}
-            iconPosition="trailing"
-            label="Icon right"
-          />
-        </View>
-      </List.Section>
-      <List.Section title="Custom">
-        <View style={styles.row}>
           <Button
             mode="outlined"
             icon={{
@@ -252,17 +292,14 @@ const ButtonExample = () => {
           />
           <Button
             mode="outlined"
-            icon={require('../../assets/images/favorite.png')}
-            onPress={() => {}}
-            style={styles.button}
-            label="Required asset"
-          />
-          <Button
-            mode="outlined"
-            icon={({ size }) => (
+            icon={({ size: iconSize }) => (
               <Image
                 source={require('../../assets/images/chameleon.jpg')}
-                style={{ width: size, height: size, borderRadius: size / 2 }}
+                style={{
+                  width: iconSize,
+                  height: iconSize,
+                  borderRadius: iconSize / 2,
+                }}
                 accessibilityIgnoresInvertColors
               />
             )}
@@ -275,15 +312,8 @@ const ButtonExample = () => {
             mode="outlined"
             onPress={() => {}}
             style={styles.button}
-            labelStyle={[styles.fontStyles, styles.md3FontStyles]}
-            label="Custom Font"
-          />
-          <Button
-            mode="outlined"
-            onPress={() => {}}
-            style={styles.button}
-            labelStyle={theme.fonts.titleLarge}
-            label="Custom text"
+            labelStyle={styles.fontStyles}
+            label="Custom font"
           />
           <Button
             mode="outlined"
@@ -291,127 +321,16 @@ const ButtonExample = () => {
             style={styles.customRadius}
             label="Custom radius"
           />
-          <Button
-            mode="filled"
-            onPress={() => {}}
-            style={styles.noRadius}
-            label="Without radius"
-          />
-          <Button
-            mode="tonal"
-            onPress={() => {}}
-            style={{ borderRadius: styles.customRadiusAndPadding.borderRadius }}
-            contentStyle={styles.customRadiusAndPadding}
-            label="Custom radius and padding"
-          />
         </View>
-
         <View style={styles.row}>
           <Button
             mode="filled"
             onPress={() => {}}
-            style={styles.flexGrow1Button}
-            label="flex-grow: 1"
-          />
-        </View>
-        <View style={styles.row}>
-          <Button
-            mode="filled"
-            onPress={() => {}}
-            style={styles.width100PercentButton}
+            style={styles.fullWidthButton}
             label="width: 100%"
           />
         </View>
       </List.Section>
-      <List.Section title="Compact">
-        <View style={styles.row}>
-          {(['text', 'outlined', 'filled', 'elevated', 'tonal'] as const).map(
-            (mode) => {
-              return (
-                <Button
-                  key={mode}
-                  mode={mode}
-                  compact
-                  onPress={() => {}}
-                  style={styles.button}
-                  icon="camera"
-                  label={`Compact ${mode}`}
-                />
-              );
-            }
-          )}
-        </View>
-      </List.Section>
-      <List.Section title="Size (expressive)">
-        <View style={styles.row}>
-          {(
-            ['extra-small', 'small', 'medium', 'large', 'extra-large'] as const
-          ).map((size) => (
-            <Button
-              key={size}
-              mode="filled"
-              size={size}
-              icon="star"
-              onPress={() => {}}
-              style={styles.button}
-              label={size}
-            />
-          ))}
-        </View>
-      </List.Section>
-      <List.Section title="Shape (expressive)">
-        <View style={styles.row}>
-          {(['extra-small', 'small', 'medium', 'large'] as const).map(
-            (size) => (
-              <Button
-                key={`round-${size}`}
-                mode="outlined"
-                size={size}
-                shape="round"
-                onPress={() => {}}
-                style={styles.button}
-                label={`${size} round`}
-              />
-            )
-          )}
-        </View>
-        <View style={styles.row}>
-          {(['extra-small', 'small', 'medium', 'large'] as const).map(
-            (size) => (
-              <Button
-                key={`square-${size}`}
-                mode="outlined"
-                size={size}
-                shape="square"
-                onPress={() => {}}
-                style={styles.button}
-                label={`${size} square`}
-              />
-            )
-          )}
-        </View>
-      </List.Section>
-      <List.Section title="Toggle (expressive)">
-        <View style={styles.row}>
-          {(['outlined', 'text', 'tonal'] as const).map((mode) => {
-            const key = `toggle-${mode}`;
-            const selected = !!selectedToggles[key];
-            return (
-              <Button
-                key={key}
-                mode={mode}
-                size="small"
-                shape="round"
-                selected={selected}
-                onPress={() => toggle(key)}
-                style={styles.button}
-                icon={selected ? 'check' : 'plus'}
-                label={mode}
-              />
-            );
-          })}
-        </View>
-      </List.Section>
     </ScreenWrapper>
   );
 };
@@ -419,6 +338,34 @@ const ButtonExample = () => {
 ButtonExample.title = 'Button';
 
 const styles = StyleSheet.create({
+  preview: {
+    minHeight: 160,
+    alignItems: 'center',
+    justifyContent: 'center',
+    paddingVertical: 16,
+  },
+  optionRow: {
+    paddingHorizontal: 16,
+    paddingVertical: 4,
+  },
+  optionLabel: {
+    marginBottom: 8,
+  },
+  chips: {
+    flexDirection: 'row',
+    flexWrap: 'wrap',
+    gap: 8,
+  },
+  chip: {
+    marginBottom: 4,
+  },
+  switchRow: {
+    flexDirection: 'row',
+    alignItems: 'center',
+    justifyContent: 'space-between',
+    paddingHorizontal: 16,
+    paddingVertical: 8,
+  },
   row: {
     flexDirection: 'row',
     flexWrap: 'wrap',
@@ -429,34 +376,20 @@ const styles = StyleSheet.create({
   button: {
     margin: 4,
   },
-  md3FontStyles: {
-    lineHeight: 32,
-  },
   fontStyles: {
     fontWeight: '800',
-    fontSize: 24,
-  },
-  flexGrow1Button: {
-    flexGrow: 1,
-    marginTop: 10,
-  },
-  width100PercentButton: {
-    width: '100%',
-    marginTop: 10,
+    fontSize: 20,
   },
   customRadius: {
+    margin: 4,
     borderTopLeftRadius: 16,
     borderTopRightRadius: 0,
     borderBottomLeftRadius: 0,
     borderBottomRightRadius: 16,
   },
-  noRadius: {
-    borderRadius: 0,
-  },
-  customRadiusAndPadding: {
-    borderRadius: 4,
-    paddingHorizontal: 12,
-    paddingVertical: 6,
+  fullWidthButton: {
+    width: '100%',
+    marginTop: 10,
   },
 });
 

From 48a0132a9f3db8fc4bf3bb042c22828ef301d2a5 Mon Sep 17 00:00:00 2001
From: Aziz Becha <aziz07becha@gmail.com>
Date: Thu, 21 May 2026 01:22:28 +0100
Subject: [PATCH 24/24] docs(button): update for filled/tonal modes and
 outlined tokens

Update the Button doc data sources to match the v6 API: rename the
contained/contained-tonal color + screenshot entries to filled/tonal, set the
outlined label to onSurfaceVariant, and switch mode="contained" to
mode="filled" in the react-navigation and ripple-effect guides. The Button.mdx
page is generated from these sources plus the component JSDoc.
---
 docs/docs/guides/09-react-navigation.md       |  2 +-
 docs/docs/guides/11-ripple-effect.md          |  2 +-
 docs/src/data/screenshots.js                  |  8 ++++----
 docs/src/data/themeColors.js                  | 20 +++++++++----------
 docs/src/utils/__tests__/themeColors.test.tsx | 20 +++++++++----------
 5 files changed, 26 insertions(+), 26 deletions(-)

diff --git a/docs/docs/guides/09-react-navigation.md b/docs/docs/guides/09-react-navigation.md
index c37bf2bad9..1213f98c35 100644
--- a/docs/docs/guides/09-react-navigation.md
+++ b/docs/docs/guides/09-react-navigation.md
@@ -87,7 +87,7 @@ function HomeScreen({ navigation }) {
     <View style={style.container}>
       <Text>Home Screen</Text>
       <Button
-        mode="contained"
+        mode="filled"
         onPress={() => navigation.navigate('Details')}
         label="Go to details"
       />
diff --git a/docs/docs/guides/11-ripple-effect.md b/docs/docs/guides/11-ripple-effect.md
index fcdb1e70a4..d4501643e6 100644
--- a/docs/docs/guides/11-ripple-effect.md
+++ b/docs/docs/guides/11-ripple-effect.md
@@ -18,7 +18,7 @@ The `rippleColor` prop is available for every pressable component which allows y
 <Button
   rippleColor="#FF000020"
   icon="camera"
-  mode="contained"
+  mode="filled"
   onPress={() => console.log('Pressed')}
   label="Press me"
 />
diff --git a/docs/src/data/screenshots.js b/docs/src/data/screenshots.js
index c1afa99a6a..bc20787a92 100644
--- a/docs/src/data/screenshots.js
+++ b/docs/src/data/screenshots.js
@@ -22,11 +22,11 @@ const screenshots = {
   BottomNavigation: 'screenshots/bottom-navigation.gif',
   'BottomNavigation.Bar': 'screenshots/bottom-navigation-tabs.jpg',
   Button: {
-    text: 'screenshots/button-1.png',
-    outlined: 'screenshots/button-2.png',
-    contained: 'screenshots/button-3.png',
+    filled: 'screenshots/button-3.png',
+    tonal: 'screenshots/button-5.png',
     elevated: 'screenshots/button-4.png',
-    'contained-tonal': 'screenshots/button-5.png',
+    outlined: 'screenshots/button-2.png',
+    text: 'screenshots/button-1.png',
   },
   Card: {
     elevated: 'screenshots/card-1.png',
diff --git a/docs/src/data/themeColors.js b/docs/src/data/themeColors.js
index f12b955341..55f531c45f 100644
--- a/docs/src/data/themeColors.js
+++ b/docs/src/data/themeColors.js
@@ -47,20 +47,20 @@ const themeColors = {
   },
   Button: {
     active: {
-      elevated: {
-        backgroundColor: 'theme.colors.elevation.level1',
-        textColor: 'theme.colors.primary',
-      },
-      contained: {
+      filled: {
         backgroundColor: 'theme.colors.primary',
         textColor: 'theme.colors.onPrimary',
       },
-      'contained-tonal': {
+      tonal: {
         backgroundColor: 'theme.colors.secondaryContainer',
         textColor: 'theme.colors.onSecondaryContainer',
       },
-      outlined: {
+      elevated: {
+        backgroundColor: 'theme.colors.elevation.level1',
         textColor: 'theme.colors.primary',
+      },
+      outlined: {
+        textColor: 'theme.colors.onSurfaceVariant',
         borderColor: 'theme.colors.outline',
       },
       text: {
@@ -68,15 +68,15 @@ const themeColors = {
       },
     },
     disabled: {
-      elevated: {
+      filled: {
         backgroundColor: 'theme.colors.surfaceDisabled',
         textColor: 'theme.colors.onSurfaceDisabled',
       },
-      contained: {
+      tonal: {
         backgroundColor: 'theme.colors.surfaceDisabled',
         textColor: 'theme.colors.onSurfaceDisabled',
       },
-      'contained-tonal': {
+      elevated: {
         backgroundColor: 'theme.colors.surfaceDisabled',
         textColor: 'theme.colors.onSurfaceDisabled',
       },
diff --git a/docs/src/utils/__tests__/themeColors.test.tsx b/docs/src/utils/__tests__/themeColors.test.tsx
index 4803ea7a6b..668f1a0bbd 100644
--- a/docs/src/utils/__tests__/themeColors.test.tsx
+++ b/docs/src/utils/__tests__/themeColors.test.tsx
@@ -2,20 +2,20 @@ import { getMaxNestedLevel, getUniqueNestedKeys } from '../themeColors';
 
 const Button = {
   active: {
-    elevated: {
-      backgroundColor: 'theme.colors.elevation.level1',
-      color: 'theme.colors.primary',
-    },
-    contained: {
+    filled: {
       backgroundColor: 'theme.colors.primary',
       color: 'theme.colors.onPrimary',
     },
-    'contained-tonal': {
+    tonal: {
       backgroundColor: 'theme.colors.secondaryContainer',
       color: 'theme.colors.onSecondaryContainer',
     },
-    outlined: {
+    elevated: {
+      backgroundColor: 'theme.colors.elevation.level1',
       color: 'theme.colors.primary',
+    },
+    outlined: {
+      color: 'theme.colors.onSurfaceVariant',
       borderColor: 'theme.colors.outline',
     },
     text: {
@@ -23,15 +23,15 @@ const Button = {
     },
   },
   disabled: {
-    elevated: {
+    filled: {
       backgroundColor: 'theme.colors.surfaceDisabled',
       color: 'theme.colors.onSurfaceDisabled',
     },
-    contained: {
+    tonal: {
       backgroundColor: 'theme.colors.surfaceDisabled',
       color: 'theme.colors.onSurfaceDisabled',
     },
-    'contained-tonal': {
+    elevated: {
       backgroundColor: 'theme.colors.surfaceDisabled',
       color: 'theme.colors.onSurfaceDisabled',
     },