feat(DSYS-489): Migrate Text to ADR-0003 and ADR-0004

.cursor/rules/component-architecture.md

@@ -159,6 +159,35 @@ export {
 } from '@metamask/design-system-shared';
 ```
 
+## Where to Import Shared Types
+
+**Always import shared consts and types directly from `@metamask/design-system-shared`**, never through a sibling component's index.
+
+```tsx
+// ✅ Correct - import from shared (the owner)
+import { TextVariant } from '@metamask/design-system-shared';
+
+// ❌ Wrong - import through a sibling component's index
+import { TextVariant } from '../Text';
+```
+
+**Why not `../Text`?**
+
+Both `Input` and `Text` are _consumers_ of `TextVariant` — neither owns it. Importing through `../Text` creates:
+
+1. **False semantic coupling** — implies `Input` is built on top of `Text`, which it isn't
+2. **Fragile circular-dep risk** — if `Text` ever renders an `Input` internally, you get `Input → Text → Input 💥`
+3. **Misleading dependency graph** — obscures that the real source is `@metamask/design-system-shared`
+
+**The rule:**
+
+| What you need                                                      | Import from                                  |
+| ------------------------------------------------------------------ | -------------------------------------------- |
+| Shared const/type (`TextVariant`, `TextColor`, `FontWeight`, etc.) | `@metamask/design-system-shared`             |
+| A sibling component to render it                                   | `'../ComponentName'`                         |
+| A sibling component's platform-specific props type                 | `'../ComponentName'`                         |
+| A sibling component's mapping constants                            | `'../ComponentName/ComponentName.constants'` |
+
 ## Cross-Platform Consistency
 
 **Required consistency:**

apps/storybook-react/tailwind.config.js

@@ -4,6 +4,7 @@ const designSystemPreset = require('@metamask/design-system-tailwind-preset');
 module.exports = {
   presets: [designSystemPreset],
   content: [
+    '../../packages/design-system-shared/src/**/*.{js,jsx,ts,tsx}',
     '../../packages/design-system-react/src/**/*.{js,jsx,ts,tsx}',
     '../../packages/design-tokens/stories/**/*.{js,jsx,ts,tsx,mdx}',
     './src/**/*.{js,jsx,ts,tsx}',

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

@@ -17,6 +17,7 @@ This guide provides detailed instructions for migrating your project from one ve
   - [Icon Component](#icon-component)
   - [Checkbox Component](#checkbox-component)
 - [Version Updates](#version-updates)
+  - [From version 0.16.0 to 0.17.0](#from-version-0160-to-0170)
   - [From version 0.15.0 to 0.16.0](#from-version-0150-to-0160)
   - [From version 0.13.0 to 0.14.0](#from-version-0130-to-0140)
   - [From version 0.12.0 to 0.13.0](#from-version-0120-to-0130)
@@ -26,6 +27,40 @@ This guide provides detailed instructions for migrating your project from one ve
 
 ## Version Updates
 
+### From version 0.16.0 to 0.17.0
+
+#### Text: Typography const values moved to `@metamask/design-system-shared`
+
+`FontWeight`, `FontStyle`, `FontFamily`, `TextVariant`, and `TextColor` are now defined in `@metamask/design-system-shared` and re-exported from `@metamask/design-system-react-native`. All existing import paths through `@metamask/design-system-react-native` continue to work without change.
+
+#### `FontWeight` values changed
+
+**No migration likely needed.** `FontWeight` was a TypeScript `enum` before this release, so the underlying string values were inaccessible via the type system. Idiomatic usage (`fontWeight={FontWeight.Bold}`) continues to work without change — the TWRNC classmap handles the mapping internally.
+
+The values did change to semantic identifiers for cross-platform sharing:
+
+| Key                  | Before (0.16.0) | After (0.17.0) |
+| -------------------- | --------------- | -------------- |
+| `FontWeight.Bold`    | `'600'`         | `'bold'`       |
+| `FontWeight.Medium`  | `'500'`         | `'medium'`     |
+| `FontWeight.Regular` | `'400'`         | `'regular'`    |
+
+If you were comparing against the raw numeric string values directly, update to use the const member instead:
+
+```tsx
+// ❌ Rare: comparing against raw numeric string
+if (fontWeight === '600') { ... }
+
+// ✅ Use const member (works in both 0.16.0 and 0.17.0)
+if (fontWeight === FontWeight.Bold) { ... }
+```
+
+#### `TextColor` additions
+
+`TextColor` gains four hover-state keys that were previously web-only (`PrimaryDefaultHover`, `ErrorDefaultHover`, `SuccessDefaultHover`, `WarningDefaultHover`). These are non-breaking additions. Their JSDoc notes that hover does not exist as an interaction state on React Native — use the corresponding `*Pressed` variant instead.
+
+---
+
 ### From version 0.13.0 to 0.14.0
 
 #### BottomSheet navigation callback change

packages/design-system-react-native/src/components/BannerBase/BannerBase.tsx

@@ -1,3 +1,4 @@
+import { FontWeight, TextVariant } from '@metamask/design-system-shared';
 import React from 'react';
 import { GestureResponderEvent } from 'react-native';
 
@@ -6,10 +7,8 @@ import {
   BoxBackgroundColor,
   ButtonIconSize,
   ButtonSize,
-  FontWeight,
   BoxFlexDirection,
   IconName,
-  TextVariant,
 } from '../../types';
 import { Box } from '../Box';
 import { Button } from '../Button';

packages/design-system-react-native/src/components/Box/Box.stories.tsx

@@ -1,3 +1,4 @@
+import { TextColor } from '@metamask/design-system-shared';
 import type { Meta, StoryObj } from '@storybook/react-native';
 import React from 'react';
 import { ScrollView } from 'react-native';
@@ -9,7 +10,6 @@ import {
   BoxJustifyContent,
   BoxBackgroundColor,
   BoxBorderColor,
-  TextColor,
 } from '../../types';
 import { Text } from '../Text';
 

packages/design-system-react-native/src/components/Input/Input.constants.ts

@@ -1,7 +1,6 @@
+import { TextVariant } from '@metamask/design-system-shared';
 import { typography } from '@metamask/design-tokens';
 
-import { TextVariant } from '../../types';
-
 /**
  * Typographic metrics for Input: same tokens as `text-*` utilities but **without** `lineHeight`.
  * React Native `TextInput` aligns single-line text more predictably when line height is not set

packages/design-system-react-native/src/components/Input/Input.stories.tsx

@@ -1,9 +1,8 @@
+import { TextVariant } from '@metamask/design-system-shared';
 import type { Meta, StoryObj } from '@storybook/react-native';
 import { useEffect, useState } from 'react';
 import { View } from 'react-native';
 
-import { TextVariant } from '../../types';
-
 import { Input } from './Input';
 import type { InputProps } from './Input.types';
 

packages/design-system-react-native/src/components/Input/Input.test.tsx

@@ -1,3 +1,4 @@
+import { TextVariant } from '@metamask/design-system-shared';
 import {
   Theme,
   ThemeProvider,
@@ -11,8 +12,6 @@ import { Platform, TextInput } from 'react-native';
 import type { StyleProp, TextStyle } from 'react-native';
 import { create } from 'react-test-renderer';
 
-import { TextVariant } from '../../types';
-
 import { Input } from './Input';
 
 const TEST_ID = 'input';

packages/design-system-react-native/src/components/Input/Input.tsx

@@ -1,3 +1,4 @@
+import { FontFamily, TextVariant } from '@metamask/design-system-shared';
 import {
   Theme,
   useTailwind,
@@ -7,9 +8,8 @@ import { darkTheme, lightTheme } from '@metamask/design-tokens';
 import { forwardRef, useCallback, useMemo, useState } from 'react';
 import { Platform, TextInput } from 'react-native';
 
-import { FontFamily, TextVariant } from '../../types';
 import {
-  MAP_TEXT_VARIANT_FONTWEIGHT,
+  TWCLASSMAP_TEXT_VARIANT_FONTWEIGHT,
   TWCLASSMAP_TEXT_FONTWEIGHT,
 } from '../Text/Text.constants';
 
@@ -46,7 +46,7 @@ export const Input = forwardRef<TextInput, InputProps>(
       [theme],
     );
 
-    const finalFontWeight = MAP_TEXT_VARIANT_FONTWEIGHT[textVariant];
+    const finalFontWeight = TWCLASSMAP_TEXT_VARIANT_FONTWEIGHT[textVariant];
     const fontSuffix = TWCLASSMAP_TEXT_FONTWEIGHT[finalFontWeight];
     const fontClass = `font-${FontFamily.Default}${fontSuffix}`;
     const hasPlaceholder =

packages/design-system-react-native/src/components/Input/Input.types.ts

@@ -1,7 +1,6 @@
+import type { TextVariant } from '@metamask/design-system-shared';
 import type { TextInputProps } from 'react-native';
 
-import type { TextVariant } from '../../types';
-
 export type InputProps = Omit<
   TextInputProps,
   'editable' | 'value' | 'defaultValue'

packages/design-system-react-native/src/components/KeyValueColumn/KeyValueColumn.tsx

@@ -1,12 +1,11 @@
-import React from 'react';
-
 import {
-  ButtonIconSize,
   FontWeight,
-  IconColor,
   TextColor,
   TextVariant,
-} from '../../types';
+} from '@metamask/design-system-shared';
+import React from 'react';
+
+import { ButtonIconSize, IconColor } from '../../types';
 import { BoxColumn } from '../BoxColumn';
 import { BoxRow } from '../BoxRow';
 import { ButtonIcon } from '../ButtonIcon';

packages/design-system-react-native/src/components/KeyValueRow/KeyValueRow.tsx

@@ -1,14 +1,13 @@
-import { KeyValueRowVariant } from '@metamask/design-system-shared';
-import { useTailwind } from '@metamask/design-system-twrnc-preset';
-import React from 'react';
-
 import {
-  ButtonIconSize,
   FontWeight,
-  IconColor,
+  KeyValueRowVariant,
   TextColor,
   TextVariant,
-} from '../../types';
+} from '@metamask/design-system-shared';
+import { useTailwind } from '@metamask/design-system-twrnc-preset';
+import React from 'react';
+
+import { ButtonIconSize, IconColor } from '../../types';
 import { Box } from '../Box';
 import { BoxRow } from '../BoxRow';
 import { ButtonIcon } from '../ButtonIcon';

packages/design-system-react-native/src/components/Text/Text.constants.ts

@@ -1,6 +1,4 @@
-import { typography } from '@metamask/design-tokens';
-
-import { FontWeight, TextVariant } from '../../types';
+import { FontWeight, TextVariant } from '@metamask/design-system-shared';
 
 // Mappings
 export const TWCLASSMAP_TEXT_FONTWEIGHT: {
@@ -11,25 +9,21 @@ export const TWCLASSMAP_TEXT_FONTWEIGHT: {
   [FontWeight.Bold]: '-bold',
 };
 
-export const MAP_TEXT_VARIANT_FONTWEIGHT: {
+export const TWCLASSMAP_TEXT_VARIANT_FONTWEIGHT: {
   [key in TextVariant]: FontWeight;
 } = {
-  [TextVariant.DisplayLg]: typography.sDisplayLG.fontWeight as FontWeight,
-  [TextVariant.DisplayMd]: typography.sDisplayMD.fontWeight as FontWeight,
-  [TextVariant.HeadingLg]: typography.sHeadingLG.fontWeight as FontWeight,
-  [TextVariant.HeadingMd]: typography.sHeadingMD.fontWeight as FontWeight,
-  [TextVariant.HeadingSm]: typography.sHeadingSM.fontWeight as FontWeight,
-  [TextVariant.BodyLg]: typography.sBodyLGMedium.fontWeight as FontWeight,
-  [TextVariant.BodyMd]: typography.sBodyMD.fontWeight as FontWeight,
-  [TextVariant.BodySm]: typography.sBodySM.fontWeight as FontWeight,
-  [TextVariant.BodyXs]: typography.sBodyXS.fontWeight as FontWeight,
-  [TextVariant.PageHeading]: typography.sPageHeading.fontWeight as FontWeight,
-  [TextVariant.SectionHeading]: typography.sSectionHeading
-    .fontWeight as FontWeight,
-  [TextVariant.ButtonLabelMd]: typography.sButtonLabelMd
-    .fontWeight as FontWeight,
-  [TextVariant.ButtonLabelLg]: typography.sButtonLabelLg
-    .fontWeight as FontWeight,
-  [TextVariant.AmountDisplayLg]: typography.sAmountDisplayLg
-    .fontWeight as FontWeight,
+  [TextVariant.DisplayLg]: FontWeight.Bold,
+  [TextVariant.DisplayMd]: FontWeight.Bold,
+  [TextVariant.HeadingLg]: FontWeight.Bold,
+  [TextVariant.HeadingMd]: FontWeight.Bold,
+  [TextVariant.HeadingSm]: FontWeight.Bold,
+  [TextVariant.BodyLg]: FontWeight.Medium,
+  [TextVariant.BodyMd]: FontWeight.Regular,
+  [TextVariant.BodySm]: FontWeight.Regular,
+  [TextVariant.BodyXs]: FontWeight.Regular,
+  [TextVariant.PageHeading]: FontWeight.Bold,
+  [TextVariant.SectionHeading]: FontWeight.Bold,
+  [TextVariant.ButtonLabelMd]: FontWeight.Medium,
+  [TextVariant.ButtonLabelLg]: FontWeight.Medium,
+  [TextVariant.AmountDisplayLg]: FontWeight.Bold,
 };

packages/design-system-react-native/src/components/Text/Text.stories.tsx

@@ -1,16 +1,15 @@
+import {
+  FontFamily,
+  FontStyle,
+  FontWeight,
+  TextColor,
+  TextVariant,
+} from '@metamask/design-system-shared';
 import { useTailwind } from '@metamask/design-system-twrnc-preset';
 import type { Meta, StoryObj } from '@storybook/react-native';
 import React from 'react';
 import { View, ScrollView } from 'react-native';
 
-import {
-  TextVariant,
-  TextColor,
-  FontWeight,
-  FontFamily,
-  FontStyle,
-} from '../../types';
-
 import { Text } from './Text';
 import type { TextProps } from './Text.types';
 

packages/design-system-react-native/src/components/Text/Text.test.tsx

@@ -1,19 +1,18 @@
-import { useTailwind } from '@metamask/design-system-twrnc-preset';
-import { render } from '@testing-library/react-native';
-import React from 'react';
-
 import {
-  TextVariant,
-  TextColor,
-  FontWeight,
   FontFamily,
   FontStyle,
-} from '../../types';
+  FontWeight,
+  TextColor,
+  TextVariant,
+} from '@metamask/design-system-shared';
+import { useTailwind } from '@metamask/design-system-twrnc-preset';
+import { render } from '@testing-library/react-native';
+import React from 'react';
 
 import { Text } from './Text';
 import {
   TWCLASSMAP_TEXT_FONTWEIGHT,
-  MAP_TEXT_VARIANT_FONTWEIGHT,
+  TWCLASSMAP_TEXT_VARIANT_FONTWEIGHT,
 } from './Text.constants';
 
 function buildTextStyleArgs({
@@ -31,7 +30,7 @@ function buildTextStyleArgs({
   fontStyle: FontStyle;
   twClassName: string;
 }> = {}) {
-  const fw = fontWeight ?? MAP_TEXT_VARIANT_FONTWEIGHT[variant];
+  const fw = fontWeight ?? TWCLASSMAP_TEXT_VARIANT_FONTWEIGHT[variant];
   const isItalic = fontStyle === FontStyle.Italic;
   const fontSuffix = `${TWCLASSMAP_TEXT_FONTWEIGHT[fw]}${
     isItalic && fontFamily === FontFamily.Default ? '-italic' : ''
@@ -104,7 +103,7 @@ describe('Text', () => {
           expectedStyles = tw.style(
             ...buildTextStyleArgs({
               variant,
-              fontWeight: MAP_TEXT_VARIANT_FONTWEIGHT[variant],
+              fontWeight: TWCLASSMAP_TEXT_VARIANT_FONTWEIGHT[variant],
             }),
           );
           return (

packages/design-system-react-native/src/components/Text/Text.tsx

@@ -1,11 +1,15 @@
+import {
+  FontFamily,
+  FontStyle,
+  TextColor,
+  TextVariant,
+} from '@metamask/design-system-shared';
 import { useTailwind } from '@metamask/design-system-twrnc-preset';
 import React, { useMemo } from 'react';
 import { Text as RNText } from 'react-native';
 
-import { FontFamily, FontStyle, TextVariant, TextColor } from '../../types';
-
 import {
-  MAP_TEXT_VARIANT_FONTWEIGHT,
+  TWCLASSMAP_TEXT_VARIANT_FONTWEIGHT,
   TWCLASSMAP_TEXT_FONTWEIGHT,
 } from './Text.constants';
 import type { TextProps } from './Text.types';
@@ -22,7 +26,8 @@ export const Text: React.FC<TextProps> = ({
   ...props
 }) => {
   const tw = useTailwind();
-  const finalFontWeight = fontWeight ?? MAP_TEXT_VARIANT_FONTWEIGHT[variant];
+  const finalFontWeight =
+    fontWeight ?? TWCLASSMAP_TEXT_VARIANT_FONTWEIGHT[variant];
 
   const textStyle = useMemo(() => {
     const isItalic = fontStyle === FontStyle.Italic;