ginskill-init 2.7.0

package/skills/react-native-expo/SKILL.md

@@ -0,0 +1,128 @@
+---
+name: react-native-expo
+description: |
+  **React Native Expo (Sty AI Mobile)**: Production patterns for the Sty AI React Native app — Expo SDK 54, Expo Router v5, React Query v5, Zustand v5, Reanimated v4, FlashList v2, MMKV, BottomSheet v5, react-hook-form + zod, and the full Sty AI design system.
+  - MANDATORY TRIGGERS: react native, expo, mobile app, screen, component, navigation, route, tab, stack, modal, animation, reanimated, gesture, flash list, flatlist, list performance, bottom sheet, form, validation, zod, state management, zustand, store, query, mutation, api call, fetch data, image, expo-image, styling, theme, color, typography, spacing, font, button, card, skeleton, shimmer, toast, dialog, upload, camera, photo, push notification, deep link, branch, auth, login, onboarding, keyboard, MMKV, storage, cache, i18n, localization, live activity, adapty, subscription, in-app purchase, analytics, airbridge, facebook sdk
+  - Use this skill whenever working on ANY file in the styai-mobile directory, creating new screens/components, debugging mobile issues, optimizing performance, or reviewing mobile code. Also trigger when discussing React Native architecture, Expo configuration, or mobile-specific patterns — even casual mentions like 'fix this screen' or 'add a button'.
+---
+
+# React Native Expo — Sty AI Mobile
+
+Production-grade skill for the Sty AI React Native mobile app (Expo SDK 54, New Architecture, Hermes).
+
+## Quick Start — Load Only What You Need
+
+Before writing code, read the correct reference file based on the task:
+
+| Task | Reference File |
+|------|---------------|
+| Screens, routes, navigation, tabs, modals | `references/navigation.md` |
+| React Query hooks, API calls, mutations | `references/data-layer.md` |
+| Zustand stores, MMKV, global state | `references/state-management.md` |
+| Animations, gestures, Reanimated, lists | `references/performance.md` |
+| Theme, colors, typography, spacing, scaling | `references/design-system.md` |
+| Forms, validation, zod, bottom sheets | `references/ui-patterns.md` |
+| Auth, notifications, deep links, i18n, analytics | `references/platform-services.md` |
+
+Read ONLY the relevant reference file(s) for the current task. This keeps token usage minimal.
+
+## Project Identity
+
+- **App**: Sty AI — AI-powered wardrobe management
+- **Bundle**: `app.styai.android` (Android) / `dev.jerrypham.easycloset` (iOS)
+- **Stack**: Expo SDK 54, React Native 0.81, React 19, TypeScript 5.9
+- **Package Manager**: pnpm
+- **Font**: Poppins (300-900 weights, platform-specific families)
+- **Design**: Sophisticated minimal with rose/blush brand accent (#EC4899)
+
+## Architecture at a Glance
+
+```
+styai-mobile/src/
+  app/           # Route files (thin delegators to screens)
+  screens/       # Actual screen logic (mirrors app/ structure)
+  models/        # Domain models: _services/, _types/, _ui/, _store/
+  features/      # Cross-cutting features (auth, credit, stylist, etc.)
+  shared/        # Shared infrastructure
+    components/  # Typography, Button, BottomSheet, shimmer, toast
+    hooks/       # use-auth-init, use-push-notifications, use-infinite-scroll
+    libs/        # api-client (Axios + auto-refresh), token-storage (Keychain)
+    stores/      # Zustand stores with slices pattern
+    theme/       # Design tokens: color, typography, spacing, scaling
+    services/    # Singletons: logger, airbridge, facebook, push
+    types/       # PaginatedResponse<T>, IdRes, TimeStampRes, ApiError
+    constant/    # ROUTES object, enums
+    utils/       # Helpers: compress-image, date, logger, share-app
+  components/    # (deprecated — use shared/components/)
+```
+
+## Critical Rules
+
+1. **Route files are thin delegators** — actual logic lives in `src/screens/`
+2. **Always use `Typography`** instead of raw `<Text>`
+3. **Always use `Theme.color.*`** semantic tokens, never raw hex values
+4. **Always use `useShallow`** when selecting multiple fields from Zustand
+5. **Query keys = API URL path strings** (e.g., `"/api/v1/item"`)
+6. **All API calls through `client`** from `@/shared/libs/api-client`
+7. **Use `expo-image`** (`Image` from `expo-image`), not React Native's `Image`
+8. **Use `FlashList`** for lists, never `FlatList`
+9. **Use `Spacing.*`** semantic tokens for all spacing values
+10. **Platform fonts differ**: iOS uses `Poppins-Medium`, Android uses `Poppins_500Medium` — always use `typefaceBase` or `withFontWeight()`, never hardcode font names
+
+## Path Aliases
+
+```
+@/*            → ./src/*
+@auth/*        → ./src/features/auth/*
+@testimonials/* → ./src/assets/images/testimonials/*
+assets/*       → ./assets/*
+```
+
+## Commands
+
+```bash
+pnpm start              # Dev server (Metro)
+pnpm ios                # iOS device
+pnpm android            # Android emulator
+pnpm type-check         # TypeScript check
+pnpm lint:fix           # ESLint + auto-fix
+pnpm test               # Jest
+pnpm prebuild           # Regenerate native code
+pnpm cng:development    # Full dev env setup
+```
+
+## Key Dependencies
+
+| Package | Version | Use |
+|---------|---------|-----|
+| `expo` | 54 | Framework (New Arch, Hermes) |
+| `expo-router` | 6 | File-based routing (v5 API) |
+| `@tanstack/react-query` | 5 | Server state |
+| `zustand` | 5 | Client state |
+| `react-native-mmkv` | 3.1 | Fast sync storage |
+| `react-native-reanimated` | 4.1 | UI-thread animations |
+| `@shopify/flash-list` | 2.0 | High-perf lists (New Arch only) |
+| `@gorhom/bottom-sheet` | 5 | Bottom sheets |
+| `react-hook-form` + `zod` | 7 + 3 | Forms + validation |
+| `expo-image` | 3.0 | Cached images |
+| `react-native-gesture-handler` | 2.28 | Native gestures |
+| `@shopify/react-native-skia` | 2.2 | Canvas drawing |
+| `react-native-keychain` | 10 | Secure JWT storage |
+| `i18next` + `react-i18next` | 25 + 16 | i18n (9 languages) |
+| `react-native-adapty` | 3.15 | Subscriptions |
+| `airbridge-expo-sdk` | 4.8 | Analytics |
+| `lottie-react-native` | 7.3 | Lottie animations |
+| `date-fns` / `dayjs` | 4 / 1.11 | Date utils |
+| `axios` | 1.11 | HTTP client (wrapped) |
+| `react-native-svg` | 15.12 | SVG rendering |
+| `ai` + `@ai-sdk/react` | 4 + 1 | AI SDK streaming |
+
+## New Code Placement
+
+- **New model** → `src/models/<model-name>/` with `_services/`, `_types/`
+- **New screen** → `src/screens/` + thin delegator in `src/app/`
+- **New shared component** → `src/shared/components/`
+- **New hook** → `src/shared/hooks/` or model's `_hooks/`
+- **New store** → `src/shared/stores/` (Zustand) or feature's `_stores/`
+- **New feature** → `src/features/<feature-name>/`
+- **DO NOT** add to `src/components/` (deprecated)

package/skills/react-native-expo/references/data-layer.md

@@ -0,0 +1,252 @@
+# Data Layer — React Query v5 + API Client
+
+## API Client (`@/shared/libs/api-client`)
+
+Custom Axios wrapper with:
+- **Auto token injection** via request interceptor
+- **401 auto-refresh** with single-flight pattern (max 2 retries, prevents race conditions)
+- **FormData fallback** to native `fetch` (Axios has RN FormData issues)
+- **Credit header parsing**: Response interceptor reads `x-credits-balance` and `x-credits-used` headers
+- **Custom headers**: `User-Agent`, `X-Client-Type: mobile`, `Accept-Language`
+- Base URL from `EXPO_PUBLIC_API_URL` env var
+- Android emulator: `localhost` auto-replaced with `10.0.2.2`
+
+```typescript
+import { client } from "@/shared/libs/api-client"
+
+// Standard requests
+const { data } = await client.get<ItemRes[]>("/api/v1/item")
+const { data } = await client.post<ItemRes>("/api/v1/item", body)
+const { data } = await client.patch<ItemRes>(`/api/v1/item/${id}`, body)
+await client.delete(`/api/v1/item/${id}`)
+
+// FormData (auto falls back to native fetch)
+const formData = new FormData()
+formData.append("file", { uri, type, name } as any)
+const { data } = await client.post("/api/v1/upload", formData, {
+  headers: { "X-FormData-Upload": "true" },
+})
+```
+
+## Service Pattern — One Hook Per File
+
+Each query/mutation lives in its own file under `_services/`:
+
+```
+src/models/item/_services/
+  use-get-items.ts         # useInfiniteQuery
+  use-get-item-detail.ts   # useQuery
+  use-create-item.ts       # useMutation
+  use-update-item.ts       # useMutation
+  use-delete-item.ts       # useMutation
+```
+
+### Query Key Convention
+
+Query keys are **always the API URL path string**:
+
+```typescript
+export const ITEM_INFINITE_LIST_QUERY_KEY = "/api/v1/item"
+export const ITEM_DETAIL_QUERY_KEY = "/api/v1/item/detail"
+export const CATEGORIES_QUERY_KEY = "/api/v1/category"
+```
+
+### useQuery Pattern
+
+```typescript
+import { useQuery } from "@tanstack/react-query"
+import { client } from "@/shared/libs/api-client"
+
+export const ITEM_DETAIL_QUERY_KEY = "/api/v1/item/detail"
+
+export const useGetItemDetail = (id: string) => {
+  return useQuery({
+    queryKey: [ITEM_DETAIL_QUERY_KEY, id],
+    queryFn: async () => {
+      const { data } = await client.get<ItemDetailPopulated>(`/api/v1/item/${id}`)
+      return data
+    },
+    enabled: !!id,
+  })
+}
+```
+
+### useInfiniteQuery Pattern
+
+```typescript
+import { useInfiniteQuery } from "@tanstack/react-query"
+
+export const ITEM_INFINITE_LIST_QUERY_KEY = "/api/v1/item"
+
+export const useGetItemInfiniteList = (params?: ItemListParams, opts?: { enabled?: boolean }) => {
+  const limit = 20
+  const query = useInfiniteQuery({
+    queryKey: [ITEM_INFINITE_LIST_QUERY_KEY, limit, params],
+    initialPageParam: 0,
+    queryFn: async ({ pageParam }) => {
+      const { data } = await client.get<PaginatedResponse<ItemRes>>(ITEM_INFINITE_LIST_QUERY_KEY, {
+        params: { limit, skip: pageParam, paging_count: pageParam === 0, ...params },
+      })
+      return data
+    },
+    getNextPageParam: (lastPage, allPages) => {
+      if ((lastPage?.data?.length ?? 0) < limit) return undefined
+      return allPages.reduce((sum, p) => sum + (p?.data?.length ?? 0), 0)
+    },
+    enabled: opts?.enabled,
+  })
+
+  // Flatten pages
+  const items = query.data?.pages.flatMap((p) => p.data) ?? []
+  const firstMeta = query.data?.pages?.[0]?.meta
+
+  return { items, meta: firstMeta, ...query }
+}
+```
+
+Usage with FlashList + infinite scroll:
+```typescript
+const { items, fetchNextPage, hasNextPage, isFetchingNextPage } = useGetItemInfiniteList()
+const { onEndReached } = useInfiniteScroll({ fetchNextPage, hasNextPage, isFetchingNextPage })
+
+<FlashList
+  data={items}
+  renderItem={renderItem}
+  estimatedItemSize={120}
+  onEndReached={onEndReached}
+  onEndReachedThreshold={0.5}
+  ListFooterComponent={isFetchingNextPage ? <ActivityIndicator /> : null}
+/>
+```
+
+### useMutation Pattern
+
+```typescript
+import { useMutation, useQueryClient } from "@tanstack/react-query"
+import { showErrorToast } from "@/shared/components/toast"
+import { logEvent } from "@/shared/utils/log-event"
+
+export const useUpdateItem = () => {
+  const queryClient = useQueryClient()
+
+  const { mutate, isPending, error } = useMutation({
+    mutationFn: async ({ _id, body }: { _id: string; body: UpdateItemBody }) => {
+      return (await client.patch<ItemRes>(`/api/v1/item/${_id}`, body)).data
+    },
+    onSuccess: () => {
+      queryClient.invalidateQueries({ queryKey: [ITEM_INFINITE_LIST_QUERY_KEY] })
+      queryClient.invalidateQueries({ queryKey: [ITEM_DETAIL_QUERY_KEY] })
+      logEvent("item_updated")
+    },
+    onError: () => {
+      showErrorToast("Update Failed", "Could not update the item. Please try again.")
+    },
+  })
+
+  return { updateItem: mutate, isUpdatingItem: isPending, updateItemError: error }
+}
+```
+
+### Optimistic Updates
+
+```typescript
+export const useToggleFavorite = () => {
+  const queryClient = useQueryClient()
+
+  return useMutation({
+    mutationFn: async (id: string) => (await client.patch(`/api/v1/item/${id}/favorite`)).data,
+    onMutate: async (id) => {
+      await queryClient.cancelQueries({ queryKey: [ITEM_DETAIL_QUERY_KEY, id] })
+      const previous = queryClient.getQueryData([ITEM_DETAIL_QUERY_KEY, id])
+      queryClient.setQueryData([ITEM_DETAIL_QUERY_KEY, id], (old: any) => ({
+        ...old,
+        isFavorite: !old.isFavorite,
+      }))
+      return { previous }
+    },
+    onError: (_err, id, context) => {
+      queryClient.setQueryData([ITEM_DETAIL_QUERY_KEY, id], context?.previous)
+    },
+    onSettled: (_data, _err, id) => {
+      queryClient.invalidateQueries({ queryKey: [ITEM_DETAIL_QUERY_KEY, id] })
+    },
+  })
+}
+```
+
+### Async Service Pattern (for Zustand stores)
+
+```typescript
+// Non-hook function for use inside Zustand slices
+export const getStyBalance = async (): Promise<StyBalance> => {
+  const response = await client.get<StyBalance>(GET_STY_BALANCE_QUERY_KEY)
+  return response.data
+}
+```
+
+## Type Patterns
+
+Types extend shared bases from `@/shared/types/`:
+
+```typescript
+import { IdRes, TimeStampRes } from "@/shared/types"
+
+// Response type (composition pattern)
+type ItemRes = {
+  name: string
+  image_url: string
+  category_id: string
+  blurhash?: string
+} & IdRes & TimeStampRes
+// IdRes = { _id: string }
+// TimeStampRes = { created_at: string; updated_at: string }
+
+// Populated type (nested objects expanded)
+type ItemDetailPopulated = Omit<ItemRes, "styles" | "occasions"> & {
+  styles: FashionStyleRes[]
+  occasions: FashionOccasionRes[]
+}
+
+// Paginated response
+type PaginatedResponse<T> = {
+  data: T[]
+  meta: PaginationMeta  // page, take, item_count, page_count, has_next_page
+}
+```
+
+## React Query Provider Setup
+
+```typescript
+// src/shared/providers/react-query-provider.tsx
+// - Sets online manager from expo-network (device connectivity)
+// - Sets focus manager from AppState (refetch on app focus)
+// - Exports queryClient singleton
+```
+
+## Token Storage (`@/shared/libs/token-storage`)
+
+Secure JWT storage via `react-native-keychain`:
+
+```typescript
+import { storeTokens, getAccessToken, clearTokens, hasValidTokens, validateTokenIntegrity } from "@/shared/libs/token-storage"
+
+await storeTokens({ accessToken, refreshToken })
+const token = await getAccessToken()
+await clearTokens()  // On sign-out
+const isValid = await hasValidTokens()
+```
+
+## Best Practices
+
+- **One query/mutation hook per file** — named `use-get-*.ts` or `use-create-*.ts`
+- **Export `QUERY_KEY` constant** from every query file
+- **Query key = API URL path** — always a string constant
+- **Always `invalidateQueries`** in mutation `onSuccess`
+- **Always `showErrorToast`** in mutation `onError`
+- **Always `logEvent`** for analytics in mutation `onSuccess`
+- **Use `enabled` option** to prevent queries without required params
+- **Use `useInfiniteQuery`** for paginated lists, never manual page tracking
+- **Flatten pages** in the hook: `data?.pages.flatMap((p) => p.data) ?? []`
+- **Distinguish loading states**: `isLoading` (initial), `isFetching` (refetch), `isPending` (mutation)
+- **Never import axios directly** — always use `client` from `api-client`
+- **FormData uploads** need `"X-FormData-Upload": "true"` header

package/skills/react-native-expo/references/design-system.md

@@ -0,0 +1,252 @@
+# Design System — Theme, Colors, Typography, Spacing
+
+## Theme Usage
+
+Always import from `@/shared/theme`:
+
+```typescript
+import { Theme, Spacing, scale, moderateScale, withFontWeight } from "@/shared/theme"
+
+Theme.color.brand          // #EC4899
+Theme.color.text           // #262626
+Theme.typography.b1        // { fontSize: 16, lineHeight: 24, fontFamily: "Poppins-Regular" }
+Spacing.lg                 // 16
+```
+
+## Color System
+
+Sophisticated minimal with rose/blush brand accent. **Always use semantic tokens, never raw hex.**
+
+### Brand Colors (use sparingly)
+
+| Token | Value | Use |
+|-------|-------|-----|
+| `brand` | `#EC4899` | Primary brand (buttons, links) |
+| `brandLight` | `#FFE4E9` | Light accent backgrounds |
+| `brandSubtle` | `#FFF1F3` | Super light tint |
+| `brandDark` | `#BE185D` | Dark brand emphasis |
+| `brandText` | `#DB2777` | Brand-colored text |
+
+### Backgrounds
+
+| Token | Value | Use |
+|-------|-------|-----|
+| `background` | `#F6F6F9` | Screen background |
+| `backgroundSubtle` | `#EDEDF0` | Secondary background |
+| `backgroundElevated` | `#FFFFFF` | Cards, elevated surfaces |
+| `backgroundInverse` | `#171717` | Dark backgrounds |
+
+### Text
+
+| Token | Value | Use |
+|-------|-------|-----|
+| `text` | `#262626` | Primary text |
+| `textSecondary` | `#737373` | Secondary/muted |
+| `textTertiary` | `#A3A3A3` | Placeholder, disabled |
+| `textInverse` | `#FFFFFF` | On dark backgrounds |
+| `textBrand` | `#DB2777` | Brand-colored text |
+
+### Borders
+
+| Token | Value | Use |
+|-------|-------|-----|
+| `border` | `#E5E5E5` | Default |
+| `borderSubtle` | `#EDEDED` | Subtle |
+| `borderStrong` | `#D4D4D4` | Emphasized |
+| `borderBrand` | `#FDA4B8` | Brand accent |
+
+### Interactive States
+
+`interactive` (brand), `interactiveHover`, `interactiveActive`, `interactiveSubtle` (bg), `interactiveMuted` (selected bg)
+
+### Status Colors
+
+| Status | Main | Subtle | Muted | Text |
+|--------|------|--------|-------|------|
+| Success | `#22C55E` | `#F0FDF4` | `#DCFCE7` | `#15803D` |
+| Warning | `#F59E0B` | `#FFFBEB` | `#FEF3C7` | `#B45309` |
+| Error | `#EF4444` | `#FEF2F2` | `#FEE2E2` | `#B91C1C` |
+
+### Special Tokens
+
+`overlay` (rgba 0.5), `scrim` (rgba 0.6 for modals), `skeleton` (#E5E5E5), `disabled` (#D4D4D4), `focus` (#F87198), `ripple` (rgba 0.08 for Android)
+
+## Typography
+
+Font: **Poppins** (Google Fonts, weights 300-900)
+
+### Variants
+
+| Variant | Size | Height | Weight | Use |
+|---------|------|--------|--------|-----|
+| `xxl` | 72 | 80 | ExtraBold | Hero numbers |
+| `h1` | 22 | 33 | Bold | Page titles |
+| `h2` | 20 | 30 | Medium | Section headings |
+| `h3` | 18 | 27 | Medium | Sub-headings |
+| `b1` | 16 | 24 | Regular | Body text |
+| `b2` | 14 | 21 | Regular | Small body |
+| `b3` | 12 | 18 | Regular | Captions, labels |
+
+### Usage
+
+```typescript
+import { Typography } from "@/shared/components"
+
+<Typography variant="h1">Page Title</Typography>
+<Typography variant="b2" color={Theme.color.textSecondary}>Subtitle</Typography>
+```
+
+### Font Weight Override
+
+**Always use `withFontWeight()`** — never set fontWeight directly (breaks Android):
+
+```typescript
+import { withFontWeight } from "@/shared/theme"
+
+// CORRECT: Maps to correct platform font family
+const boldBody = withFontWeight(Theme.typography.b1, "700")
+
+// WRONG: Breaks on Android (fontWeight without matching fontFamily)
+const bad = { ...Theme.typography.b1, fontWeight: "700" }
+```
+
+### Platform Font Families
+
+| Weight | iOS | Android |
+|--------|-----|---------|
+| 300 | `Poppins-Light` | `Poppins_300Light` |
+| 400 | `Poppins-Regular` | `Poppins_400Regular` |
+| 500 | `Poppins-Medium` | `Poppins_500Medium` |
+| 600 | `Poppins-SemiBold` | `Poppins_600SemiBold` |
+| 700 | `Poppins-Bold` | `Poppins_700Bold` |
+| 800 | `Poppins-ExtraBold` | `Poppins_800ExtraBold` |
+
+Typography component: `maxFontSizeMultiplier = 1.15` (prevents OS font scaling issues).
+
+## Spacing System
+
+4-point grid. **Always use `Spacing.*` tokens.**
+
+### Component Spacing
+
+| Token | Value | Use |
+|-------|-------|-----|
+| `xs` | 4 | Tight elements |
+| `sm` | 8 | Compact layouts |
+| `md` | 12 | Standard gaps |
+| `lg` | 16 | Comfortable gaps |
+| `xl` | 20 | Emphasis |
+| `xxl` | 24 | Section spacing |
+| `xxxl` | 32 | Large sections |
+
+### Layout Spacing
+
+| Token | Value | Use |
+|-------|-------|-----|
+| `screenHorizontal` | 16 | Screen padding L/R |
+| `screenVertical` | 24 | Screen padding T/B |
+| `sectionGap` | 24 | Between sections |
+| `cardPadding` | 16 | Card internal padding |
+| `cardInnerGap` | 12 | Gap inside cards |
+| `cardRadius` | 16 | Standard card radius |
+| `cardRadiusLarge` | 20 | Hero card radius |
+| `touchTarget` | 44 | Min touch size (iOS HIG) |
+| `listItemGap` | 12 | Between list items |
+
+## Responsive Scaling
+
+Baseline: 375x812 (iPhone 13/14)
+
+```typescript
+import { scale, verticalScale, moderateScale, DeviceSize } from "@/shared/theme"
+
+scale(16)              // Linear horizontal scaling
+verticalScale(24)      // Linear vertical scaling
+moderateScale(16)      // Dampened (factor=0.5, recommended default)
+moderateScale(16, 0.3) // Less aggressive
+
+// Device breakpoints
+DeviceSize.isSmall   // < 360px (older devices)
+DeviceSize.isMedium  // 360-399px (mid-range)
+DeviceSize.isLarge   // >= 400px (standard+)
+```
+
+Use `moderateScale` for text/padding, `scale` for widths/icons, raw values for tokens/borders.
+
+## Shadow Pattern
+
+```typescript
+const styles = StyleSheet.create({
+  card: {
+    backgroundColor: Theme.color.backgroundElevated,
+    borderRadius: Spacing.cardRadius,
+    padding: Spacing.cardPadding,
+    shadowColor: Theme.color.shadowColor,
+    shadowOffset: { width: 0, height: 2 },
+    shadowOpacity: 0.08,
+    shadowRadius: 8,
+    elevation: 3, // Android
+  },
+})
+```
+
+## Standard Card Pattern
+
+Consistent card style used across all sections (overview, lists, settings):
+
+```typescript
+const styles = StyleSheet.create({
+  card: {
+    backgroundColor: Theme.color.backgroundElevated,
+    borderRadius: Spacing.cardRadius,       // 16
+    padding: Spacing.cardPadding,           // 16
+    borderWidth: 1,
+    borderColor: Theme.color.border,
+  },
+})
+```
+
+For hero/featured cards, use `brandSubtle` background with `brandLight` border:
+```typescript
+heroCard: {
+  backgroundColor: Theme.color.brandSubtle,
+  borderRadius: Spacing.cardRadius,
+  padding: Spacing.cardPadding,
+  borderWidth: 1,
+  borderColor: Theme.color.brandLight,
+}
+```
+
+## Progress Bar Pattern
+
+Standard progress bar: 4px height, 2px radius, `backgroundMuted` track, `brand` fill.
+Use status colors (error/warning) only for actual error/warning states.
+
+```typescript
+progressTrack: {
+  height: 4,
+  borderRadius: 2,
+  backgroundColor: Theme.color.backgroundMuted,
+  overflow: "hidden",
+},
+progressFill: {
+  height: "100%",
+  borderRadius: 2,
+  backgroundColor: Theme.color.brand,   // Default — use consistently
+},
+```
+
+## Safe Area in Modals
+
+For absolute-positioned elements inside modals (e.g., close button in fullscreen image viewer),
+`SafeAreaView` doesn't reliably apply insets. Use `useSafeAreaInsets()` with explicit padding:
+
+```typescript
+const insets = useSafeAreaInsets()
+const topPadding = insets.top + (Platform.OS === "ios" ? 8 : 12)
+
+<View style={{ paddingTop: topPadding }}>
+  <TouchableOpacity onPress={onClose}>...</TouchableOpacity>
+</View>
+```
+```