From 4d4a5e8484de98ff185084e50af3d1f288def2c6 Mon Sep 17 00:00:00 2001 From: ignaciosantise <25931366+ignaciosantise@users.noreply.github.com> Date: Thu, 22 Jan 2026 12:21:50 -0300 Subject: [PATCH 1/4] docs: add AGENTS.md and CLAUDE.md for SDK documentation Add comprehensive AGENTS.md with SDK overview, architecture patterns, UI system details, and agent guidance. Add CLAUDE.md as a reference link to AGENTS.md. Co-Authored-By: Claude Haiku 4.5 --- AGENTS.md | 288 ++++++++++++++++++++++++++++++++++++++++++++++++++++++ CLAUDE.md | 1 + 2 files changed, 289 insertions(+) create mode 100644 AGENTS.md create mode 100644 CLAUDE.md diff --git a/AGENTS.md b/AGENTS.md new file mode 100644 index 00000000..e67ea6f3 --- /dev/null +++ b/AGENTS.md @@ -0,0 +1,288 @@ +# AppKit React Native SDK + +## SDK Overview + +**AppKit React Native** is a multichain web3 library by Reown that enables React Native applications to connect users with cryptocurrency wallets and interact with blockchain networks. + +### Core Functionality + +- **Wallet Connection**: Multi-wallet support via WalletConnect protocol and custom connectors (Coinbase, Phantom, etc.) +- **Multichain Support**: EVM (Ethereum, Polygon, Arbitrum, etc.), Solana, and Bitcoin +- **User Authentication**: Sign-In With X (SIWX) for decentralized authentication +- **DeFi Features**: Token swaps, on-ramp/off-ramp, transaction monitoring +- **Native Modal UI**: Pre-built, customizable React Native components +- **Theme Support**: Light/dark themes with customization options + +### Monorepo Structure + +``` +packages/ +├── core/ # Controllers, utilities, core business logic (@reown/appkit-core-react-native) +├── appkit/ # Main SDK entry point, hooks, components (@reown/appkit-react-native) +├── ui/ # Reusable UI components (@reown/appkit-ui-react-native) +├── common/ # Shared types, constants, utilities (@reown/appkit-common-react-native) +├── ethers/ # EVM adapter using ethers.js (@reown/appkit-ethers-react-native) +├── wagmi/ # EVM adapter using wagmi (@reown/appkit-wagmi-react-native) +├── solana/ # Solana blockchain adapter (@reown/appkit-solana-react-native) +├── bitcoin/ # Bitcoin blockchain adapter (@reown/appkit-bitcoin-react-native) +├── coinbase/ # Coinbase wallet connector (@reown/appkit-coinbase-react-native) +└── cli/ # CLI tools (@reown/appkit-cli-react-native) + +apps/ +├── native/ # Example React Native Expo app +└── gallery/ # UI component showcase +``` + +### Architectural Patterns + +**Controller Pattern (Valtio)** +State management via reactive controllers: +- `ModalController` - Modal visibility and state +- `RouterController` - Navigation between views +- `ConnectionsController` - Wallet connections and networks +- `SwapController` - Token swap operations +- `SendController` - Transfer operations +- `TransactionsController` - Transaction history + +**Adapter Pattern** +Blockchain-specific implementations: +- `BlockchainAdapter` - Base interface +- EVM adapters (Ethers, Wagmi) +- Solana adapter +- Bitcoin adapter + +**Connector Pattern** +Wallet connection methods: +- `WalletConnectConnector` - Default WalletConnect protocol +- Custom connectors for Coinbase, Phantom, etc. + +### Tech Stack + +- React Native 0.76+ +- TypeScript 5.2+ +- Valtio (state management) +- WalletConnect v2 +- Ethers.js / Wagmi (EVM) +- Solana Web3.js + +--- + +## UI System + +### Package Structure + +The UI layer is split between two packages: + +``` +packages/ui/src/ # Reusable UI library (@reown/appkit-ui-react-native) +├── components/ # 13 base primitives (Card, Icon, Text, Image, Modal, etc.) +├── composites/ # 42 feature-rich components (Button, ListItem, InputText, etc.) +├── layout/ # 3 layout helpers (FlexView, Overlay, Separator) +├── context/ # ThemeContext and ThemeProvider +├── hooks/ # useTheme, useAnimatedValue, useCustomDimensions +├── utils/ # UiUtil, ThemeUtil, TypesUtil, TransactionUtil +└── assets/ # SVG icons + +packages/appkit/src/ # AppKit-specific UI (@reown/appkit-react-native) +├── modal/ # Modal wrapper and router +├── views/ # 23 route views (Connect, Account, Swap, Networks, etc.) +└── partials/ # 24 AppKit-specific composites (Header, Snackbar, QrCode, etc.) +``` + +### Component Hierarchy + +**Base Components** (`packages/ui/src/components/`): +- `wui-card` - Container with themed background/border +- `wui-icon` - SVG icon renderer (60+ icons) +- `wui-text` - Typography with 24 variants +- `wui-image` - Image loader with error handling +- `wui-modal` - Animated bottom sheet +- `wui-pressable` - Base pressable wrapper +- `wui-shimmer` - Loading skeleton +- `wui-loading-spinner` - Loading indicator + +**Composite Components** (`packages/ui/src/composites/`): +- `wui-button` - Primary button (size: sm/md, variant: fill/shade/accent) +- `wui-list-item` - Pressable list item with animations +- `wui-input-text` - Animated text input with focus states +- `wui-card-select` - Wallet/Network selector card +- `wui-tabs` - Animated tab switcher +- `wui-qr-code` - QR code with embedded logo +- `wui-snackbar` - Toast notification +- `wui-avatar` - Address-based avatar with gradient + +**Layout Components** (`packages/ui/src/layout/`): +- `FlexView` - Flex container replacing View (supports gap, padding arrays) +- `Overlay` - Semi-transparent overlay +- `Separator` - Divider with optional text + +### Theming System + +**Theme Colors** (62 keys in DarkTheme/LightTheme): +- `accent-100` to `accent-020` - Primary brand colors +- `fg-100` to `fg-300` - Foreground/text colors +- `bg-100` to `bg-300` - Background colors +- `success-100`, `error-100` - Semantic colors +- `gray-glass-001` to `gray-glass-090` - Glass morphism overlays + +**Design Tokens**: +``` +Spacing: '0' | '4xs' | '3xs' | '2xs' | 'xs' | 's' | 'm' | 'l' | 'xl' | '2xl' | '3xl' | '4xl' + 0 2 4 6 8 12 14 16 20 24 32 40 (px) + +BorderRadius: '5xs' | '4xs' | '3xs' | 'xxs' | 'xs' | 's' | 'm' | 'l' | '3xl' | 'full' + 4 6 8 12 16 20 28 36 80 100 (px) +``` + +**Typography** (24 variants): +- Sizes: `medium-title`, `large`, `paragraph`, `small`, `tiny`, `micro` +- Weights: `400`, `500`, `600` +- Example: `paragraph-500`, `small-400` + +**Using Theme**: +```typescript +const Theme = useTheme() +// Returns themed color object that responds to light/dark mode +``` + +### Animation Patterns + +All animations use React Native's `Animated` API with native driver for GPU acceleration. + +**Modal Animation**: +- Opening: Spring physics (damping: 25, stiffness: 220) +- Closing: Timing animation (150ms) for snappy UX +- Backdrop: Opacity fade (300ms in, 250ms out) + +**Component Animations**: +- `useAnimatedValue` hook for color interpolation on press states +- `Animated.createAnimatedComponent(Pressable)` for interactive elements +- Color transitions between normal/pressed states + +### Views and Router + +**RouterController** manages navigation between 23 views: +- Account flows: `Account`, `AccountDefault` +- Connection: `Connect`, `ConnectingSocials`, `ConnectingExternal`, `WalletConnect` +- Networks: `Networks`, `NetworkSwitch`, `UnsupportedChain` +- OnRamp: `OnRamp`, `OnRampCheckout`, `OnRampSettings` +- Swap: `Swap`, `SwapPreview` +- Wallet: `WalletReceive`, `WalletSend`, `WalletSendPreview` +- Info: `WhatIsANetwork`, `WhatIsAWallet` + +**View Pattern**: +```typescript +export function MyView() { + const snapshot = useSnapshot(ControllerState) + const { padding } = useCustomDimensions() + + return ( + + + {/* Content */} + + + ) +} +``` + +### Common UI Patterns + +**FlexView Layout**: +```typescript + +``` + +**List Item**: +```typescript + + {name} + +``` + +**Button**: +```typescript + +``` + +### UI Guidelines for Agents + +1. **Use existing components** - Never create custom primitives; use the `wui-*` components +2. **Follow theme system** - All colors must come from theme, no hardcoded hex values +3. **Use FlexView** - Prefer FlexView over View for layout consistency +4. **Spacing tokens** - Use spacing tokens ('xs', 's', 'm', etc.) not pixel values +5. **Animation consistency** - Use `useAnimatedValue` hook for press state animations +6. **Memoize list items** - Use `React.memo` with custom comparison for expensive list items +7. **Test both themes** - Verify changes work in both light and dark mode + +--- + +## Agent Guidance + +### Code Quality Requirements + +**Before pushing any solution, always run:** +```bash +yarn format # Prettier formatting +yarn lint # ESLint checks +yarn test # Jest tests +``` + +Follow existing code style in the codebase. Do not deviate from established patterns. + +### Platform Compatibility + +This SDK must work for both **Expo** and **React Native CLI** projects. Ensure any changes are compatible with both environments. + +### Dependency Policy + +**Keep external third-party dependencies minimal.** Avoid adding new libraries if possible - the SDK must remain lightweight. If a new dependency is absolutely necessary, justify it clearly. + +### Key Abstractions + +- **Adapters**: Blockchain-specific implementations (one per chain type) +- **Connectors**: Wallet connection methods +- **Controllers**: Valtio-based reactive state containers +- **Namespaces**: CAIP-style chain identifiers (e.g., `eip155:1` for Ethereum mainnet) +- **CAIP Addresses**: Chain-agnostic addresses (e.g., `eip155:1:0x...`) + +### Important Files + +``` +packages/appkit/src/AppKit.ts # Main SDK class (~900 LOC) +packages/appkit/src/hooks/ # React hooks (useAppKit, useAccount, etc.) +packages/core/src/controllers/ # State management controllers +packages/common/src/ # Shared types and network definitions +packages/ethers/src/adapter.ts # EVM adapter implementation +packages/solana/src/ # Solana adapter +packages/bitcoin/src/ # Bitcoin adapter +``` + +### Development Commands + +```bash +yarn install # Install dependencies +yarn ios # Run example on iOS simulator +yarn android # Run example on Android emulator +yarn build # Build all packages +yarn lint # Run ESLint +yarn test # Run Jest tests +yarn format # Run Prettier +``` + +### Commit Convention + +Follow conventional commits: `fix:`, `feat:`, `refactor:`, `docs:`, `test:`, `chore:` diff --git a/CLAUDE.md b/CLAUDE.md new file mode 100644 index 00000000..c3170642 --- /dev/null +++ b/CLAUDE.md @@ -0,0 +1 @@ +AGENTS.md From 4fa91364ccda4d0e6ef068447b0358a7b82597aa Mon Sep 17 00:00:00 2001 From: ignaciosantise <25931366+ignaciosantise@users.noreply.github.com> Date: Thu, 22 Jan 2026 12:34:05 -0300 Subject: [PATCH 2/4] docs: address PR review comments in AGENTS.md MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - Fix base components count (13 → 11) - Fix React Native version (0.76+ → 0.72+ with tested note) - Fix typography variants (24 → 23, add 700 weight) - Clarify animation patterns (native driver vs JS-driven) - Update RouterController views to reference source file Co-Authored-By: Claude Haiku 4.5 --- AGENTS.md | 40 +++++++++++++++++++++------------------- 1 file changed, 21 insertions(+), 19 deletions(-) diff --git a/AGENTS.md b/AGENTS.md index e67ea6f3..f6644996 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -58,7 +58,7 @@ Wallet connection methods: ### Tech Stack -- React Native 0.76+ +- React Native 0.72+ (tested with 0.76+) - TypeScript 5.2+ - Valtio (state management) - WalletConnect v2 @@ -75,7 +75,7 @@ The UI layer is split between two packages: ``` packages/ui/src/ # Reusable UI library (@reown/appkit-ui-react-native) -├── components/ # 13 base primitives (Card, Icon, Text, Image, Modal, etc.) +├── components/ # 11 base primitives (Card, Icon, Text, Image, Modal, etc.) ├── composites/ # 42 feature-rich components (Button, ListItem, InputText, etc.) ├── layout/ # 3 layout helpers (FlexView, Overlay, Separator) ├── context/ # ThemeContext and ThemeProvider @@ -85,7 +85,7 @@ packages/ui/src/ # Reusable UI library (@reown/appkit-ui-react-nati packages/appkit/src/ # AppKit-specific UI (@reown/appkit-react-native) ├── modal/ # Modal wrapper and router -├── views/ # 23 route views (Connect, Account, Swap, Networks, etc.) +├── views/ # Route views (Connect, Account, Swap, Networks, etc.) └── partials/ # 24 AppKit-specific composites (Header, Snackbar, QrCode, etc.) ``` @@ -94,7 +94,7 @@ packages/appkit/src/ # AppKit-specific UI (@reown/appkit-react-native) **Base Components** (`packages/ui/src/components/`): - `wui-card` - Container with themed background/border - `wui-icon` - SVG icon renderer (60+ icons) -- `wui-text` - Typography with 24 variants +- `wui-text` - Typography with 23 variants - `wui-image` - Image loader with error handling - `wui-modal` - Animated bottom sheet - `wui-pressable` - Base pressable wrapper @@ -134,10 +134,10 @@ BorderRadius: '5xs' | '4xs' | '3xs' | 'xxs' | 'xs' | 's' | 'm' | 'l' | '3xl' | ' 4 6 8 12 16 20 28 36 80 100 (px) ``` -**Typography** (24 variants): -- Sizes: `medium-title`, `large`, `paragraph`, `small`, `tiny`, `micro` -- Weights: `400`, `500`, `600` -- Example: `paragraph-500`, `small-400` +**Typography** (23 variants): +- Sizes: `medium-title`, `small-title`, `large`, `medium`, `paragraph`, `small`, `tiny`, `micro` +- Weights: `400`, `500`, `600`, `700` +- Example: `paragraph-500`, `small-400`, `micro-700` **Using Theme**: ```typescript @@ -147,28 +147,30 @@ const Theme = useTheme() ### Animation Patterns -All animations use React Native's `Animated` API with native driver for GPU acceleration. +Animations use React Native's `Animated` API, preferring the native driver for GPU-accelerated properties (opacity, transforms) and falling back to `useNativeDriver: false` when animating unsupported properties like colors. -**Modal Animation**: +**Modal Animation** (native driver): - Opening: Spring physics (damping: 25, stiffness: 220) - Closing: Timing animation (150ms) for snappy UX - Backdrop: Opacity fade (300ms in, 250ms out) -**Component Animations**: +**Component Animations** (JS-driven, `useNativeDriver: false`): - `useAnimatedValue` hook for color interpolation on press states - `Animated.createAnimatedComponent(Pressable)` for interactive elements - Color transitions between normal/pressed states ### Views and Router -**RouterController** manages navigation between 23 views: -- Account flows: `Account`, `AccountDefault` -- Connection: `Connect`, `ConnectingSocials`, `ConnectingExternal`, `WalletConnect` -- Networks: `Networks`, `NetworkSwitch`, `UnsupportedChain` -- OnRamp: `OnRamp`, `OnRampCheckout`, `OnRampSettings` -- Swap: `Swap`, `SwapPreview` -- Wallet: `WalletReceive`, `WalletSend`, `WalletSendPreview` -- Info: `WhatIsANetwork`, `WhatIsAWallet` +**RouterController** manages navigation between views defined in `RouterControllerState` (see `packages/core/src/controllers/RouterController.ts` for the up-to-date list of route IDs). + +View categories: +- Account flows (account overview and default account views) +- Connection flows (social logins, external wallets, WalletConnect, etc.) +- Network management (network selection, switching, unsupported network messaging) +- On-ramp experiences (on-ramp setup, checkout, loading, settings) +- Swap flows (swap entry and swap preview/review) +- Wallet actions (receiving, sending, send preview/review) +- Informational views (e.g., "What is a network?", "What is a wallet?") **View Pattern**: ```typescript From 37dd058bf269c687daf91ab15ed8b1c62ca3fd7f Mon Sep 17 00:00:00 2001 From: ignaciosantise <25931366+ignaciosantise@users.noreply.github.com> Date: Thu, 22 Jan 2026 12:37:47 -0300 Subject: [PATCH 3/4] style: fix prettier formatting in AGENTS.md Co-Authored-By: Claude Haiku 4.5 --- AGENTS.md | 20 +++++++++++++++++++- 1 file changed, 19 insertions(+), 1 deletion(-) diff --git a/AGENTS.md b/AGENTS.md index f6644996..fd0d7b4a 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -37,6 +37,7 @@ apps/ **Controller Pattern (Valtio)** State management via reactive controllers: + - `ModalController` - Modal visibility and state - `RouterController` - Navigation between views - `ConnectionsController` - Wallet connections and networks @@ -46,6 +47,7 @@ State management via reactive controllers: **Adapter Pattern** Blockchain-specific implementations: + - `BlockchainAdapter` - Base interface - EVM adapters (Ethers, Wagmi) - Solana adapter @@ -53,6 +55,7 @@ Blockchain-specific implementations: **Connector Pattern** Wallet connection methods: + - `WalletConnectConnector` - Default WalletConnect protocol - Custom connectors for Coinbase, Phantom, etc. @@ -92,6 +95,7 @@ packages/appkit/src/ # AppKit-specific UI (@reown/appkit-react-native) ### Component Hierarchy **Base Components** (`packages/ui/src/components/`): + - `wui-card` - Container with themed background/border - `wui-icon` - SVG icon renderer (60+ icons) - `wui-text` - Typography with 23 variants @@ -102,6 +106,7 @@ packages/appkit/src/ # AppKit-specific UI (@reown/appkit-react-native) - `wui-loading-spinner` - Loading indicator **Composite Components** (`packages/ui/src/composites/`): + - `wui-button` - Primary button (size: sm/md, variant: fill/shade/accent) - `wui-list-item` - Pressable list item with animations - `wui-input-text` - Animated text input with focus states @@ -112,6 +117,7 @@ packages/appkit/src/ # AppKit-specific UI (@reown/appkit-react-native) - `wui-avatar` - Address-based avatar with gradient **Layout Components** (`packages/ui/src/layout/`): + - `FlexView` - Flex container replacing View (supports gap, padding arrays) - `Overlay` - Semi-transparent overlay - `Separator` - Divider with optional text @@ -119,6 +125,7 @@ packages/appkit/src/ # AppKit-specific UI (@reown/appkit-react-native) ### Theming System **Theme Colors** (62 keys in DarkTheme/LightTheme): + - `accent-100` to `accent-020` - Primary brand colors - `fg-100` to `fg-300` - Foreground/text colors - `bg-100` to `bg-300` - Background colors @@ -126,6 +133,7 @@ packages/appkit/src/ # AppKit-specific UI (@reown/appkit-react-native) - `gray-glass-001` to `gray-glass-090` - Glass morphism overlays **Design Tokens**: + ``` Spacing: '0' | '4xs' | '3xs' | '2xs' | 'xs' | 's' | 'm' | 'l' | 'xl' | '2xl' | '3xl' | '4xl' 0 2 4 6 8 12 14 16 20 24 32 40 (px) @@ -135,13 +143,15 @@ BorderRadius: '5xs' | '4xs' | '3xs' | 'xxs' | 'xs' | 's' | 'm' | 'l' | '3xl' | ' ``` **Typography** (23 variants): + - Sizes: `medium-title`, `small-title`, `large`, `medium`, `paragraph`, `small`, `tiny`, `micro` - Weights: `400`, `500`, `600`, `700` - Example: `paragraph-500`, `small-400`, `micro-700` **Using Theme**: + ```typescript -const Theme = useTheme() +const Theme = useTheme(); // Returns themed color object that responds to light/dark mode ``` @@ -150,11 +160,13 @@ const Theme = useTheme() Animations use React Native's `Animated` API, preferring the native driver for GPU-accelerated properties (opacity, transforms) and falling back to `useNativeDriver: false` when animating unsupported properties like colors. **Modal Animation** (native driver): + - Opening: Spring physics (damping: 25, stiffness: 220) - Closing: Timing animation (150ms) for snappy UX - Backdrop: Opacity fade (300ms in, 250ms out) **Component Animations** (JS-driven, `useNativeDriver: false`): + - `useAnimatedValue` hook for color interpolation on press states - `Animated.createAnimatedComponent(Pressable)` for interactive elements - Color transitions between normal/pressed states @@ -164,6 +176,7 @@ Animations use React Native's `Animated` API, preferring the native driver for G **RouterController** manages navigation between views defined in `RouterControllerState` (see `packages/core/src/controllers/RouterController.ts` for the up-to-date list of route IDs). View categories: + - Account flows (account overview and default account views) - Connection flows (social logins, external wallets, WalletConnect, etc.) - Network management (network selection, switching, unsupported network messaging) @@ -173,6 +186,7 @@ View categories: - Informational views (e.g., "What is a network?", "What is a wallet?") **View Pattern**: + ```typescript export function MyView() { const snapshot = useSnapshot(ControllerState) @@ -191,6 +205,7 @@ export function MyView() { ### Common UI Patterns **FlexView Layout**: + ```typescript Connect Wallet @@ -237,6 +254,7 @@ export function MyView() { ### Code Quality Requirements **Before pushing any solution, always run:** + ```bash yarn format # Prettier formatting yarn lint # ESLint checks From 36db6f75468290adbed004db2eff9551fdf21024 Mon Sep 17 00:00:00 2001 From: ignaciosantise <25931366+ignaciosantise@users.noreply.github.com> Date: Thu, 22 Jan 2026 12:43:29 -0300 Subject: [PATCH 4/4] style: additional prettier formatting fixes Co-Authored-By: Claude Haiku 4.5 --- AGENTS.md | 22 ++++++++-------------- 1 file changed, 8 insertions(+), 14 deletions(-) diff --git a/AGENTS.md b/AGENTS.md index fd0d7b4a..022415ba 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -189,16 +189,14 @@ View categories: ```typescript export function MyView() { - const snapshot = useSnapshot(ControllerState) - const { padding } = useCustomDimensions() + const snapshot = useSnapshot(ControllerState); + const { padding } = useCustomDimensions(); return ( - - {/* Content */} - + {/* Content */} - ) + ); } ``` @@ -218,14 +216,10 @@ export function MyView() { **List Item**: ```typescript - - {name} + + + {name} + ```