docs: TextButton migration

packages/design-system-react-native/MIGRATION.md

@@ -10,6 +10,7 @@ This guide provides detailed instructions for migrating your project from one ve
   - [ButtonFilter Component](#buttonfilter-component)
   - [ButtonHero Component](#buttonhero-component)
   - [ButtonIcon Component](#buttonicon-component)
+  - [TextButton Component (ButtonLink)](#textbutton-component-buttonlink)
   - [BottomSheet Component](#bottomsheet-component)
   - [BottomSheetHeader Component](#bottomsheetheader-component)
   - [BottomSheetFooter Component](#bottomsheetfooter-component)
@@ -1062,6 +1063,125 @@ After (Design System):
 />
 ```
 
+### TextButton Component (ButtonLink)
+
+The legacy `ButtonLink` component is replaced by **two** design system components depending on the use case:
+
+- **`TextButton`** — for inline links within text flows (the primary replacement)
+- **`Button` with `variant={ButtonVariant.Tertiary}`** — for standalone link-style buttons with icons, full width, or other button-like affordances
+
+`TextButton` is a `Text`-based component (not a `Pressable`/`TouchableOpacity`). It only renders text — no icons, no size variants, no width control.
+
+#### Breaking Changes
+
+##### Import Path
+
+| Mobile Pattern                                                                                 | Design System Migration                                             |
+| ---------------------------------------------------------------------------------------------- | ------------------------------------------------------------------- |
+| `import ButtonLink from '.../component-library/components/Buttons/Button/variants/ButtonLink'` | `import { TextButton } from '@metamask/design-system-react-native'` |
+
+##### Content Model: `label` → `children`
+
+| Mobile Pattern                      | Design System Migration               |
+| ----------------------------------- | ------------------------------------- |
+| `<ButtonLink label="Learn more" />` | `<TextButton>Learn more</TextButton>` |
+| `<ButtonLink label={variable} />`   | `<TextButton>{variable}</TextButton>` |
+
+##### Size Removed
+
+The legacy `ButtonLink` inherited `ButtonSize` with a default of `ButtonSize.Auto`. The design system `TextButton` has no `size` prop — control typography via the `variant` prop instead.
+
+| Mobile Pattern           | Design System Migration                  |
+| ------------------------ | ---------------------------------------- |
+| `size={ButtonSize.Auto}` | Remove — default behavior                |
+| `size={ButtonSize.Lg}`   | `variant={TextVariant.BodyLg}`           |
+| `size={ButtonSize.Sm}`   | `variant={TextVariant.BodySm}`           |
+| `size={ButtonSize.Md}`   | `variant={TextVariant.BodyMd}` (default) |
+
+##### `isDanger` Removed
+
+The legacy `ButtonLink` supported `isDanger` for error-colored text. `TextButton` does not have this prop — it always uses primary color. For error-state links, use `Button` with `variant={ButtonVariant.Tertiary}` and `isDanger`.
+
+##### `labelTextVariant` → `variant`
+
+| Mobile Pattern                                | Design System Migration                                           |
+| --------------------------------------------- | ----------------------------------------------------------------- |
+| `labelTextVariant={TextVariant.BodyMDMedium}` | `variant={TextVariant.BodyMd}` + `fontWeight={FontWeight.Medium}` |
+
+##### `onPress` Signature
+
+All press props (`onPress`, `onPressIn`, `onPressOut`) keep the same `GestureResponderEvent` type. The behavioral difference is that the legacy non-auto `ButtonBase` (`TouchableOpacity`) provided animated press feedback and handled `isDisabled`, whereas `TextButton` uses `Text` press handling throughout.
+
+##### Removed Props
+
+| Mobile Prop                     | Design System Migration                                           |
+| ------------------------------- | ----------------------------------------------------------------- |
+| `isDanger`                      | Use `Button` with `variant={ButtonVariant.Tertiary}` + `isDanger` |
+| `startIconName` / `endIconName` | Use `Button` with `variant={ButtonVariant.Tertiary}`              |
+| `width` / `isFullWidth`         | Use `Button` with `variant={ButtonVariant.Tertiary}`              |
+| `isDisabled`                    | Not available on `TextButton` — use `Button` if needed            |
+
+#### Migration Examples
+
+##### Inline "show more" link
+
+Before (Mobile):
+
+```tsx
+import ButtonLink from '../../../../component-library/components/Buttons/Button/variants/ButtonLink';
+
+<ButtonLink
+  onPress={toggleContent}
+  label={isExpanded ? 'Show less' : 'Show more'}
+/>;
+```
+
+After (Design System):
+
+```tsx
+import { TextButton } from '@metamask/design-system-react-native';
+
+<TextButton onPress={toggleContent}>
+  {isExpanded ? 'Show less' : 'Show more'}
+</TextButton>;
+```
+
+##### Link variant in a Button group → Tertiary Button
+
+Before (Mobile):
+
+```tsx
+import Button, {
+  ButtonVariants,
+  ButtonSize,
+} from '../../../../component-library/components/Buttons/Button';
+
+<Button
+  variant={ButtonVariants.Link}
+  size={ButtonSize.Lg}
+  label={strings('button.learn_more')}
+  onPress={handleLearnMore}
+/>;
+```
+
+After (Design System):
+
+```tsx
+import {
+  Button,
+  ButtonVariant,
+  ButtonSize,
+} from '@metamask/design-system-react-native';
+
+<Button
+  variant={ButtonVariant.Tertiary}
+  size={ButtonSize.Lg}
+  onPress={handleLearnMore}
+>
+  {strings('button.learn_more')}
+</Button>;
+```
+
 ### BottomSheet Component
 
 The `BottomSheet` component has two key breaking changes when migrating from the mobile component-library:

packages/design-system-react-native/src/components/TextButton/README.md

@@ -86,6 +86,10 @@ Style for the label, merged after design-token styles. Prefer `twClassName` with
 
 Other `Text` / React Native `Text` props are supported via `TextButtonProps` (see [`TextProps`](../Text/Text.types.ts)).
 
+## Migration from MetaMask Mobile Component Library
+
+Migrating from the legacy `ButtonLink` in `app/component-library/components/Buttons/Button/variants/ButtonLink`? See the [TextButton (ButtonLink) migration guide](../../../MIGRATION.md#textbutton-component-buttonlink) for the full prop mapping, `label` → `children`, and when to use `Button` with `variant={ButtonVariant.Tertiary}` instead.
+
 ## References
 
 [MetaMask Design System Guides](https://www.notion.so/MetaMask-Design-System-Guides-Design-f86ecc914d6b4eb6873a122b83c12940)