chore: Improve button docs (#230)

* chore: Improve button docs

* Fix responsive issues

* Fix typo

Author: hcopp

apps/docs/docs/components/inputs/Button/_mobileExamples.mdx

@@ -1,72 +1,215 @@
-### Primary Button
+Buttons allow users to take actions and make choices with a single tap. They communicate what action will occur when the user interacts with them.
 
-Use primary buttons for high emphasis actions. These buttons have the most visual impact and should be reserved for the most important, final actions that complete a flow, like Save, Join now, or Confirm. Try to use one per screen. Multiple primary buttons make it confusing for the user to understand what action they should take.
+## Basics
+
+The only required prop is `children`, which is the button's label. Buttons default to the `primary` variant.
 
 ```jsx
-<Button onPress={console.log} variant="primary">
-  Primary
-</Button>
+<Button onPress={console.log}>Get started</Button>
 ```
 
-### Secondary Button
+## Variants
 
-These buttons have a medium level of emphasis that should be used for non-critical actions. Secondary buttons can be used on pages without restrictions and works well for multiple actions of equal weight. They can be used in conjunction with a Primary Button or independently.
+Use variants to communicate the importance and intent of an action.
+
+- **Primary** — High emphasis for main actions like "Save" or "Confirm". Limit to one per screen.
+- **Secondary** — Medium emphasis for multiple actions of equal weight.
+- **Tertiary** — High contrast with inverted background.
+- **Negative** — Destructive actions that can't be undone. Use sparingly.
 
 ```jsx
-<Button onPress={console.log} variant="secondary">
-  Secondary
-</Button>
+<HStack gap={2} flexWrap="wrap">
+  <Button onPress={console.log} variant="primary">
+    Primary
+  </Button>
+  <Button onPress={console.log} variant="secondary">
+    Secondary
+  </Button>
+  <Button onPress={console.log} variant="tertiary">
+    Tertiary
+  </Button>
+  <Button onPress={console.log} variant="negative">
+    Negative
+  </Button>
+</HStack>
 ```
 
-### Tertiary Button
+### Transparent
 
-These buttons provide high contrast with the background through the use of the themable inverted background color.
+Use transparent buttons for supplementary actions with lower prominence. The container is only visible on interaction. Works with any variant.
 
 ```jsx
-<Button onPress={console.log} variant="tertiary">
-  Tertiary
-</Button>
+<HStack gap={2}>
+  <Button onPress={console.log} transparent>
+    Primary
+  </Button>
+  <Button onPress={console.log} variant="secondary" transparent>
+    Secondary
+  </Button>
+  <Button onPress={console.log} variant="negative" transparent>
+    Negative
+  </Button>
+</HStack>
 ```
 
-### Negative Button
+## States
+
+### Loading
 
-Negative buttons should be used sparingly for destructive actions that will result in data loss, can’t be undone, or will have significant consequences. They commonly appear in confirmation dialogs as the final confirmation before deleting.
+Use the `loading` prop to indicate an action is in progress. The button becomes non-interactive and displays a spinner while preserving its width.
 
 ```jsx
-<Button onPress={console.log} variant="negative">
-  Negative
-</Button>
+<HStack gap={2}>
+  <Button onPress={console.log} loading>
+    Save changes
+  </Button>
+  <Button onPress={console.log} variant="secondary" loading>
+    Submit
+  </Button>
+</HStack>
 ```
 
-### Transparent Button
+### Disabled
 
-Transparent buttons are used for less important actions that are supplementary. These buttons have lower prominence since its container is not visible until the button is interacted with. Transparent buttons are frequently used on Cards and can be placed on a variety of backgrounds.
+Use the `disabled` prop to prevent interaction and indicate the action is unavailable.
 
 ```jsx
 <HStack gap={2}>
-  <Button onPress={console.log} transparent>
+  <Button disabled onPress={console.log}>
     Primary
   </Button>
-  <Button onPress={console.log} variant="secondary" transparent>
+  <Button disabled onPress={console.log} variant="secondary">
     Secondary
   </Button>
-  <Button onPress={console.log} variant="negative" transparent>
+  <Button disabled onPress={console.log} variant="negative">
     Negative
   </Button>
 </HStack>
 ```
 
-### Buttons with end icon
+## Sizing
+
+### Compact
 
-You can add an icon after the label of a button.
+Use `compact` for smaller buttons with reduced padding. Useful in dense UIs or alongside other compact elements.
 
 ```jsx
-<HStack gap={2}>
-  <Button onPress={console.log} endIcon="add" endIconActive variant="secondary" compact>
-    Select file
+<HStack gap={2} alignItems="center">
+  <Button onPress={console.log} compact>
+    Compact
+  </Button>
+  <Button onPress={console.log}>Default</Button>
+</HStack>
+```
+
+### Block
+
+Use `block` to make the button expand to fill its container width.
+
+```jsx
+<VStack gap={2}>
+  <Button onPress={console.log} block>
+    Full width button
+  </Button>
+  <Button onPress={console.log} variant="secondary" block>
+    Another full width
   </Button>
+</VStack>
+```
+
+## Icons
+
+### End Icon
+
+Add an icon after the label to provide additional context or indicate direction.
+
+```jsx
+<HStack gap={2}>
   <Button onPress={console.log} endIcon="forwardArrow" variant="secondary" compact>
     See more
   </Button>
+  <Button onPress={console.log} endIcon="externalLink" variant="secondary" compact>
+    Open link
+  </Button>
+</HStack>
+```
+
+### Start Icon
+
+Add an icon before the label to reinforce the action.
+
+```jsx
+<HStack gap={2}>
+  <Button onPress={console.log} startIcon="add" startIconActive variant="secondary" compact>
+    Add item
+  </Button>
+  <Button onPress={console.log} startIcon="download" variant="secondary" compact>
+    Download
+  </Button>
+</HStack>
+```
+
+### Full Width with Icons
+
+When using `block` with icons, the content automatically spreads across the button width.
+
+```jsx
+<Button onPress={console.log} startIcon="wallet" endIcon="forwardArrow" variant="secondary" block>
+  Connect wallet
+</Button>
+```
+
+## Accessibility
+
+Buttons automatically use their `children` as the accessible label. For buttons with only icons or ambiguous labels, provide an `accessibilityLabel`.
+
+```jsx
+<Button onPress={handleClose} accessibilityLabel="Close dialog">
+  ×
+</Button>
+```
+
+## Composed Examples
+
+### Confirmation Dialog
+
+A common pattern using primary and secondary buttons together.
+
+```jsx
+<HStack gap={2} justifyContent="flex-end">
+  <Button onPress={console.log} variant="secondary" transparent>
+    Cancel
+  </Button>
+  <Button onPress={console.log}>Confirm</Button>
+</HStack>
+```
+
+### Destructive Confirmation
+
+Use negative buttons with a secondary cancel option for destructive actions.
+
+```jsx
+<HStack gap={2} justifyContent="flex-end">
+  <Button onPress={console.log} variant="secondary" transparent>
+    Cancel
+  </Button>
+  <Button onPress={console.log} variant="negative">
+    Delete
+  </Button>
 </HStack>
 ```
+
+### Form Actions
+
+A full-width primary action with a compact secondary option.
+
+```jsx
+<VStack gap={2}>
+  <Button onPress={console.log} block>
+    Create account
+  </Button>
+  <Button onPress={console.log} variant="secondary" transparent block>
+    Already have an account? Sign in
+  </Button>
+</VStack>
+```