Jan 5, 2026

React Native Paper

Problem Statement

React Native Paper (RNP) gives us useful components out of the box, but its theming and component anatomy don’t match Material 3 (M3) or our web design system. That mismatch causes UI drift, slows cross-platform work, and increases maintenance.

Current State

  • Fragmented toolkits with mix of responsive web and native app ui components
  • Guidance and documentation is limited for app specific guidance
  • We're in the midst of updating our visual styles, trying to course correct to reduce duplicative efforts and/or reduce throwaway work long term.

Assumptions

  • Mobile app is leveraging React Native Paper to deliver an app experience for iOS and Android.

Constraints

  • No programatic color scale
  • Native icon collection (Google Symbols)
  • M3 Expressions for Native Android Users
  • iOS 26 for iPhone users
  • Need to scale to support various device types across operating system

Approach

  • Analyze out of box React Native paper design system package (DSP).
  • Identify areas where React Native Paper and M3 are not 1:1 to reflect in Figma.
  • Instead of prioritizing entire component groups with all potential variations, focus on smaller bite size to not bloat dev capacity solely on design system.

Short term

  • Tokens: RNP’s theme shape and naming don’t line up with M3 semantic tokens — we need a translation layer so web and mobile share the same source of truth.
  • Color & Theming: M3 uses tonal palettes and semantic roles; RNP exposes theme objects but lacks tonal generation. This affects brand color fidelity and dark-mode behavior.
  • Typography: RNP uses presets; M3 is token-driven (display/headline/body/label). Mapping is straightforward but requires review across components.
  • Components: Anatomy and props differ for buttons, text fields, app bars, cards, etc. Some components need small tweaks; a few require larger refactors for parity.
  • Elevation & Surfaces: Surface blending and elevation tokens don’t match; visual differences will surface across cards, dialogs, and sheets.
  • Developer ergonomics: Web uses CSS tokens; RN uses JS themes — we must automate token generation or provide a stable mapping to avoid duplicate work.