ADR 0009: Gluestack UI v3 + NativeWind 4 Design System

Status: Accepted
Date: 2026-04-17
Deciders: Ideony team

Context

Ideony’s mobile app requires a cross-platform (iOS, Android, Web) component library with accessibility, dark mode, and a copy-paste model to allow deep customisation without fighting a black-box component system. The initial Phase 6 implementation used raw StyleSheet.create; Phase 7B formalised the design system.

Decision

Adopt Gluestack UI v3 with NativeWind 4 (Tailwind CSS for React Native) as the design system. Components are copy-pasted into the codebase (shadcn model), not imported as opaque npm packages. New components use NativeWind utility classes; legacy StyleSheet.create code coexists during migration. Phosphor Icons (duotone) are used for nav/tabs; lucide-react-native for inline icons.

Consequences

Copy-paste model gives full control over component internals without upstream breakage risk.
NativeWind maps Tailwind utilities to React Native styles, enabling shared vocabulary with web developers.
40+ accessible Gluestack components reduce custom a11y implementation burden.
Gluestack is Expo-first; no native rebuild required for most component changes.

NativeWind deferred in initial phases — old StyleSheet.create code coexists, creating inconsistency during migration window.
NativeWind class names don’t survive Metro’s --clear purge without explicit content paths in Tailwind config.
Dual icon libraries (Phosphor + lucide) add bundle weight; must enforce usage boundary.

Alternatives considered

Tamagui — rejected: complex compiler setup; conflicts with Expo managed workflow.
React Native Paper — rejected: Material Design aesthetic conflicts with Italian Sole brand direction.
Custom components only — rejected: re-implementing accessible components (modals, sheets, inputs) from scratch is high-effort and error-prone.