@12-apps/ui 6.17.1 → 6.19.0

package/src/components/typography/Paragraph/Paragraph.tsx

@@ -1,9 +1,22 @@
-import type { Theme } from '@mui/material/styles/index.js';
+import type { CSSObject, Theme } from '@mui/material/styles/index.js';
 import Typography from '@mui/material/Typography/index.js';
 import { styled } from '@mui/material/styles/index.js';
 import React from 'react';
 
+import {
+  LEAD_FONT_SIZE,
+  LEAD_LETTER_SPACING_EM,
+  LEAD_LINE_HEIGHT,
+  MUTED_OPACITY,
+  PARAGRAPH_FONT_WEIGHT,
+  PARAGRAPH_MARGIN_BOTTOM_EM,
+  PARAGRAPH_SIZES,
+  SMALL_FONT_SIZE,
+  SMALL_LINE_HEIGHT,
+} from './Paragraph.metrics';
 import type { ParagraphProps } from './Paragraph.types';
+import { resolveTestId, withoutTestIdProps } from '../../../platform/test-id';
+import { px } from '../../../tokens/theme';
 
 const getColorFromTheme = (theme: Theme, color: string) => {
   if (color === 'neutral') {
@@ -22,6 +35,20 @@ const getColorFromTheme = (theme: Theme, color: string) => {
   return colorMap[color] || theme.palette.text.primary;
 };
 
+// Derived from the shared metrics, not restated: the native `Paragraph` reads
+// the same table, so the two renderers cannot disagree on a size.
+const sizeMap: Record<string, { fontSize: string; lineHeight: number }> = Object.fromEntries(
+  Object.entries(PARAGRAPH_SIZES).map(([size, step]) => [
+    size,
+    { fontSize: px(step.fontSize), lineHeight: step.lineHeight },
+  ]),
+);
+
+// `lead` and `small` shrink or grow relative to the scale, but only at the
+// default size — an explicit size wins.
+const sizeOverride = (customSize: string, atDefault: number): string | undefined =>
+  customSize === 'md' ? px(atDefault) : sizeMap[customSize]?.fontSize;
+
 const StyledParagraph = styled(Typography, {
   shouldForwardProp: (prop) =>
     !['customVariant', 'customColor', 'customSize'].includes(prop as string),
@@ -32,61 +59,56 @@ const StyledParagraph = styled(Typography, {
 }>(({ theme, customVariant = 'default', customColor = 'neutral', customSize = 'md' }) => {
   const textColor = getColorFromTheme(theme, customColor);
 
-  // Size mapping
-  const sizeMap = {
-    xs: { fontSize: '0.75rem', lineHeight: 1.4 },
-    sm: { fontSize: '0.875rem', lineHeight: 1.5 },
-    md: { fontSize: '1rem', lineHeight: 1.6 },
-    lg: { fontSize: '1.125rem', lineHeight: 1.6 },
-    xl: { fontSize: '1.25rem', lineHeight: 1.7 },
-  };
-
-  const baseStyles = {
+  const baseStyles: CSSObject = {
     fontFamily: theme.typography.body1.fontFamily,
-    margin: '0 0 1em 0',
+    margin: `0 0 ${PARAGRAPH_MARGIN_BOTTOM_EM}em 0`,
     transition: 'all 0.2s ease',
-    ...sizeMap[customSize as keyof typeof sizeMap],
+    ...sizeMap[customSize],
   };
 
   // Variant-specific styles
-  const variantStyles = {
+  const variantStyles: Record<string, CSSObject> = {
     default: {
       ...baseStyles,
       color: textColor,
-      fontWeight: 400,
+      fontWeight: PARAGRAPH_FONT_WEIGHT,
     },
     lead: {
       ...baseStyles,
       color: textColor,
-      fontWeight: 400,
-      fontSize:
-        customSize === 'md' ? '1.125rem' : sizeMap[customSize as keyof typeof sizeMap]?.fontSize,
-      lineHeight: 1.7,
-      letterSpacing: '0.01em',
+      fontWeight: PARAGRAPH_FONT_WEIGHT,
+      fontSize: sizeOverride(customSize, LEAD_FONT_SIZE),
+      lineHeight: LEAD_LINE_HEIGHT,
+      letterSpacing: `${LEAD_LETTER_SPACING_EM}em`,
     },
     muted: {
       ...baseStyles,
       color: theme.palette.text.secondary,
-      fontWeight: 400,
-      opacity: 0.8,
+      fontWeight: PARAGRAPH_FONT_WEIGHT,
+      opacity: MUTED_OPACITY,
     },
     small: {
       ...baseStyles,
       color: theme.palette.text.secondary,
-      fontSize:
-        customSize === 'md' ? '0.875rem' : sizeMap[customSize as keyof typeof sizeMap]?.fontSize,
-      fontWeight: 400,
-      lineHeight: 1.5,
+      fontSize: sizeOverride(customSize, SMALL_FONT_SIZE),
+      fontWeight: PARAGRAPH_FONT_WEIGHT,
+      lineHeight: SMALL_LINE_HEIGHT,
     },
   };
 
-  return variantStyles[customVariant as keyof typeof variantStyles] || variantStyles.default;
+  return variantStyles[customVariant] || variantStyles.default;
 });
 
 export const Paragraph = React.forwardRef<globalThis.HTMLParagraphElement, ParagraphProps>(
-  ({ variant = 'default', color = 'neutral', size = 'md', children, ...props }, ref) => (
+  ({ variant = 'default', color = 'neutral', size = 'md', children, ...others }, ref) => {
+    // `testID` and `dataTestId` are the shared contract's spellings; the DOM
+    // wants `data-testid`, and must not see the other two as attributes.
+    const testId = resolveTestId(others);
+    const props = withoutTestIdProps(others);
+    return (
       <StyledParagraph
         ref={ref}
+        data-testid={testId}
         customVariant={variant}
         customColor={color}
         customSize={size}
@@ -94,7 +116,8 @@ export const Paragraph = React.forwardRef<globalThis.HTMLParagraphElement, Parag
       >
         {children}
       </StyledParagraph>
-    ),
+    );
+  },
 );
 
-Paragraph.displayName = 'Paragraph';
+Paragraph.displayName = 'Paragraph';

package/src/components/typography/Paragraph/Paragraph.types.native.ts

@@ -0,0 +1,17 @@
+import type { GestureResponderEvent, StyleProp, TextProps as RNTextProps, TextStyle } from 'react-native';
+
+import type { ParagraphBaseProps } from './Paragraph.base';
+
+export type { ParagraphBaseProps, ParagraphVariant } from './Paragraph.base';
+
+/**
+ * The native `Paragraph`: the shared contract, plus a react-native `Text`'s
+ * own props. `onClick` keeps its web name and `onPress` is accepted too, as on
+ * `Button`; both fire.
+ */
+export type ParagraphProps = ParagraphBaseProps &
+  Omit<RNTextProps, keyof ParagraphBaseProps | 'style' | 'onPress'> & {
+    onClick?: (event: GestureResponderEvent) => void;
+    onPress?: (event: GestureResponderEvent) => void;
+    style?: StyleProp<TextStyle>;
+  };

package/src/components/typography/Paragraph/Paragraph.types.ts

@@ -1,11 +1,10 @@
-import type { ColorValue, SizeValue } from '../../../tokens/scales';
 import type React from 'react';
 
-export type ParagraphVariant = 'default' | 'lead' | 'muted' | 'small';
+import type { ParagraphBaseProps } from './Paragraph.base';
 
-export interface ParagraphProps extends React.HTMLAttributes<globalThis.HTMLParagraphElement> {
-  variant?: ParagraphVariant;
-  color?: ColorValue;
-  size?: SizeValue;
-  children: React.ReactNode;
-}
+export type { ParagraphBaseProps, ParagraphVariant } from './Paragraph.base';
+
+/** The web `Paragraph`: the shared contract, plus everything a `<p>` accepts. */
+export interface ParagraphProps
+  extends ParagraphBaseProps,
+    Omit<React.HTMLAttributes<globalThis.HTMLParagraphElement>, 'color' | 'children'> {}

package/src/components/typography/Paragraph/index.native.ts

@@ -0,0 +1,2 @@
+export { Paragraph, paragraphStyle } from './Paragraph.native';
+export type { ParagraphBaseProps, ParagraphProps, ParagraphVariant } from './Paragraph.types.native';

package/src/components/typography/Paragraph/index.ts

@@ -1,2 +1,2 @@
 export { Paragraph } from './Paragraph';
-export type { ParagraphProps } from './Paragraph.types';
+export type { ParagraphBaseProps, ParagraphProps, ParagraphVariant } from './Paragraph.types';

package/src/components/typography/Text/Text.base.ts

@@ -0,0 +1,25 @@
+import type React from 'react';
+
+import type { ColorValue, SizeValue } from '../../../tokens/vocabulary';
+
+/** The contract both renderers honour; see `Button.base.ts` for why it is its own file. */
+export type TextVariant = 'body' | 'heading' | 'caption' | 'code';
+export type TextWeight = 'light' | 'normal' | 'medium' | 'semibold' | 'bold';
+
+/**
+ * The contract both renderers honour. Nothing here names a DOM or a React
+ * Native type: the web adds `HTMLAttributes` and `as` below, the native side
+ * adds `TextProps` from react-native in `Text.types.native.ts`.
+ */
+export interface TextBaseProps {
+  variant?: TextVariant;
+  color?: ColorValue;
+  size?: SizeValue;
+  weight?: TextWeight;
+  italic?: boolean;
+  underline?: boolean;
+  strikethrough?: boolean;
+  children: React.ReactNode;
+  testID?: string;
+  dataTestId?: string;
+}

package/src/components/typography/Text/Text.metrics.ts

@@ -0,0 +1,30 @@
+import { FONT_WEIGHTS, TYPE_SIZES } from '../../../tokens/theme';
+
+/**
+ * THE NUMBERS BOTH `Text` RENDERERS DRAW WITH.
+ *
+ * `Text.tsx` used to hold these as rem strings and `Text.native.tsx` would have
+ * held them again as numbers — two tables, one of which drifts. Now there is
+ * one, in px, and the web derives its rem from it (see `px()` in the theme).
+ * Ratios stay ratios; the native side multiplies them out because React
+ * Native's `lineHeight` and `letterSpacing` are absolute.
+ */
+export const TEXT_SIZES = TYPE_SIZES;
+export const TEXT_WEIGHTS = FONT_WEIGHTS;
+
+/** The `heading` variant: heavier by default, tighter tracking. */
+export const HEADING_DEFAULT_WEIGHT = 600;
+export const HEADING_LETTER_SPACING_EM = -0.01;
+
+/** The `caption` variant: a step down at the default size, faded and looser. */
+export const CAPTION_FONT_SIZE = 12;
+export const CAPTION_OPACITY = 0.8;
+export const CAPTION_LETTER_SPACING_EM = 0.02;
+
+/** The `code` variant: a step down, on a faint primary wash inside a hairline. */
+export const CODE_FONT_SIZE = 14;
+export const CODE_BACKGROUND_ALPHA = 0.08;
+export const CODE_BORDER_ALPHA = 0.12;
+export const CODE_PADDING = { vertical: 2, horizontal: 6 } as const;
+/** Half the theme's `md` radius, as `Text.tsx` has always drawn it. */
+export const CODE_RADIUS_FACTOR = 0.5;

package/src/components/typography/Text/Text.native.tsx

@@ -0,0 +1,149 @@
+import * as React from 'react';
+import { Platform, Text as RNText, type TextStyle } from 'react-native';
+
+import {
+  CAPTION_FONT_SIZE,
+  CAPTION_LETTER_SPACING_EM,
+  CAPTION_OPACITY,
+  CODE_BACKGROUND_ALPHA,
+  CODE_BORDER_ALPHA,
+  CODE_FONT_SIZE,
+  CODE_PADDING,
+  CODE_RADIUS_FACTOR,
+  HEADING_DEFAULT_WEIGHT,
+  HEADING_LETTER_SPACING_EM,
+  TEXT_SIZES,
+  TEXT_WEIGHTS,
+} from './Text.metrics';
+import type { TextProps, TextVariant, TextWeight } from './Text.types.native';
+import { resolveTestId, withoutTestIdProps } from '../../../platform/test-id';
+import { useUiTheme } from '../../../provider/use-ui-theme.native';
+import type { ColorValue, SizeValue } from '../../../tokens/vocabulary';
+import { alpha } from '../../../tokens/color';
+import type { UiTheme } from '../../../tokens/theme';
+
+/** Same mapping as the web `getColorFromTheme`: neutral is body ink, secondary the muted ink. */
+const inkFor = (theme: UiTheme, color: ColorValue): string => {
+  if (color === 'neutral') return theme.palette.text.primary;
+  if (color === 'secondary') return theme.palette.text.secondary;
+  return theme.palette[color].main;
+};
+
+/** React Native wants the weight as a string. */
+const weightOf = (weight: number): TextStyle['fontWeight'] => String(weight) as TextStyle['fontWeight'];
+
+/** Captions and code shrink relative to the body scale, but only at the default size. */
+const sizeOverride = (size: SizeValue, atDefault: number): number =>
+  size === 'md' ? atDefault : TEXT_SIZES[size].fontSize;
+
+const decoration = (underline: boolean, strikethrough: boolean): TextStyle['textDecorationLine'] => {
+  if (underline && strikethrough) return 'underline line-through';
+  if (underline) return 'underline';
+  return strikethrough ? 'line-through' : 'none';
+};
+
+interface TextStyleArgs {
+  variant: TextVariant;
+  color: ColorValue;
+  size: SizeValue;
+  weight: TextWeight;
+  italic: boolean;
+  underline: boolean;
+  strikethrough: boolean;
+}
+
+const monospace = (theme: UiTheme): string | undefined =>
+  theme.typography.monospaceFontFamily ?? Platform.select({ ios: 'Menlo', android: 'monospace', default: 'monospace' });
+
+/**
+ * The style the web `Text` computes, in absolute numbers. `lineHeight` and
+ * `letterSpacing` are multiplied out here because React Native has no ratio
+ * or `em` unit — the web keeps them relative and the browser does this step.
+ */
+export function textStyle(theme: UiTheme, a: TextStyleArgs): TextStyle {
+  const step = TEXT_SIZES[a.size];
+  const base: TextStyle = {
+    color: inkFor(theme, a.color),
+    fontFamily: theme.typography.fontFamily,
+    fontSize: step.fontSize,
+    lineHeight: step.fontSize * step.lineHeight,
+    fontWeight: weightOf(TEXT_WEIGHTS[a.weight]),
+    fontStyle: a.italic ? 'italic' : 'normal',
+    textDecorationLine: decoration(a.underline, a.strikethrough),
+  };
+
+  switch (a.variant) {
+    case 'heading':
+      return {
+        ...base,
+        fontWeight: weightOf(a.weight === 'normal' ? HEADING_DEFAULT_WEIGHT : TEXT_WEIGHTS[a.weight]),
+        letterSpacing: HEADING_LETTER_SPACING_EM * step.fontSize,
+      };
+    case 'caption': {
+      const fontSize = sizeOverride(a.size, CAPTION_FONT_SIZE);
+      return {
+        ...base,
+        fontSize,
+        lineHeight: fontSize * step.lineHeight,
+        opacity: CAPTION_OPACITY,
+        letterSpacing: CAPTION_LETTER_SPACING_EM * fontSize,
+      };
+    }
+    case 'code': {
+      const fontSize = sizeOverride(a.size, CODE_FONT_SIZE);
+      return {
+        ...base,
+        fontFamily: monospace(theme),
+        fontSize,
+        lineHeight: fontSize * step.lineHeight,
+        backgroundColor: alpha(theme.palette.primary.main, CODE_BACKGROUND_ALPHA),
+        paddingVertical: CODE_PADDING.vertical,
+        paddingHorizontal: CODE_PADDING.horizontal,
+        borderRadius: theme.radius.md * CODE_RADIUS_FACTOR,
+        borderWidth: 1,
+        borderColor: alpha(theme.palette.primary.main, CODE_BORDER_ALPHA),
+      };
+    }
+    default:
+      return base;
+  }
+}
+
+export const Text = React.forwardRef<RNText, TextProps>(
+  (
+    {
+      variant = 'body',
+      color = 'neutral',
+      size = 'md',
+      weight = 'normal',
+      italic = false,
+      underline = false,
+      strikethrough = false,
+      children,
+      style,
+      ...others
+    },
+    ref,
+  ) => {
+    const rest = withoutTestIdProps(others);
+    const theme = useUiTheme();
+    const resolved = React.useMemo(
+      () => textStyle(theme, { variant, color, size, weight, italic, underline, strikethrough }),
+      [theme, variant, color, size, weight, italic, underline, strikethrough],
+    );
+
+    return (
+      <RNText
+        ref={ref}
+        style={[resolved, style]}
+        testID={resolveTestId(others)}
+        role={variant === 'heading' ? 'heading' : undefined}
+        {...rest}
+      >
+        {children}
+      </RNText>
+    );
+  },
+);
+
+Text.displayName = 'Text';

package/src/components/typography/Text/Text.tsx

@@ -5,8 +5,24 @@ import Typography from '@mui/material/Typography/index.js';
 import { alpha, styled } from '@mui/material/styles/index.js';
 import React from 'react';
 
+import {
+  CAPTION_FONT_SIZE,
+  CAPTION_LETTER_SPACING_EM,
+  CAPTION_OPACITY,
+  CODE_BACKGROUND_ALPHA,
+  CODE_BORDER_ALPHA,
+  CODE_FONT_SIZE,
+  CODE_PADDING,
+  CODE_RADIUS_FACTOR,
+  HEADING_DEFAULT_WEIGHT,
+  HEADING_LETTER_SPACING_EM,
+  TEXT_SIZES,
+  TEXT_WEIGHTS,
+} from './Text.metrics';
 import type { TextProps } from './Text.types';
+import { resolveTestId, withoutTestIdProps } from '../../../platform/test-id';
 import type { ColorValue } from '../../../tokens/scales';
+import { px } from '../../../tokens/theme';
 
 const getColorFromTheme = (theme: Theme, color: ColorValue): string => {
   if (color === 'neutral') {
@@ -32,21 +48,16 @@ const getColorFromTheme = (theme: Theme, color: ColorValue): string => {
   return colorMap[color];
 };
 
-const SIZE_MAP: Record<string, { fontSize: string; lineHeight: number }> = {
-  xs: { fontSize: '0.75rem', lineHeight: 1.2 },
-  sm: { fontSize: '0.875rem', lineHeight: 1.3 },
-  md: { fontSize: '1rem', lineHeight: 1.5 },
-  lg: { fontSize: '1.125rem', lineHeight: 1.4 },
-  xl: { fontSize: '1.25rem', lineHeight: 1.3 },
-};
+// Derived from the shared metrics, not restated: the native `Text` reads the
+// same table, so the two renderers cannot disagree on a size.
+const SIZE_MAP: Record<string, { fontSize: string; lineHeight: number }> = Object.fromEntries(
+  Object.entries(TEXT_SIZES).map(([size, step]) => [
+    size,
+    { fontSize: px(step.fontSize), lineHeight: step.lineHeight },
+  ]),
+);
 
-const WEIGHT_MAP: Record<string, number> = {
-  light: 300,
-  normal: 400,
-  medium: 500,
-  semibold: 600,
-  bold: 700,
-};
+const WEIGHT_MAP: Record<string, number> = TEXT_WEIGHTS;
 
 interface TextStyleArgs {
   theme: Theme;
@@ -87,25 +98,25 @@ const textVariantStyles = (theme: Theme, a: TextStyleArgs, base: CSSObject): CSS
       return {
         ...base,
         fontFamily: theme.typography.h4.fontFamily,
-        fontWeight: weight === 'normal' ? 600 : WEIGHT_MAP[weight],
-        letterSpacing: '-0.01em',
+        fontWeight: weight === 'normal' ? HEADING_DEFAULT_WEIGHT : WEIGHT_MAP[weight],
+        letterSpacing: `${HEADING_LETTER_SPACING_EM}em`,
       };
     case 'caption':
       return {
         ...base,
-        fontSize: sizeOverride(a.customSize, '0.75rem'),
-        opacity: 0.8,
-        letterSpacing: '0.02em',
+        fontSize: sizeOverride(a.customSize, px(CAPTION_FONT_SIZE)),
+        opacity: CAPTION_OPACITY,
+        letterSpacing: `${CAPTION_LETTER_SPACING_EM}em`,
       };
     case 'code':
       return {
         ...base,
         fontFamily: 'Monaco, Menlo, "Ubuntu Mono", "Courier New", monospace',
-        fontSize: sizeOverride(a.customSize, '0.875rem'),
-        backgroundColor: alpha(theme.palette.primary.main, 0.08),
-        padding: '2px 6px',
-        borderRadius: theme.shape.borderRadius / 2,
-        border: `1px solid ${alpha(theme.palette.primary.main, 0.12)}`,
+        fontSize: sizeOverride(a.customSize, px(CODE_FONT_SIZE)),
+        backgroundColor: alpha(theme.palette.primary.main, CODE_BACKGROUND_ALPHA),
+        padding: `${CODE_PADDING.vertical}px ${CODE_PADDING.horizontal}px`,
+        borderRadius: theme.shape.borderRadius * CODE_RADIUS_FACTOR,
+        border: `1px solid ${alpha(theme.palette.primary.main, CODE_BORDER_ALPHA)}`,
       };
     default:
       return { ...base, fontFamily: theme.typography.body1.fontFamily };
@@ -148,12 +159,18 @@ export const Text = React.forwardRef<HTMLElement, TextProps>(
       underline = false,
       strikethrough = false,
       children,
-      ...props
+      ...others
     },
     ref,
-  ) => (
+  ) => {
+    // `testID` and `dataTestId` are the shared contract's spellings; the DOM
+    // wants `data-testid`, and must not see the other two as attributes.
+    const testId = resolveTestId(others);
+    const props = withoutTestIdProps(others);
+    return (
       <StyledText
         ref={ref}
+        data-testid={testId}
         customVariant={variant}
         customColor={color}
         customSize={size}
@@ -166,7 +183,8 @@ export const Text = React.forwardRef<HTMLElement, TextProps>(
       >
         {children}
       </StyledText>
-    ),
+    );
+  },
 );
 
 Text.displayName = 'Text';

package/src/components/typography/Text/Text.types.native.ts

@@ -0,0 +1,11 @@
+import type { StyleProp, TextProps as RNTextProps, TextStyle } from 'react-native';
+
+import type { TextBaseProps } from './Text.base';
+
+export type { TextBaseProps, TextVariant, TextWeight } from './Text.base';
+
+/** The native `Text`: the shared contract, plus a react-native `Text`'s own props. */
+export type TextProps = TextBaseProps &
+  Omit<RNTextProps, keyof TextBaseProps | 'style'> & {
+    style?: StyleProp<TextStyle>;
+  };

package/src/components/typography/Text/Text.types.ts

@@ -1,16 +1,11 @@
-import type { ColorValue, SizeValue } from '../../../tokens/scales';
 import type React from 'react';
 
-export type TextVariant = 'body' | 'heading' | 'caption' | 'code';
+import type { TextBaseProps } from './Text.base';
 
-export interface TextProps extends React.HTMLAttributes<HTMLSpanElement> {
-  variant?: TextVariant;
-  color?: ColorValue;
-  size?: SizeValue;
-  weight?: 'light' | 'normal' | 'medium' | 'semibold' | 'bold';
+export type { TextBaseProps, TextVariant, TextWeight } from './Text.base';
+
+export interface TextProps
+  extends TextBaseProps,
+    Omit<React.HTMLAttributes<HTMLSpanElement>, 'color' | 'children'> {
   as?: keyof React.JSX.IntrinsicElements;
-  italic?: boolean;
-  underline?: boolean;
-  strikethrough?: boolean;
-  children: React.ReactNode;
-}
+}

package/src/components/typography/Text/index.native.ts

@@ -0,0 +1,2 @@
+export { Text, textStyle } from './Text.native';
+export type { TextBaseProps, TextProps, TextVariant, TextWeight } from './Text.types.native';

package/src/components/typography/Text/index.ts

@@ -1,2 +1,2 @@
 export { Text } from './Text';
-export type { TextProps } from './Text.types';
+export type { TextBaseProps, TextProps, TextVariant, TextWeight } from './Text.types';

package/src/icons/Icon.md

@@ -0,0 +1,28 @@
+# Icon
+
+One glyph name, both renderers.
+
+```tsx
+import { Icon } from '@12-apps/ui/icons';
+
+<Icon name="Close" size="sm" color="neutral" label="Fechar" />
+```
+
+The web `Icon` is MUI's `SvgIcon` drawing a path; the native `Icon` is
+`react-native-svg` drawing the same path in the same 24-unit box. The path data
+is **generated** from the installed `@mui/icons-material` by
+`scripts/generate-icon-paths.mjs` into `src/icons/paths.generated.ts`, from the
+list in `src/icons/glyphs.json`. Adding a glyph is one line there and
+`pnpm icons:generate`; `pnpm icons:check` fails CI when the two drift.
+
+| prop | type | notes |
+|---|---|---|
+| `name` | `IconName` | one of `glyphs.json` |
+| `size` | `xs` `sm` `md` `lg` `xl` or a px number | 16, 20, 24 (MUI's default), 32, 40 |
+| `color` | a house colour, `inherit`, or any CSS colour | `inherit` is the surrounding text on the web and the theme's primary text on native, which has no `currentColor` |
+| `label` | `string` | the accessible name; omit for a decorative glyph, which is then `aria-hidden` on both sides |
+| `testID` / `dataTestId` | `string` | defaults to `icon-<name>` |
+
+Inside the package, a ported component draws its own glyphs through this
+component rather than importing `@mui/icons-material` directly, so its native
+twin can draw the same one.

package/src/icons/Icon.native.tsx

@@ -0,0 +1,44 @@
+import * as React from 'react';
+import type { StyleProp, ViewStyle } from 'react-native';
+import Svg, { Path } from 'react-native-svg';
+
+import { iconFill } from './icon-color';
+import { iconSize, type IconBaseProps } from './Icon.types';
+import { ICON_PATHS } from './paths.generated';
+import { resolveTestId } from '../platform/test-id';
+import { useUiTheme } from '../provider/use-ui-theme.native';
+
+export interface IconProps extends IconBaseProps {
+  style?: StyleProp<ViewStyle>;
+}
+
+/**
+ * The native `Icon`: `react-native-svg` drawing the same generated path the web
+ * `SvgIcon` draws, in the same 24-unit box, at the same px size.
+ */
+export function Icon({ name, size, color, label, style, ...rest }: IconProps): React.JSX.Element {
+  const theme = useUiTheme();
+  const px = iconSize(size);
+  const fill = iconFill(theme, color, theme.palette.text.primary);
+  const testId = resolveTestId(rest, `icon-${name}`);
+
+  return (
+    <Svg
+      width={px}
+      height={px}
+      viewBox="0 0 24 24"
+      fill={fill}
+      style={style}
+      testID={testId}
+      role="img"
+      aria-label={label}
+      aria-hidden={!label}
+    >
+      {ICON_PATHS[name].map((d) => (
+        <Path key={d} d={d} fill={fill} />
+      ))}
+    </Svg>
+  );
+}
+
+Icon.displayName = 'Icon';