React Native Paper: MD3 Component Review

[adrcotfas]

Systematic review of each component against the current Material Design 3 guidelines.

Important

Baseline: This audit is done on top of the changes from Add dynamic material themes.
In the meantime more changes were added to the v6 branch, like theme tokens which should be used for all components.

Review axes:

• Color tokens: correct MD3 role names from the theme
• Spacing / sizing: padding, margin, height, icon sizes match spec values
• Behavior/Animation: state layers, disabled states, interaction patterns, elevation
• Shape: border radius values match MD3 shape tokens (corner.*)

Reference implementation: Behavior (especially animations not always described in written spec) should be cross-checked against https://github.com/material-components/material-components-android

General notes:

• Shape tokens should be introduced as a first-class system alongside color tokens. Currently components compute border radii inline (e.g., 4 * roundness, 7 * roundness) with no named constants. A theme.shapes object with named entries (extraSmall, small, medium, large, extraLarge, full) would make shape intent explicit, allow global overrides, and eliminate the scattered multiplier magic throughout component code.
• Each component should live in its own subdirectory under src/components/. Currently some components are loose files (e.g., Divider.tsx, Badge.tsx) while others have directories. Standardize to one directory per component.
• Component names should match MD3 spec names (e.g., “List” not “ListItem/ListAccordion”, “FAB Menu” not “FABGroup” etc).
• Components like Carousel, Date and time pickers, Sheets, Toolbars are missing from react-native-paper
• Hover is missing from react-native-paper; MD3 defines separate sets of color/opacity/state tokens for hovered components
• [minor] All button types should be consolidated under a single src/components/Buttons/ directory, matching the MD3 spec grouping. This includes Button, IconButton, SegmentedButtons, ToggleButton, and FAB (the MD3 spec groups FAB under Buttons).
• [minor] Components that have no MD3 equivalent (e.g., List.AccordionGroup, List.Section, Surface) should be moved to a separate directory such as src/components/custom/ or clearly marked as library extensions, so the MD3 surface area is unambiguous.

---

Components were reviewed according to the order they appear in the Example app.

Activity Indicator

MD3 spec: Progress indicators (Circular)
Specs link: https://m3.material.io/components/progress-indicators/specs

Color tokens

• No track color. MD3 requires a track arc behind the indicator (token: secondaryContainer); only primary is rendered

Spacing / sizing

• Stroke width is size / 10 (2.4dp @ small, 4.8dp @ large). MD3 specifies a fixed 4dp stroke for both indicator and track

Behavior

• Arc ends are square (border clipping technique). MD3 requires rounded stroke caps
• No track rendered. MD3 always shows the inactive track arc
• M3 Expressive wavy circular and linear indicators not implemented

Notes

• Rename to match MD3: CircularProgressIndicator and move to a “Progress Indicators” directory together with Linear Progress Indicator.
• Entire rendering approach is MD2-era (two clipped half-border views). MD3-compliant implementation needs SVG or canvas-based arc for rounded caps and track

---

Animated FAB

MD3 spec: Extended FAB
Specs link: https://m3.material.io/components/extended-fab/specs

Color tokens

• surface variant (surfaceContainerHigh bg / primary fg) does not exist in the MD3 Extended FAB spec. Only primary, secondary, and tertiary are defined
• primary, secondary, tertiary variants map to correct MD3 container/on-container token pairs ✅

Spacing / sizing

• Container height 56dp ✅
• Leading space 16dp ✅
• Trailing space 16dp ✅
• Corner radius 16dp ✅, but hardcoded (SIZE / 3.5) instead of derived from theme.roundness like FAB does (4 * roundness)
• Icon-to-label gap is ~16dp. Spec requires 8dp (extendedWidth = textWidth + SIZE + borderRadius leaves 16dp)
• Only one fixed size (SIZE = 56). Spec defines three sizes: small (56dp), medium (80dp), large (96dp), each with different corner radii and icon sizes

Behavior

• iconMode: 'dynamic' (default) slides the icon during collapse/extend. MD3 keeps the icon on the leading side; only the label fades in/out
• Shape does not animate during the FAB to Extended FAB transition. MD3 specifies borderRadius morphs between FAB (28dp) and Extended FAB (16dp) as part of the transform sequence
• Collapse/extend animation uses Easing.linear. MD3 motion tokens require standard easing (emphasizedDecelerate / emphasizedAccelerate)

Notes

• Rename to match MD3: ExtendedFAB
• MD3 defines a three-step transform on scroll: shape changes, icon moves to leading side, label fades in. Current implementation uses a single translateX with no shape morph

---

Appbar

MD3 spec: App bars (Top app bar)
Specs link: https://m3.material.io/components/app-bars/specs

Color tokens

• Container background surface (flat) ✅
• surfaceContainer when elevated prop is set ✅
• Leading icon onSurface ✅
• Trailing icons onSurfaceVariant ✅
• Headline onSurface ✅

Spacing / sizing

• Small height 64dp ✅
• Baseline medium height 112dp ✅
• Baseline large height 152dp ✅
• Typography per mode (titleLarge / headlineSmall / headlineMedium) ✅

Behavior

• Medium flexible and Large flexible variants not implemented. Both are part of the M3 Expressive spec (Search app bar is covered by the separate Searchbar component)
• medium and large modes implement the baseline variants, which are explicitly not recommended in M3 Expressive. Flexible counterparts should be added and baselines deprecated
• center-aligned is a separate mode value. M3 Expressive merges it into small as a text-alignment configuration
• elevated is a static boolean. MD3 specifies the container color transitions reactively on scroll (surface to surfaceContainer); no scroll-reactive API is provided
• Subtitle support is @deprecated in v5. M3 Expressive medium flexible and large flexible variants restore subtitle as a supported element
• Image/logo in the container not supported. M3 Expressive anatomy includes image/logo as an optional element
• Filled trailing icon button not supported. M3 Expressive allows a single filled (primary or tonal) icon button in the trailing area

Notes

• Current implementation covers the original M3 set (small, center-aligned, medium baseline, large baseline) but is missing the full M3 Expressive set
• Should be renamed to T

---

Avatar

MD3 spec: N/A (no Avatar component in MD3 specs)

---

Badge

MD3 spec: Badges
Specs link: https://m3.material.io/components/badges/specs

Color tokens

• Background error ✅
• Label text onError ✅

Spacing / sizing

• Default size is 20dp. MD3 defines small badge at 6dp (no label) and large badge at 16dp (with label)
• No small/large distinction. Size should be determined automatically: 6dp when no children, 16dp when children are present
• paddingHorizontal: 3. Spec requires 4dp between badge edge and text
• fontSize = size * 0.5 yields 8sp at 16dp. Spec requires 11sp for large badge label text
• Large badge max character count size (16x34dp) not handled; text currently overflows unconstrained

Behavior

• No automatic small vs large variant. Component should render as a 6dp dot when childless and as a 16dp pill when a label is provided

---

Banner

MD3 spec: N/A (no Banner component in MD3 specs)

---

Bottom Navigation

MD3 spec: Navigation bar
Specs link: https://m3.material.io/components/navigation-bar/specs

Notes

• BottomNavigation is a router-aware wrapper around BottomNavigation.Bar that handles scene management and tab transitions. MD3 compliance is governed by BottomNavigation.Bar below.

---

Bottom Navigation Bar

MD3 spec: Navigation bar
Specs link: https://m3.material.io/components/navigation-bar/specs

Color tokens

• Container surfaceContainer ✅
• Active icon onSecondaryContainer ✅
• Active indicator secondaryContainer ✅
• Inactive icon onSurfaceVariant ✅
• Inactive label onSurfaceVariant ✅
• Active label uses onSurface. Spec token Nav bar item active label text color maps to secondary

Spacing / sizing

• Active indicator 64x32dp with 16dp corner radius ✅
• Icon-to-label gap 4dp (marginBottom: 4 on icon container) ✅
• v3NoLabelContainer height is hardcoded to 80dp. Spec requires 64dp
• BAR_HEIGHT = 56 constant is used for label height styling. Spec bar height is 64dp

Behavior

• shifting mode (inactive tabs hide labels) is an MD2 pattern not present in MD3
• labeled={false} hides all labels (not in MD3 spec, but a deliberate extension used by Google’s own products e.g. Gmail) ✅
• rippleColor: 'transparent' suppresses state layer feedback. MD3 requires visible state layers (8% hovered, 10% focused/pressed)
• Flexible navigation bar (horizontal items for medium windows) not implemented. M3 Expressive requires horizontal layout support
• Baseline navigation bar is not recommended in M3 Expressive; flexible variant should replace it

Notes

• Rename to match MD3: NavigationBar

---

Button

MD3 spec: Buttons
Specs link: https://m3.material.io/components/buttons/specs

Color tokens

• Elevated: surfaceContainerLow bg / primary label ✅
• Filled (contained): primary bg / onPrimary label ✅
• Tonal (contained-tonal): secondaryContainer bg / onSecondaryContainer label ✅
• Text: transparent bg / primary label ✅
• Outlined: border uses outlineVariant. Spec token is outline
• Outlined: label uses primary. Spec token is onSurfaceVariant

Spacing / sizing

• Height 40dp (marginVertical: 10 + labelLarge line height) ✅
• Corner radius 5 * roundness = 20dp (fully rounded for small) ✅
• Icon size is 18dp. Spec defines 20dp for leading/trailing icons
• Horizontal padding is 24dp (md3Label marginHorizontal). Spec recommends 16dp; 24dp is explicitly marked as no longer recommended

Behavior

• Mode names don’t match MD3: contained should be filled, contained-tonal should be tonal
• Toggle button not implemented (M3 Expressive)
• Only one size (small/40dp). M3 Expressive defines XS, M, L, XL with different heights, padding, and corner radii
• No square shape variant. M3 Expressive adds square shape with 12dp (XS/S), 16dp (M), 28dp (L/XL) corner radii
• No shape morph on press (round→8dp) or on toggle select (round↔︎square). M3 Expressive requirement

Notes

• Default mode is 'text'; MD3 hierarchy implies filled as the primary/default button style

---

Card

MD3 spec: Cards
Specs link: https://m3.material.io/components/cards/specs

Color tokens

• Elevated: relies on Surface elevation=1 for surfaceContainerLow bg (verify Surface implements this correctly)
• Outlined: surface bg ✅
• contained (filled) uses surfaceVariant. Spec requires surfaceContainerHighest
• Outlined border uses colors.outline. Spec token is outlineVariant (#CAC4D0)

Spacing / sizing

• Corner radius 3 * roundness = 12dp ✅
• CardContent horizontal padding 16dp ✅

Behavior

• Mode name contained should be filled to match MD3
• Touchable cards use Pressable directly instead of TouchableRipple. No MD3 ripple / state layer feedback on press

---

Checkbox

MD3 spec: Checkbox
Specs link: https://m3.material.io/components/checkbox/specs

Color tokens

• Unselected outline onSurfaceVariant ✅ (Android only; iOS has no outline at all)
• Selected container primary ✅ (used as icon tint, not as a real filled container)
• Disabled container/outline onSurface at 38% opacity ✅
• Selected icon: checkbox-marked glyph with primary tint achieves the correct visual (filled box + white checkmark baked into the glyph) ✅
• Error state not implemented. Spec defines error tokens for unselected error outline and selected error container (md.sys.color.error), and onError for the error icon

Spacing / sizing

• Icon size is 24dp on both platforms. Spec requires 18dp container and 18dp icon
• State layer size is 36dp (Android) / undefined (iOS). Spec requires 40dp
• Container shape is not implemented as a proper 18dp square with 2dp corner radius. Both platforms use MaterialCommunityIcon glyphs that carry their own shape

Behavior

• iOS and Android render completely differently. MD3 requires a consistent look across platforms. The default Checkbox component switches implementation based on platform (CheckboxIOS vs CheckboxAndroid) — this should be unified into a single cross-platform MD3 implementation
• CheckboxIOS renders no visible box for the unchecked state — just a floating check icon that fades in/out. MD3 requires a visible 2dp outline box when unchecked
• CheckboxIOS lacks an uncheckedColor prop present on CheckboxAndroid — API inconsistency between the two implementations
• Indeterminate state is inconsistent: Android uses minus-box glyph (filled box + minus), iOS uses a plain minus icon. Both should match MD3’s filled-container-with-dash appearance
• Check/uncheck animation (scale bounce to 0.85 then back) is MD2-style. MD3 specifies a simpler state transition with no bounce

---

Checkbox Item

MD3 spec: N/A (library-specific compound component: Checkbox + label row)

Notes

• No direct MD3 equivalent, but all findings from Checkbox apply here since it embeds the Checkbox component

---

Chip

MD3 spec: Chips (Assist, Filter, Input, Suggestion)
Specs link: https://m3.material.io/components/chips/specs

Color tokens

• outlined mode border outlineVariant ✅
• outlined mode label onSurfaceVariant ✅
• flat mode background is always secondaryContainer regardless of selected state. Unselected assist/suggestion chips should have no fill (transparent); only selected filter chips use secondaryContainer
• elevated=true prop only animates elevation, never changes the background color. Elevated chip background should be surfaceContainerLow
• Icon color is hardcoded to primary for all non-disabled chips regardless of chip type or selected state. Filter chip unselected icon should be onSurfaceVariant; selected filter/input chip icon should be onSecondaryContainer
• showSelectedOverlay prop is declared but never consumed in the render path; selected overlay has no effect

Spacing / sizing

• Height 32dp ✅ (marginVertical: 6 + labelLarge 20dp line height)
• Icon size 18dp ✅
• Border radius 8dp (2 * roundness) ✅
• Avatar size 24dp, borderRadius: 12 (full circle) ✅
• compact mode reduces horizontal label margins from 16dp to 12dp (reasonable extension, not in spec)

Behavior

• Single Chip component covers all four MD3 chip types (assist, filter, input, suggestion) but does not expose a type prop. Each type has distinct color semantics (label, icon, selected container) that the current implementation does not fully model
• selected state in flat mode: getSelectedBackgroundColor returns the same value as the unselected background (secondaryContainer). No background color transition occurs; selection is only visible via the checkmark icon
• Close button (onClose) is rendered inside a bare Pressable with no TouchableRipple state layer
• showSelectedOverlay (declared prop) is unused; no selected overlay is applied

Notes

• The four MD3 chip types map loosely to library props: assist chip ~ no selected/onClose; filter chip ~ selected; input chip ~ onClose; suggestion chip ~ outlined with no selection. Proper separation would need a type or variant prop with distinct color logic per type

---

Data Table

• Not part of the MD3 specs

---

Dialog

MD3 spec: Dialogs
Specs link: https://m3.material.io/components/dialogs/specs

Color tokens

• Container surfaceContainerHigh ✅
• Icon secondary ✅
• Title onSurface ✅
• Title typography headlineSmall ✅
• Action button label primary ✅ (via Button text mode)
• Dialog.ScrollArea divider border color uses surfaceVariant; spec token is outline

Spacing / sizing

• Container border radius 7 * roundness = 28dp (corner.extra-large) ✅
• Icon size 24dp ✅
• Top/side/bottom padding 24dp ✅ (title marginTop: 24, marginHorizontal: 24; actions paddingBottom: 24, paddingHorizontal: 24)
• Title-to-body gap 16dp ✅ (DialogTitle marginBottom: 16)
• Icon-to-title gap 16dp ✅ (DialogTitle marginTop: 16 as non-first child)
• Button-to-button gap 8dp ✅
• Min width (280dp) and max width (560dp) not enforced. Dialog uses marginHorizontal: Math.max(left, right, 26) only
• When Dialog.Icon is the first child, Dialog injects marginTop: 24 on it (the injection applies to all first children), stacking on top of DialogIcon’s own paddingTop: 24. Total gap from dialog edge to icon becomes 48dp instead of 24dp

Behavior

• Dialog.Title does not detect whether Dialog.Icon is present. Spec requires center-aligned title when an icon is shown; text alignment is not automatically adjusted

---

Divider

MD3 spec: Divider
Specs link: https://m3.material.io/components/divider/specs

Color tokens

• Color outlineVariant ✅

Spacing / sizing

• leftInset margin-left 16dp ✅
• horizontalInset margin 16dp both sides ✅
• Default thickness is StyleSheet.hairlineWidth (sub-pixel on most platforms). Spec requires 1dp. Only the bold prop produces a 1dp divider, but bold is not an MD3 concept

---

FAB

MD3 spec: Floating action button
Specs link: https://m3.material.io/components/floating-action-button/specs

Color tokens

• primary variant: primaryContainer bg / onPrimaryContainer fg ✅
• secondary variant: secondaryContainer bg / onSecondaryContainer fg ✅
• tertiary variant: tertiaryContainer bg / onTertiaryContainer fg ✅
• surface variant (surfaceContainerHigh bg / primary fg) is not defined in the MD3 FAB spec
• M3 Expressive adds new primary, secondary, and tertiary color styles that use the actual role colors (primary/onPrimary, etc.) rather than their container counterparts. The current variant names map to container colors only

Spacing / sizing

• Small: 40x40dp, 3 * roundness = 12dp radius (corner.medium) ✅
• Medium (standard M3 FAB): 56x56dp, 4 * roundness = 16dp radius (corner.large) ✅
• Large: 96x96dp, 7 * roundness = 28dp radius (corner.extra-large) ✅
• Small/medium icon 24dp ✅
• Large icon 36dp ✅
• M3 Expressive medium FAB (80x80dp, corner.large-increased, 28dp icon) not implemented. Current size='medium' maps to the standard 56dp FAB, not the Expressive 80dp size

Behavior

• Elevation via Surface elevation system (flat = 0, elevated = level 3) ✅
• State layers via TouchableRipple ✅
• Small FAB is not recommended in M3 Expressive; no deprecation notice on size='small'

Notes

• Extended FAB (FAB with label prop) and AnimatedFAB share the same visual spec but are implemented in separate files with no code sharing. AnimatedFAB.tsx does not reuse FAB.tsx. Recommend consolidating into a single component tree with shared layout primitives after the audit.

---

FAB Menu

MD3 spec: FAB menu
Specs link: https://m3.material.io/components/fab-menu/specs

Color tokens

• Close button (main FAB when open) should use primary bg / onPrimary fg for the primary variant – current code passes variant to <FAB> which resolves to primaryContainer/onPrimaryContainer
• Stacked list items should use primaryContainer bg / onPrimaryContainer icon+label for primary variant – stackedFABBackgroundColor is always surfaceContainerHigh regardless of variant
• Label text color is always onSurface; spec requires variant-specific onPrimaryContainer / onSecondaryContainer / onTertiaryContainer
• Secondary and tertiary close button and list item colors have the same issues

Spacing / sizing

• Close button shape: spec corner.full (28dp for 56dp container); current FAB medium uses corner.large = 16dp
• Close button icon: spec 20dp; current FAB defaults to 24dp
• List item shape: spec corner.full; current FAB small/medium uses corner.medium (12dp) / corner.large (16dp)
• List item icon: 24dp ✅
• List item label: titleMedium ✅
• List item leading/trailing space: 24dp via marginHorizontal on the item wrapper ✅
• Between list items: spec 4dp; current styles.item has marginBottom: 16
• Between close button and last list item: spec 8dp; current marginBottom: 16 on item rows

Behavior

• State layers on list items via FAB’s TouchableRipple ✅
• Label container is a Card mode="contained" with hardcoded borderRadius: 5; spec treats label as an inline part of the menu item row, not a separate card
• Backdrop overlay (AnimatedPressable with theme.colors.background at 0.95 opacity) is not part of the MD3 FAB menu spec and should be removed
• No variant-aware color logic for list items – all variants render the same surfaceContainerHigh background

Notes

• Component is named FABGroup internally but maps to the MD3 “FAB menu” pattern
• Spec limits FAB menu to 2-6 items and prohibits use with extended FABs; neither constraint is enforced in the API
• Secondary and tertiary color variants exist in the spec but the color logic ignores variant for list items entirely

---

Icon

No direct MD3 equivalent. Internal primitive reused by other components. Skipped.

---

Icon Button

MD3 spec: Icon buttons
Specs link: https://m3.material.io/components/icon-buttons/specs

Color tokens

Filled (mode="contained")

• Selected: primary bg / onPrimary icon ✅
• Unselected (toggle): should be surfaceContainer bg / onSurfaceVariant icon; current is surfaceVariant bg / primary icon – wrong token and wrong icon color
• Non-toggle default (no selected prop): indistinguishable from toggle unselected at the API level; a non-toggle filled button should always show primary bg / onPrimary icon but currently shows the wrong unselected colors

Tonal (mode="contained-tonal")

• Unselected: should be secondaryContainer bg / onSecondaryContainer icon; current is surfaceVariant bg / onSurfaceVariant icon ❌
• Selected: should be secondary bg / onSecondary icon; current is secondaryContainer bg / onSecondaryContainer icon ❌ (selected/unselected tokens are swapped)

Outlined (mode="outlined")

• Unselected: outlineVariant border / onSurfaceVariant icon ✅
• Selected: inverseSurface bg / inverseOnSurface icon ✅

Standard (no mode)

• Unselected: onSurfaceVariant icon ✅
• Selected: primary icon ✅

Disabled

• Icon color: onSurface at stateOpacity.disabled (0.38) ✅
• Container opacity for filled/tonal disabled: current uses stateOpacity.disabled (0.38); spec requires 0.1 for the container

Spacing / sizing

• Small (default): icon 24dp, container 40dp (size + 2 * PADDING where PADDING = 8) ✅
• Default border radius: buttonSize / 2 = corner.full ✅
• No xsmall size (32dp container, 20dp icon)
• No medium size (56dp container, 24dp icon)
• No large size (96dp container, 32dp icon)
• No xlarge size (136dp container, 40dp icon)
• No square shape option (corner.medium / corner.large / corner.extra-large depending on size)
• No narrow / wide width variants (different leading/trailing padding)
• Outline width is hardcoded to 1dp for all sizes; spec requires 2dp for large and 3dp for xlarge

Behavior

• State layers via TouchableRipple ✅
• Toggle via selected prop ✅
• Shape morphs to corner.small on press (spring animation); not implemented
• Shape morphs on toggle selection (round shape swaps to square and vice versa); not implemented
• No web tooltip on hover

Notes

• The selected prop conflates “non-toggle enabled” with “toggle unselected” – both result in selected=false. The spec defines distinct color tokens for these two states (especially for filled). A nullable selected (or a separate toggle prop) would fix the API ambiguity.
• M3 Expressive adds xsmall and xlarge sizes and shape morphing; these are entirely new surface area for the component.

---

List Accordion

MD3 spec: Lists (expand interaction)
Specs link: https://m3.material.io/components/lists/specs

Color tokens

• Description / supporting text: onSurfaceVariant ✅
• Title color when expanded: hardcoded to primary; spec label text uses onSurface regardless of expand state
• Left icon color when expanded: hardcoded to primary; spec uses onSurfaceVariant for leading icons
• Container background: theme.colors.background; should be surface
• No selected state colors (primaryContainer bg / onPrimaryContainer text/icon) ❌

Spacing / sizing

• paddingVertical: 8 (container) + marginVertical: 6 (row) = 14dp each side; spec 1-line item is 56dp total height, requiring 16dp top/bottom padding ❌
• paddingRight: 24 trailing ✅
• Content paddingLeft: 16 ✅
• Title and description use hardcoded fontSize: 16 / fontSize: 14; should use theme.fonts.bodyLarge / theme.fonts.bodyMedium

Behavior

• Expand/collapse toggling via press ✅
• Controlled and uncontrolled modes ✅
• No expand/collapse animation; children appear and disappear instantly
• Chevron direction reversal is the only visual feedback for expanded state; no container highlight or shape change
• No multi-select or single-select mode

Notes

• Should be renamed to align with MD3 terminology (e.g., expandable list item) after the audit
• Animations and selected state are the most impactful missing features

---

List Accordion Group

MD3 spec: Lists (expand interaction – single-expand group)
Specs link: https://m3.material.io/components/lists/specs

Color tokens

No color logic of its own – delegates to List.Accordion. ✅

Spacing / sizing

No sizing logic of its own. ✅

Behavior

• At most one accordion expanded at a time (single-expand) ✅
• Controlled and uncontrolled modes ✅
• No direct MD3 equivalent; the constraint is implied by MD3 single-select list behavior ✅

Notes

• Pure context provider; no rendering of its own
• No issues beyond what is inherited from List.Accordion

---

List Item

MD3 spec: Lists
Specs link: https://m3.material.io/components/lists/specs

Color tokens

• Title: onSurface ✅
• Description / supporting text: onSurfaceVariant ✅
• Leading and trailing icon color passed as onSurfaceVariant ✅
• No container background set (inherits from parent) – acceptable since list items sit on surface ✅
• No selected state: spec defines primaryContainer bg / onPrimaryContainer label+icon for selected items

Spacing / sizing

• paddingVertical: 8 (container) + marginVertical: 6 (row) = 14dp each side; spec 1-line is 56dp requiring 16dp padding each side ❌
• paddingRight: 24 trailing ✅
• Content paddingLeft: 16 ✅
• Title uses hardcoded fontSize: 16; should use theme.fonts.bodyLarge
• Description uses hardcoded fontSize: 14; should use theme.fonts.bodyMedium

Behavior

• State layers via TouchableRipple ✅
• Left and right render-prop slots ✅
• No overline text slot (spec anatomy includes overline above label)
• No trailing text slot
• No selected state prop
• No multi-action support (multiple independent trailing actions)

Notes

• The left / right render-prop API is flexible but predates the MD3 slot model (leading / content / trailing); a typed slot API would be more aligned and enable correct padding calculations

---

List Section

MD3 spec: Lists (section grouping / subheader)
Specs link: https://m3.material.io/components/lists/specs

Color tokens

No color logic; delegates to ListSubheader. See ListSubheader for token review.

Spacing / sizing

• marginVertical: 8 on the section container – MD3 does not prescribe margin between sections; acceptable as a layout aid

Behavior

• Groups list items under an optional subheader ✅
• No MD3-specific behavior beyond grouping

Notes

• No functional issues; purely a layout container
• ListSubheader is not audited separately; its token usage should be verified against the MD3 subheader spec

---

Menu

MD3 spec: Menus
Specs link: https://m3.material.io/components/menus/specs

Color tokens

• Container background: theme.colors.elevation[level2] which resolves to surfaceContainerLow ✅ (standard color scheme)
• Menu.Item label text: onSurface ✅
• Menu.Item leading/trailing icon: onSurfaceVariant ✅
• Menu.Item disabled opacity: stateOpacity.disabled (0.38) ✅
• No selected item state: spec defines tertiaryContainer bg / onTertiaryContainer text+icon for selected menu items
• No vibrant color scheme (M3 Expressive): tertiaryContainer container / onTertiaryContainer icons+labels / tertiary selected bg / onTertiary selected text+icon

Spacing / sizing

• Container paddingVertical: 8 ✅
• Item min/max width: 112dp / 280dp ✅
• Item paddingHorizontal: 12 ✅
• Icon leading margin: 12dp after icon ✅
• Item height: 48dp (standard), 32dp (dense) – baseline menu values ✅
• Menu.Item label text uses bodyLarge; spec requires labelLarge
• Menu.Item has no supporting text slot (bodySmall); spec anatomy includes optional supporting text per item
• Menu.Item has no trailing supporting text slot (labelLarge); spec anatomy includes optional trailing text per item

Shape

• Container: borderRadius: theme.roundness = 4dp; spec corner.large = 4 * roundness = 16dp ❌
• First child item: spec corner.medium top corners; not implemented
• Last child item: spec corner.medium bottom corners; not implemented
• Selected item: spec corner.medium; not implemented
• No per-item shape rounding at all; all items are rectangles

Behavior

• Open/close: scale + opacity animation ✅ (but uses Easing.bezier(0.4, 0, 0.2, 1) from old M3 motion guidelines; M3 Expressive uses spring-based motion)
• Dismisses on outside press ✅
• Keyboard-aware positioning ✅
• RTL support ✅
• Escape key dismissal on web ✅
• Back handler on Android ✅
• No item selection state / active item support
• No grouped layout (gaps between item groups); current workaround uses Divider which is not the spec-aligned grouping mechanism for vertical menus
• No submenu support
• No badge support on items
• M3 Expressive vertical menu shape morphing (active container shape animates as focus moves to submenu) not implemented

Notes

• The current component implements the baseline menu variant only. The M3 Expressive vertical menu is a largely new feature surface (new shapes, selection states, vibrant color scheme, submenu motion, grouped layout) that requires significant additions.
• The borderRadius: theme.roundness bug is a significant visual regression vs spec – the container should be visibly rounded.

---

Progress Bar

MD3 spec: Linear progress indicator
Specs link: https://m3.material.io/components/progress-indicators/specs

Color tokens

• Active indicator: color || theme.colors.primary ✅
• Track: theme.colors.surfaceVariant; spec requires secondaryContainer ❌
• No stop indicator rendered; spec defines a stop indicator at 100% (color primary)

Spacing / sizing

• Height: 4dp ✅
• Track has no borderRadius; spec corner.full requires borderRadius: 2 for 4dp height
• Active indicator fill has no borderRadius; same issue as track
• No 4dp horizontal inset from screen edges; spec shows 4dp padding on each side
• Configurable thickness not supported (M3 Expressive)
• Wavy shape (amplitude 3dp, wavelength 40dp, height 10dp) not supported (M3 Expressive)

Behavior

• Determinate mode: progress value animates via scaleX ✅
• Indeterminate mode: looping translate + scaleX animation ✅
• Visibility fade in/out ✅
• RTL support ✅
• Stop indicator not shown at the end of the track

Notes

• Should be renamed LinearProgressIndicator and placed in a shared ProgressIndicator/ directory alongside ActivityIndicator (circular), matching MD3 naming
• ProgressBar name and the color prop (which bypasses the token system) are library-level issues to address at rename time

---

Radio Button

MD3 spec: Radio button
Specs link: https://m3.material.io/components/radio-button/specs

Color tokens

• Selected icon: primary ✅
• Unselected icon: onSurfaceVariant ✅
• Disabled icon (selected + unselected): onSurface at 0.38 opacity ✅
• Pressed state layer color not set explicitly; spec defines selected pressed = onSurface state layer, unselected pressed = primary state layer – current TouchableRipple uses a default ripple color, not these per-state values
• Unselected pressed icon should become onSurface; currently stays onSurfaceVariant

Spacing / sizing

• Icon size: 20x20dp ✅
• Dot size: 10x10dp (centered fill for checked) ✅
• State layer size: margin: 8 gives 36dp container (20 + 8*2); spec requires 40dp; fix: margin: 10, borderRadius: 20

Behavior

• Check animation: scale bounce (radioAnim 1.2 -> 1) ✅
• Uncheck animation: borderWidth collapses from 10 to 2 ✅
• State layers via TouchableRipple ✅
• Context-aware via RadioButtonGroup ✅

Notes

• RadioButton.tsx is a platform dispatcher to RadioButtonAndroid / RadioButtonIOS; the Android implementation is the cross-platform reference
• color and uncheckedColor props bypass the token system – library-level issue to address

---

Radio Button Group

MD3 spec: Radio button (group behavior)
Specs link: https://m3.material.io/components/radio-button/specs

Notes

• Pure context provider for shared value and onValueChange; no rendering of its own
• No color or sizing logic; all deferred to RadioButton

---

Radio Button Item

MD3 spec: Radio button (with label)
Specs link: https://m3.material.io/components/radio-button/specs

Color tokens

• Label text: onSurface ✅ (spec: adjacent label uses onSurface regardless of selection state)
• Label disabled opacity: stateOpacity.disabled (0.38) ✅
• Inherits radio button color issues from RadioButton

Spacing / sizing

• paddingVertical: 8, paddingHorizontal: 16 – functional but no spec measurement for the item row; consistent with list item convention ✅
• Label flexShrink: 1, flexGrow: 1 fills available space ✅

Behavior

• Entire row is pressable via TouchableRipple ✅
• position prop supports leading/trailing radio placement ✅
• labelVariant defaults to bodyLarge ✅

---

Searchbar

MD3 spec: Search
Specs link: https://m3.material.io/components/search/specs

Color tokens

• Container background: surfaceContainerHigh ✅
• Leading icon: onSurfaceVariant ✅
• Clear / trailing icons: onSurfaceVariant ✅
• Cursor: primary ✅
• Input text color: onSurfaceVariant; should be onSurface
• Placeholder text color: onSurface; should be onSurfaceVariant – these two are swapped ❌

Spacing / sizing

• Bar height: minHeight: 56 ✅
• Bar border radius: 7 * roundness = 28dp (corner.extra-large) ✅ for baseline style
• View mode border radius: 0 (corner.none) ✅ for divided style
• Input font: bodyLarge (16sp, overrides fontSize: 18 in StyleSheet) ✅

Behavior

• Leading icon, clear icon, trailing icon, custom right render prop ✅
• mode="bar" maps to divided/baseline style with elevation ✅
• mode="view" maps to divided search view with bottom Divider ✅
• State layers on icons via IconButton + TouchableRipple ✅
• No focus animation: M3 Expressive (Feb 2025) requires the bar container margins to change from 24dp (unfocused) to 12dp (focused), creating a grow-wider effect; not implemented
• mode values ("bar" / "view") do not align with M3 spec terminology ("contained" / "divided (baseline)")
• M3 Expressive contained style is now the recommended style; the component partially implements the shape but missing the focus margin transition
• No results/suggestions container component: spec anatomy includes a “container for search suggestions or results” as element 6; consumers must build this themselves with no provided primitive

Notes

• Should be moved to its own directory
• The divided style is deprecated in M3 Expressive in favor of contained; mode="view" implements the divided style
• Result grouping with gaps (M3 Expressive) is a consumer-level concern and does not need to be part of the component itself

---

Segmented Button

MD3 spec: Segmented buttons (deprecated in M3 Expressive – use Connected Button Group)
Specs link: https://m3.material.io/components/segmented-buttons/overview

Color tokens

• Selected background: secondaryContainer ✅
• Selected text/icon: onSecondaryContainer ✅
• Unselected text: onSurface ✅
• Border: outline ✅

Spacing / sizing

• Height: 40dp – current paddingVertical: 9 + labelLarge line-height (20dp) = 38dp ❌; fix: paddingVertical: 10
• Outline width: 1dp ✅
• Left/right padding: min 12dp – current paddingHorizontal: 16 ✅
• Padding between icon and label: spec 8dp; current marginRight: 5 ❌
• Outer border radius: 5 * roundness = 20dp (corner.full) ✅
• Middle segments: borderRadius: 0 ✅
• First/last segments: one side rounded, one side flat ✅
• Label font: labelLarge ✅
• Icon size: 18dp ✅

Behavior

• Single-select and multi-select modes ✅
• Check icon animates in/out with spring on selection (when showSelectedCheck is true) ✅
• State layers via TouchableRipple ✅
• No shape morphing on press (M3 Expressive connected button group feature)

Notes

• Deprecated in M3 Expressive (as of the 2025 update). The replacement is “Connected Button Group” which has the same functionality but updated visual design. A deprecation notice should be added to the component API.
• Connected Button Group is not yet implemented in the library; it should be added under src/components/Buttons/ alongside the other button types.

---

Snackbar

MD3 spec: Snackbar
Specs link: https://m3.material.io/components/snackbar/specs

Color tokens

• Container: inverseSurface ✅
• Text: inverseOnSurface ✅
• Action button text: inversePrimary ✅
• Close icon: inverseOnSurface ✅

Spacing / sizing

• Container shape: borderRadius: roundness = 4dp (corner.extra-small) ✅
• Content padding: marginHorizontal: 16, marginVertical: 14 ✅
• minHeight: 48 ✅
• Screen-edge margin: margin: 8 ✅
• Text: bodyMedium ✅

Behavior

• Auto-dismiss after configurable duration ✅
• Persists when duration={Infinity} ✅
• Opacity + scale (0.9→1) fade-in animation ✅
• Bottom-positioned with safe area insets ✅
• Action button and close icon button ✅
• No Portal by default: spec places the snackbar above all content; users must wrap with <Portal> manually, which is error-prone

Notes

• Should be moved to its own directory
• borderRadius: 4 is hardcoded redundantly in StyleSheet and then overridden by borderRadius: roundness – the StyleSheet value can be removed

---

Surface

MD3 spec: Elevation (no standalone Surface component in MD3)
Specs link: https://m3.material.io/styles/elevation/overview

Color tokens

• Tonal background colors sourced from theme.colors.elevation.levelN ✅
• LightTheme: level3 and level4 both resolve to palette.neutral92 – correct per spec (both “Surface at +3” and “Surface at +4” map to surfaceContainer) ✅
• Shadow color is hardcoded to MD3Colors.primary0 (black constant); should use theme.colors.shadow so custom themes can override it

Shape

No shape logic – shape is delegated to consumers. ✅

Spacing / sizing

No sizing logic of its own. ✅

Behavior

• Tonal background interpolates across elevation levels 0-5 ✅
• mode="elevated" adds shadow; mode="flat" suppresses it ✅
• Animated elevation supported via Animated.Value ✅
• Android elevation dp values are [0, 3, 6, 9, 12, 15]; MD3 spec dp values for levels 0-5 are [0, 1, 3, 6, 8, 12] – all non-zero levels are wrong

Animation

No animation logic of its own beyond interpolating Animated.Value inputs. ✅

Notes

• Not an MD3 component; it is a library primitive that implements the MD3 Elevation system
• Maybe it should be kept as a core utility under a different directory
• The container prop is an internal layout workaround for iOS two-layer shadow rendering; not exposed in the public API and not spec-related
• MD3 now recommends using surfaceContainerLowest / Low / Container / High / Highest color roles directly rather than numeric elevation levels for static surfaces; Surface with numeric elevation is appropriate for interactive elevation changes only

---

Switch

MD3 spec: https://m3.material.io/components/switch/specs

Currently wraps the platform-native Switch. A custom cross-platform implementation is needed: even after facebook/react-native#56484 lands it only modernizes Android, so iOS still requires a custom component to achieve consistent MD3 appearance on all platforms.

---

Text

MD3 spec: Typography
Specs link: https://m3.material.io/styles/typography/overview

Library primitive that wraps the RN Text component and applies theme.fonts[variant] styles. No direct MD3 component equivalent – it surfaces the MD3 type scale defined in src/styles/themes/v3/tokens.tsx and src/types.tsx.

Color tokens

• Default text color onSurface ✅

Spacing / sizing

• All 15 baseline type scale styles present (displayLarge through bodySmall) ✅
• Font sizes and line heights match MD3 spec values ✅
• displayLarge letterSpacing should be -0.25; currently inherits regularType.letterSpacing = 0
• bodyLarge letterSpacing should be 0.5; currently inherits mediumType.letterSpacing = 0.15 (fontWeight/fontFamily are overridden but letterSpacing is not)

Behavior

• variant prop maps directly to theme.fonts[variant] ✅
• Nested Text variant/style override logic handled ✅

Animation

N/A

Notes

• M3 Expressive adds 15 emphasized type styles (md.sys.typescale.emphasized.*): displayLargeEmphasized, displayMediumEmphasized, displaySmallEmphasized, headlineLargeEmphasized, headlineMediumEmphasized, headlineSmallEmphasized, titleLargeEmphasized, titleMediumEmphasized, titleSmallEmphasized, labelLargeEmphasized, labelMediumEmphasized, labelSmallEmphasized, bodyLargeEmphasized, bodyMediumEmphasized, bodySmallEmphasized. These need to be added to MD3TypescaleKey, typescale, and exposed as variant options on the Text component
• Variable font support (Roboto Flex) not implemented; M3 Expressive recommends variable fonts for richer editorial expression

---

Text Input

MD3 spec: Text fields
Specs link: https://m3.material.io/components/text-fields/specs

Tracked separately: Implement a new TextInput component

---

Toggle Button

No standalone MD3 equivalent. The toggle behavior (selected/unselected state) is part of Icon button in the MD3 spec. This component should be folded into the IconButton implementation or removed in favor of IconButton with a selected prop.

---

Tooltip

MD3 spec: Tooltips
Specs link: https://m3.material.io/components/tooltips/specs

Color tokens

• Container background uses theme.colors.onSurface; spec requires inverseSurface
• Text color uses theme.colors.surface; spec requires inverseOnSurface

Shape

• borderRadius: theme.roundness = 4dp matches corner.extraSmall ✅

Spacing / sizing

• Container height 32dp ✅
• Text variant is labelLarge (14sp); spec requires bodySmall (12sp)

Behavior

• Rich tooltip variant not implemented. MD3 defines two variants: plain (text only) and rich (optional title, body text, link, and action buttons). The current title: string prop cannot support rich content
• No pointer/caret indicator (not required by spec) ✅

Animation

• No enter/exit animation. MD3 specifies a fade transition on show/hide

---

Touchable Ripple

Library primitive that wraps Pressable (Android) and a custom ripple view (iOS/web) to provide MD3 state-layer feedback. No direct MD3 component equivalent.

Notes

• TouchableRipple does not support PlatformColor, which blocks dynamic theme support for ripple colors. The MD3 spec requires per-component ripple colors (e.g. primary at pressed opacity for filled buttons, onSurface for others), but expressing those as PlatformColor values is not yet possible
• As a workaround, a single hardcoded stateLayerPressed value (onSurface at md.sys.state.pressed.state-layer-opacity) is used as the ripple color uniformly across all components in both LightTheme and DarkTheme. This diverges from spec but is the only viable approach until facebook/react-native#56395 lands