@yahoo/uds-mobile 1.0.0

package/CONTRIBUTING.md

@@ -0,0 +1,1174 @@
+# Contributing to @yahoo/uds-mobile
+
+This guide covers the internal architecture and development workflow for the UDS Mobile package.
+
+## Table of Contents
+
+- [Architecture Overview](#architecture-overview)
+- [Architecture Proposals](#architecture-proposals)
+- [Dependency Bundling](#dependency-bundling)
+- [Generated Files](#generated-files)
+- [Code Generation Pipeline](#code-generation-pipeline)
+- [Theme Generation](#theme-generation)
+- [Component Styling System](#component-styling-system)
+- [Unistyles Patterns](#unistyles-patterns)
+- [Reanimated + Unistyles](#reanimated--unistyles)
+- [Development Workflow](#development-workflow)
+- [Adding New Components](#adding-new-components)
+- [Debugging](#debugging)
+
+## Architecture Overview
+
+The `@yahoo/uds-mobile` package provides React Native components styled with [Unistyles](https://www.unistyl.es//). The package has two distinct concerns:
+
+1. **Library Code** (`src/`): Components, hooks, and utilities
+2. **Generated Code** (`generated/`): Auto-generated styles and types from UDS tokens
+
+```
+packages/mobile/
+├── bin/                    # CLI tools for consumers
+│   ├── uds-mobile.ts       # Main CLI entry (sync command)
+│   └── generateTheme.ts    # Theme generation logic
+├── scripts/                # Internal code generation
+│   ├── generate.ts         # Main orchestrator
+│   ├── generateStyles.ts   # Generates styles.ts
+│   ├── generateTypes.ts    # Generates unistyles.d.ts
+│   ├── generateFonts.ts    # Generates font manifests
+│   └── utils/              # Generation utilities
+├── src/
+│   ├── components/         # React Native components
+│   ├── generated/          # AUTO-GENERATED (do not edit)
+│   │   ├── styles.ts       # Unistyles variants
+│   │   └── unistyles.d.ts  # Type declarations
+│   ├── types.ts            # Exported types
+│   ├── motion.ts           # Animation utilities
+│   └── index.ts            # Public exports
+├── fonts/                  # Font files + generated manifests
+└── docs/
+    ├── proposals/          # Architecture proposals and recommendations
+    └── *.md                # Architecture decision records and issue documentation
+```
+
+## Architecture Proposals
+
+See [docs/proposals/](./docs/proposals/) for architectural proposals and recommendations for improving the mobile package and UDS ecosystem:
+
+- **[PACKAGE_DECOMPOSITION_BENEFITS.md](./docs/proposals/PACKAGE_DECOMPOSITION_BENEFITS.md)** - Proposal to extract shared types, fixtures, and motion tokens into separate packages
+- **[CONFIG_TRANSFORMATION_ARCHITECTURE.md](./docs/proposals/CONFIG_TRANSFORMATION_ARCHITECTURE.md)** - Proposal for platform-specific config transformation architecture
+- **[HARDCODED_VALUES.md](./docs/proposals/HARDCODED_VALUES.md)** - Documentation of hardcoded values that should come from design tokens
+
+## Dependency Bundling
+
+The mobile package bundles both `@yahoo/uds` and `@yahoo/uds-icons` into its distribution. This means consumers do **not** need to install these packages separately.
+
+### What Gets Bundled
+
+- **Runtime JS**: Both packages' JavaScript code via `noExternal: ['@yahoo/uds', '@yahoo/uds-icons']`
+- **TypeScript types**: Both packages' type definitions via `dts.resolve: ['@yahoo/uds', '@yahoo/uds-icons']`
+
+This produces two folders in `dist/`:
+
+- `dist/uds/` - Bundled `@yahoo/uds` code and types
+- `dist/icons/` - Bundled `@yahoo/uds-icons` code and types
+
+### Why Both Packages Are Bundled Together
+
+We bundle both packages because of a technical constraint in TypeScript declaration bundling: **you cannot bundle `@yahoo/uds` types without also bundling `@yahoo/uds-icons` types**.
+
+The `@yahoo/uds` web package has components that directly import from `@yahoo/uds-icons` (e.g., `ChipDismissible` imports `Cross`, `Menu.ItemCheckbox` imports `Check`). When `dts.resolve` bundles `@yahoo/uds` types, it follows these import references transitively and automatically bundles `@yahoo/uds-icons` types as well.
+
+There is no way to configure the bundler to "bundle A but keep B external" when A references B - it's all-or-nothing.
+
+**See [docs/BUNDLING_UDS_AND_ICONS.md](./docs/BUNDLING_UDS_AND_ICONS.md) for:**
+
+- Detailed technical explanation
+- Why standard solutions (external array, subpath imports) don't work
+- Future roadmap for making `@yahoo/uds-icons` a peer dependency
+
+## Generated Files
+
+### `generated/styles.ts`
+
+This is the most important generated file. It contains all Unistyles stylesheets that map UDS design tokens to React Native styles.
+
+**What it contains:**
+
+1. **Foundation styles** (`styles.foundation`): Base style variants for layout props
+   - `backgroundColor`, `borderRadius`, `spacing`, `color`, `fontFamily`, etc.
+   - Maps UDS token names to theme paths (e.g., `'primary'` → `theme.colors.background['primary']`)
+
+2. **Component styles** (`avatarStyles`, `buttonStyles`, etc.): Per-component stylesheets
+   - Uses Unistyles `variants` and `compoundVariants` for state management
+   - Each component has layers: `root`, `text`, `icon`, etc. matching structure from UDS config.
+
+**Example input** (from `uds.config.ts` - see `packages/configurator/uds.config.ts`):
+
+```typescript
+import type { UniversalTokensConfig } from '@yahoo/uds';
+
+export const config: UniversalTokensConfig = {
+  // Component configs use path-based keys: '{dimension}/{value}/{layer}'
+  button: {
+    defaults: {
+      size: 'md',
+      variant: 'primary',
+    },
+    variables: {
+      // Size variants
+      'size/lg/root': {
+        gap: {
+          rest: { type: 'spacingAliases', value: '2', valueType: 'alias' },
+        },
+        spacingHorizontal: {
+          rest: { type: 'spacingAliases', value: '5', valueType: 'alias' },
+        },
+        textVariant: {
+          rest: { type: 'textVariants', value: 'label1', valueType: 'alias' },
+        },
+      },
+      'size/md/root': {
+        gap: {
+          rest: { type: 'spacingAliases', value: '1.5', valueType: 'alias' },
+        },
+        spacingHorizontal: {
+          rest: { type: 'spacingAliases', value: '4', valueType: 'alias' },
+        },
+      },
+      // Variant styles with states (rest, pressed, disabled)
+      'variant/primary/root': {
+        backgroundColor: {
+          rest: { type: 'backgroundPaletteColors', value: 'accent', valueType: 'alias' },
+          pressed: { type: 'spectrumColors', value: 'carbon-5', valueType: 'alias' },
+          disabled: { type: 'backgroundPaletteColors', value: 'accent', valueType: 'alias' },
+        },
+        borderRadius: {
+          rest: { type: 'borderRadii', value: 'md', valueType: 'alias' },
+        },
+      },
+      'variant/primary/icon': {
+        color: {
+          rest: { type: 'foregroundPaletteColors', value: 'on-color', valueType: 'alias' },
+        },
+      },
+    },
+  },
+  // ... other components (avatar, badge, checkbox, etc.)
+};
+```
+
+**Example output** (generated `styles.ts`):
+
+```typescript
+// Foundation variants
+export const styles = StyleSheet.create((theme) => ({
+  foundation: {
+    variants: {
+      backgroundColor: {
+        primary: { backgroundColor: theme.colors.background['primary'] },
+        secondary: { backgroundColor: theme.colors.background['secondary'] },
+        // ...
+      },
+      spacing: {
+        '4': { padding: theme.spacing['4'] },
+        // ...
+      },
+    },
+  },
+}));
+
+// Component variants
+export const buttonStyles = StyleSheet.create((theme) => ({
+  root: {
+    variants: {
+      size: {
+        lg: theme.components['button/size/lg/root/rest'],
+        md: theme.components['button/size/md/root/rest'],
+      },
+      variant: {
+        primary: theme.components['button/variant/primary/root/rest'],
+        // ...
+      },
+      disabled: { true: {} },
+      pressed: { true: {} },
+    },
+    compoundVariants: [
+      {
+        variant: 'primary',
+        pressed: true,
+        styles: theme.components['button/variant/primary/root/pressed'],
+      },
+      // ...
+    ],
+  },
+}));
+```
+
+### Web vs Mobile: Generated Styles Comparison
+
+The mobile `styles.ts` serves the same purpose as `packages/uds/src/styles/variants.ts` on web, but with key architectural differences:
+
+**Web (`variants.ts`)** - Maps UDS props to **CSS class names**:
+
+```typescript
+// Web uses Tailwind-style class names
+export const variants = {
+  backgroundColor: {
+    primary: 'bg-primary', // CSS class
+    secondary: 'bg-secondary',
+    accent: 'bg-accent',
+  },
+  spacing: {
+    '4': 'p-4', // Tailwind padding class
+  },
+  borderRadius: {
+    md: 'rounded-md',
+  },
+};
+```
+
+**Mobile (`styles.ts`)** - Maps UDS props to **React Native style objects**:
+
+```typescript
+// Mobile uses Unistyles theme references
+export const styles = StyleSheet.create((theme) => ({
+  foundation: {
+    variants: {
+      backgroundColor: {
+        primary: { backgroundColor: theme.colors.background['primary'] }, // RN style
+        secondary: { backgroundColor: theme.colors.background['secondary'] },
+      },
+      spacing: {
+        '4': { padding: theme.spacing['4'] }, // Numeric value from theme
+      },
+      borderRadius: {
+        md: { borderRadius: theme.borderRadius['md'] },
+      },
+    },
+  },
+}));
+```
+
+| Aspect        | Web                                               | Mobile                                                        |
+| ------------- | ------------------------------------------------- | ------------------------------------------------------------- |
+| Output format | CSS class names (`'bg-primary'`)                  | RN style objects (`{ backgroundColor: ... }`)                 |
+| Theming       | CSS custom properties (`var(--color-bg-primary)`) | Unistyles theme object (`theme.colors.background['primary']`) |
+| Dark mode     | CSS class toggle (`.dark`)                        | Unistyles theme switching                                     |
+| File location | `packages/uds/src/styles/variants.ts`             | `packages/mobile/generated/styles.ts`                         |
+
+### Component Styles Comparison
+
+For component-level styles, the pattern is similar but maps to component-specific theme values:
+
+**Web (`autoVariants.ts`)** - Maps component variants to **CSS class names**:
+
+```typescript
+// packages/uds/generated/autoVariants.ts
+export const autoVariants = {
+  buttonVariantRoot: {
+    primary: 'uds-button-variant-primary-root', // CSS class
+    secondary: 'uds-button-variant-secondary-root',
+    brand: 'uds-button-variant-brand-root',
+  },
+  buttonSizeRoot: {
+    lg: 'uds-button-size-lg-root',
+    md: 'uds-button-size-md-root',
+    sm: 'uds-button-size-sm-root',
+  },
+  buttonVariantIcon: {
+    primary: 'uds-button-variant-primary-icon',
+    secondary: 'uds-button-variant-secondary-icon',
+  },
+};
+```
+
+**Mobile (`styles.ts`)** - Maps component variants to **theme component style objects**:
+
+```typescript
+// packages/mobile/generated/styles.ts
+export const buttonStyles = StyleSheet.create((theme) => ({
+  root: {
+    variants: {
+      size: {
+        lg: theme.components['button/size/lg/root/rest'], // RN style object
+        md: theme.components['button/size/md/root/rest'],
+        sm: theme.components['button/size/sm/root/rest'],
+      },
+      variant: {
+        primary: theme.components['button/variant/primary/root/rest'],
+        secondary: theme.components['button/variant/secondary/root/rest'],
+        brand: theme.components['button/variant/brand/root/rest'],
+      },
+      disabled: { true: {} },
+      pressed: { true: {} },
+    },
+    compoundVariants: [
+      {
+        variant: 'primary',
+        pressed: true,
+        styles: theme.components['button/variant/primary/root/pressed'],
+      },
+      {
+        variant: 'primary',
+        disabled: true,
+        styles: theme.components['button/variant/primary/root/disabled'],
+      },
+    ],
+  },
+  text: {
+    variants: {
+      variant: {
+        primary: theme.components['button/variant/primary/text/rest'],
+        secondary: theme.components['button/variant/secondary/text/rest'],
+      },
+    },
+  },
+  icon: {
+    variants: {
+      size: {
+        lg: theme.components['button/size/lg/icon/rest'],
+        md: theme.components['button/size/md/icon/rest'],
+      },
+      variant: {
+        primary: theme.components['button/variant/primary/icon/rest'],
+        secondary: theme.components['button/variant/secondary/icon/rest'],
+      },
+    },
+  },
+}));
+```
+
+| Aspect         | Web                                      | Mobile                                               |
+| -------------- | ---------------------------------------- | ---------------------------------------------------- |
+| Key format     | camelCase (`buttonVariantRoot`)          | Slash-separated (`button/variant/primary/root/rest`) |
+| State handling | Separate class toggle                    | `compoundVariants` with pressed/disabled states      |
+| Multi-layer    | Separate keys per layer (`Root`, `Icon`) | Nested style objects (`root`, `text`, `icon`)        |
+| Theme access   | CSS variables in classes                 | Direct theme object reference                        |
+
+### Generated Theme Shape
+
+The theme exists in two forms:
+
+1. **TypeScript types** (`generated/unistyles.d.ts`) - Generated by `scripts/generateTypes.ts` during package development. These provide full type safety for component development without needing actual runtime values. This is what allows IDE autocomplete and type checking in `styles.ts`.
+
+2. **JavaScript runtime values** - Generated when consumers run `uds-mobile sync`. This creates the actual theme object with real color values, spacing numbers, etc. in their app (e.g., `lib/unistyles.uds.ts`).
+
+This separation means we can develop type-safe components in the package without bundling theme values, while consumers get their own themed values at sync time.
+
+Here's the theme shape (from the generated types):
+
+```typescript
+// Generated theme structure (simplified)
+interface AppTheme {
+  // Foundation tokens
+  colors: {
+    background: { primary: string; secondary: string; brand: string /* ... */ };
+    foreground: { primary: string; secondary: string /* ... */ };
+    line: { primary: string; secondary: string /* ... */ };
+    spectrum: { 'gray-0': string; 'gray-1': string /* ... */ };
+  };
+  spacing: { '0': number; '1': number; '2': number /* ... */ };
+  borderRadius: { none: number; sm: number; md: number; lg: number; full: number };
+  borderWidth: { none: number; sm: number; md: number /* ... */ };
+  iconSize: { sm: number; md: number; lg: number /* ... */ };
+  typography: { 'body-md': TypographyVariant; 'heading-lg': TypographyVariant /* ... */ };
+  shadow: { sm: ShadowValue; md: ShadowValue /* ... */ };
+  font: { 'YahooSans-Bold': string; 'YahooSans-Regular': string /* ... */ };
+
+  // Component-specific styles (flat key structure)
+  components: {
+    'button/size/lg/root/rest': { gap: number; paddingHorizontal: number; paddingVertical: number };
+    'button/size/md/root/rest': { gap: number; paddingHorizontal: number; paddingVertical: number };
+    'button/variant/primary/root/rest': { backgroundColor: string /* ... */ };
+    'button/variant/primary/root/pressed': { backgroundColor: string /* ... */ };
+    'button/variant/primary/root/disabled': { opacity: number /* ... */ };
+    'button/variant/primary/text/rest': { color: string /* ... */ };
+    'button/variant/primary/icon/rest': { color: string /* ... */ };
+    // ... hundreds more component style entries
+  };
+}
+```
+
+#### Component Key Format
+
+Component styles use a slash-separated key format:
+
+```
+{component}/{dimension}/{value}/{layer}/{state}
+```
+
+| Segment     | Description                                       | Examples                           |
+| ----------- | ------------------------------------------------- | ---------------------------------- |
+| `component` | Component name                                    | `button`, `badge`, `avatar`        |
+| `dimension` | Variant dimension (size, variant, or nested type) | `size`, `variant`, `icon/variant`  |
+| `value`     | Specific value for that dimension                 | `lg`, `md`, `primary`, `secondary` |
+| `layer`     | UI layer within the component                     | `root`, `text`, `icon`, `rootText` |
+| `state`     | Interaction state                                 | `rest`, `pressed`, `disabled`      |
+
+Examples:
+
+- `button/size/lg/root/rest` → Button, size=lg, root layer, rest state
+- `button/variant/primary/icon/pressed` → Button, variant=primary, icon layer, pressed state
+- `avatar/icon/variant/secondary/root/rest` → Avatar (icon type), variant=secondary, root layer
+
+This flat structure allows `styles.ts` to reference exact theme values:
+
+```typescript
+// In styles.ts
+export const buttonStyles = StyleSheet.create((theme) => ({
+  root: {
+    variants: {
+      size: {
+        lg: theme.components['button/size/lg/root/rest'], // ← Direct lookup
+        md: theme.components['button/size/md/root/rest'],
+      },
+    },
+  },
+}));
+```
+
+### How Unistyles Variants Work
+
+Unistyles variants allow styles to change based on props passed to `useVariants()`. The structure can be confusing at first because of the nesting, so here's a breakdown:
+
+#### Basic Structure
+
+```typescript
+const buttonStyles = StyleSheet.create((theme) => ({
+  // Each top-level key is a "layer" (root, text, icon, etc.)
+  root: {
+    // Base styles applied to ALL variants
+    flexDirection: 'row',
+    alignItems: 'center',
+
+    // Variants object defines conditional styles
+    variants: {
+      // Each key here is a "variant dimension" (size, variant, disabled, etc.)
+      size: {
+        // Each nested key is a possible value for that dimension
+        lg: { paddingHorizontal: 24, paddingVertical: 16 },
+        md: { paddingHorizontal: 16, paddingVertical: 12 },
+        sm: { paddingHorizontal: 12, paddingVertical: 8 },
+      },
+      variant: {
+        primary: { backgroundColor: theme.colors.background.brand },
+        secondary: { backgroundColor: theme.colors.background.secondary },
+      },
+      // Boolean variants use `true` as the key
+      disabled: {
+        true: { opacity: 0.5 },
+      },
+      pressed: {
+        true: {}, // Empty - handled by compoundVariants
+      },
+    },
+  },
+}));
+```
+
+#### Using Variants in Components
+
+```typescript
+function Button({ size = 'md', variant = 'primary', disabled }) {
+  const [pressed, setPressed] = useState(false);
+
+  // Call useVariants with current prop values
+  // This "selects" which variant styles to apply
+  buttonStyles.useVariants({
+    size,      // 'lg' | 'md' | 'sm'
+    variant,   // 'primary' | 'secondary' | ...
+    disabled,  // true | false
+    pressed,   // true | false
+  });
+
+  return (
+    <Pressable
+      style={buttonStyles.root}  // Styles auto-update based on useVariants
+      onPressIn={() => setPressed(true)}
+      onPressOut={() => setPressed(false)}
+    >
+      <Text style={buttonStyles.text}>Press me</Text>
+    </Pressable>
+  );
+}
+```
+
+#### Style Resolution
+
+When `useVariants({ size: 'lg', variant: 'primary', disabled: false })` is called:
+
+```typescript
+// Final styles for `buttonStyles.root` are merged in order:
+{
+  // 1. Base styles (always applied)
+  flexDirection: 'row',
+  alignItems: 'center',
+
+  // 2. Size variant styles (size: 'lg')
+  paddingHorizontal: 24,
+  paddingVertical: 16,
+
+  // 3. Variant styles (variant: 'primary')
+  backgroundColor: theme.colors.background.brand,
+
+  // 4. Disabled styles (disabled: false → not applied)
+  // opacity: 0.5  ← skipped because disabled is false
+}
+```
+
+#### Compound Variants
+
+Compound variants apply styles when **multiple conditions are true simultaneously**. This is essential for state-specific styling that depends on the variant:
+
+```typescript
+const buttonStyles = StyleSheet.create((theme) => ({
+  root: {
+    variants: {
+      variant: {
+        primary: { backgroundColor: theme.colors.background.brand },
+        secondary: { backgroundColor: theme.colors.background.secondary },
+      },
+      pressed: { true: {} }, // Empty placeholder - actual styles in compoundVariants
+    },
+
+    // Compound variants: apply when ALL specified conditions match
+    compoundVariants: [
+      {
+        variant: 'primary',
+        pressed: true,
+        styles: { backgroundColor: theme.colors.background.brandHover },
+      },
+      {
+        variant: 'secondary',
+        pressed: true,
+        styles: { backgroundColor: theme.colors.background.secondaryHover },
+      },
+    ],
+  },
+}));
+```
+
+**Why compound variants?** Each button variant needs a different pressed color. Without compound variants, you'd need a single `pressed: { true: { ... } }` style that works for all variants—impossible when different variants need different pressed colors.
+
+#### Resolution Order
+
+Styles are merged in this priority (later wins):
+
+1. **Base styles** - Always applied
+2. **Single variants** - Applied when their condition matches
+3. **Compound variants** - Applied when ALL their conditions match (highest priority)
+
+```typescript
+// With useVariants({ variant: 'primary', pressed: true }):
+{
+  // 1. Base: flexDirection, alignItems
+  // 2. variant='primary': backgroundColor: brand
+  // 3. pressed=true: (empty)
+  // 4. COMPOUND (variant='primary' + pressed=true): backgroundColor: brandHover ← wins!
+}
+```
+
+### `generated/unistyles.d.ts`
+
+Type declarations for Unistyles theme augmentation. Ensures TypeScript knows the shape of the theme object.
+
+### `fonts/index.cjs` and `fonts/index.mjs`
+
+Font manifests that export:
+
+- `fonts`: Array of font file paths for Expo's font plugin
+- `fontAliasToPostscript`: Mapping of font IDs to PostScript names (required by React Native)
+
+## Code Generation Pipeline
+
+The generation pipeline runs via `bun scripts/generate.ts` (or `bun run generate`):
+
+```
+┌─────────────────────────────────────────────────────────────────────┐
+│                          generate.ts                                 │
+│   1. generateTypes()   → generated/unistyles.d.ts               │
+│   2. generateStyles()  → generated/styles.ts                    │
+│   3. generateFonts()   → fonts/index.{cjs,mjs}                      │
+└─────────────────────────────────────────────────────────────────────┘
+```
+
+### Step 1: generateTypes.ts
+
+Uses [ts-morph](https://ts-morph.com/) to:
+
+1. Load `@yahoo/uds/tokens` type definitions
+2. Generate a temporary theme using `generateTheme()`
+3. Infer TypeScript types from runtime values
+4. Write `unistyles.d.ts` with proper theme augmentation
+
+### Step 2: generateStyles.ts
+
+The most complex generation step:
+
+1. **Load TypeScript definitions** via ts-morph:
+   - Reads `StyleProps` interfaces from `@yahoo/uds/tokens/types.ts`
+   - Extracts all possible values for each prop (e.g., `backgroundColor: 'primary' | 'secondary' | ...`)
+
+2. **Validate against React Native types**:
+   - Loads Unistyles' `AllAvailableStyles` type
+   - Filters out values not valid in React Native (e.g., `'grid'` for `display`)
+
+3. **Map UDS props to theme paths**:
+   - Uses `themeConfig.ts` to map type names to theme locations
+   - Example: `BackgroundColor` type → `theme.colors.background`
+
+4. **Generate component styles**:
+   - Uses `generateLayerBasedComponentStyles.ts` to create per-component stylesheets
+   - Reads component configs from `@yahoo/uds/tokens`
+   - Maps component keys like `button/size/lg/root/rest` to theme references
+
+5. **Output formatted TypeScript**:
+   - Uses Prettier for consistent formatting
+   - Writes to `generated/styles.ts`
+
+### Step 3: generateFonts.ts
+
+1. Scans `fonts/` directory for `.otf` and `.ttf` files
+2. Uses `fontkit` to extract PostScript names from font files
+3. Generates CommonJS and ESM manifests for Expo compatibility
+
+## Theme Generation
+
+The CLI (`uds-mobile sync`) generates themes for consumer apps:
+
+```
+┌─────────────────────────────────────────────────────────────────────┐
+│                     Consumer App                                     │
+│                                                                      │
+│   uds.config.ts  ──────►  uds-mobile sync  ──────►  unistyles.uds.ts │
+│   (UDS tokens)            (CLI command)             (theme objects)  │
+└─────────────────────────────────────────────────────────────────────┘
+```
+
+### How `generateTheme.ts` works:
+
+1. **Input**: `UniversalTokensConfig` from `@yahoo/uds/tokens`
+
+2. **Color Processing**:
+   - Generates spectrum colors (hue + step combinations)
+   - Creates semantic colors (background, foreground, line)
+   - Handles `always/*` colors that don't change with theme
+
+3. **Typography**:
+   - Converts CSS font-family + weight to PostScript names
+   - React Native requires PostScript names for custom fonts
+
+4. **Component Styles**:
+   - Flattens component config into key-value pairs
+   - Keys use format: `component/variant/value/layer/state`
+   - Example: `button/variant/primary/root/pressed`
+
+5. **Output**: Light and dark theme objects ready for Unistyles
+
+### Config Assumptions & Workarounds
+
+The theme generator makes assumptions about config structure. When configs don't honor these assumptions, workarounds are required. These are documented in `packages/mobile/docs/`.
+
+#### Text-Only Props in Root Layers
+
+**Problem:** React Native's `color` only works on `<Text>`, not `<View>`. Config defines `color` in root layers expecting CSS cascade behavior.
+
+**Why it matters:** On web, CSS `color` on a parent cascades to child text. In RN, applying `color` to a `<View>` does nothing—text stays black. Without this workaround, 74 style definitions across 7 components would have broken text colors.
+
+**Workaround:** The generator detects text-only props (`color`) in root layers and extracts them into a separate `rootText` layer, which components apply to their `<Text>` children:
+
+```tsx
+// Generated theme has both layers
+theme.components['button/variant/primary/root/rest']     // backgroundColor, etc.
+theme.components['button/variant/primary/rootText/rest'] // color (for Text)
+
+// Component applies them separately
+<Pressable style={buttonStyles.root}>
+  <Text style={buttonStyles.text}>{children}</Text>  {/* Gets color */}
+</Pressable>
+```
+
+**Affected:** 7 components, 74 root paths (avatar, badge, button, checkbox, chip, link, radio)
+
+See: `docs/TEXT_ONLY_PROPS_WORKAROUND.md`
+
+#### Missing Disabled States
+
+**Problem:** Some components don't define `disabled` state in config but need disabled styling.
+
+**Why it matters:** Users expect disabled components to look disabled. Without config-defined states, the generator can't output disabled styles, so components would look fully interactive even when `disabled={true}`.
+
+**Workaround:** Manual `opacity: 0.5` in component files:
+
+```tsx
+<Pressable
+  disabled={disabled}
+  style={[styles.root, disabled && { opacity: 0.5 }]}
+>
+```
+
+This is hardcoded in each component rather than generated from config.
+
+**Affected:** radio, switch, chip, link, menu, iconButton
+
+See: `docs/MISSING_DISABLED_STATES.md`
+
+#### Always Palette Special Handling
+
+**Problem:** `always/current` uses `currentColor` (CSS-only concept), and `alwaysPaletteAliases` is a separate type not in spectrum.
+
+**Why it matters:** The `always/*` palette contains colors that don't change between light/dark themes (e.g., `always/light`, `always/dark`). But `always/current` maps to CSS `currentColor`—a concept that doesn't exist in React Native. If the generator tried to resolve it, it would crash or produce invalid styles.
+
+**Workaround:**
+
+```typescript
+// In generateTheme.ts
+if (value === 'always/current') {
+  return undefined; // Skip - no RN equivalent
+}
+
+// alwaysPaletteAliases handled separately from spectrum colors
+if (type === 'alwaysPaletteAliases') {
+  return theme.colors.always[value]; // Special lookup
+}
+```
+
+See: `docs/ALWAYS_PALETTE_HANDLING.md`
+
+#### Property Name Inconsistency (`iconSize` vs `size`)
+
+**Problem:** Avatar uses `iconSize` but Button/Badge/Input/Switch use `size` for their icon layers—yet all have type `iconSizes`.
+
+**Why it matters:** The generator maps config properties to React Native style properties. For icon fonts, we need `fontSize` and `lineHeight`. With inconsistent naming, we must handle **both** property names:
+
+```typescript
+// In configToRNMappings.ts - both map to the same RN props
+const propToStyleProps = {
+  iconSize: ['fontSize', 'lineHeight'], // Avatar uses this
+  size: ['fontSize', 'lineHeight'], // Everyone else uses this
+};
+```
+
+Without this, Avatar icons wouldn't get proper sizing.
+
+**Workaround:** Added `fontSize`/`lineHeight` mapping for **both** `iconSize` and `size` properties.
+
+See: `docs/CONFIG_INCONSISTENCIES.md`
+
+#### textStyle vs textVariant
+
+**Problem:** Link config uses `textStyle` as variant name, but component exposes `textVariant` prop.
+
+**Why it matters:** The generated styles use config variant names as keys. When the component prop name differs, you can't directly pass the prop value to the stylesheet:
+
+```tsx
+// Config defines: link/textStyle/body1/root
+// Component receives: textVariant="body1"
+
+// This doesn't work - key mismatch
+linkStyles.useVariants({ textVariant }); // ❌ No 'textVariant' variant
+
+// Must map prop to config key
+linkStyles.useVariants({ textStyle: textVariant }); // ✅ Works
+```
+
+**Workaround:** Link component maps `textVariant` prop to `textStyle` variant key internally.
+
+See: `docs/CONFIG_INCONSISTENCIES.md`
+
+> **📋 Full documentation:** See `packages/mobile/docs/` for all workarounds and their proper fixes.
+
+### Adding New Config Workarounds
+
+When you encounter a new config inconsistency, here's where to add the fix:
+
+| Workaround Type               | File                                       | Purpose                                                                           |
+| ----------------------------- | ------------------------------------------ | --------------------------------------------------------------------------------- |
+| **Property name mapping**     | `scripts/utils/configToRNMappings.ts`      | Map config prop names to RN style props (e.g., `iconSize` → `fontSize`)           |
+| **Text-only prop extraction** | `scripts/utils/configToRNMappings.ts`      | `TEXT_ONLY_PROPS` set — props like `color` that must go on `<Text>`, not `<View>` |
+| **Layer normalization**       | `scripts/utils/generateComponentStyles.ts` | Transform layer names (e.g., `rootText` → `text`)                                 |
+| **Value resolution**          | `bin/generateTheme.ts`                     | Handle special value types (e.g., `alwaysPaletteAliases`)                         |
+| **Type mappings**             | `scripts/utils/typesToThemePaths.ts`       | Map UDS types to theme paths (e.g., `spacingAliases` → `theme.spacing`)           |
+| **Component-level**           | `src/components/[Component].tsx`           | Runtime fixes (e.g., manual `opacity: 0.5` for missing disabled states)           |
+
+#### Workflow for Adding a Workaround
+
+1. **Identify the issue** - What's wrong with the config? Missing state, wrong property name, etc.
+
+2. **Determine the fix location:**
+   - Can it be fixed in generation? → Use scripts/bin files
+   - Must be fixed at runtime? → Use component file
+
+3. **Implement the fix** with clear comments:
+
+   ```typescript
+   // In configToRNMappings.ts
+   // WORKAROUND: Avatar uses 'iconSize' but others use 'size'
+   // See: docs/CONFIG_INCONSISTENCIES.md
+   iconSize: ['fontSize', 'lineHeight'],
+   size: ['fontSize', 'lineHeight'],
+   ```
+
+4. **Document the workaround** in `packages/mobile/docs/`:
+   - Create a new `.md` file or update existing one
+   - Include: Problem, Why it matters, Workaround, Proper fix
+
+5. **Regenerate styles** to verify:
+
+   ```bash
+   cd packages/mobile
+   bun run generate
+   ```
+
+## Component Styling System
+
+### Layer-Based Architecture
+
+Components use a layer-based styling system:
+
+```
+Component
+├── root       # Container/pressable layer
+├── text       # Text content layer (rootText in configs)
+├── icon       # Icon layer
+└── [custom]   # Component-specific layers (e.g., checkbox, handle)
+```
+
+### Variant Key Format
+
+Component styles in the theme use this key format:
+
+```
+{component}/{dimension}/{value}/{layer}/{state}
+
+Examples:
+- button/size/lg/root/rest
+- button/variant/primary/icon/pressed
+- checkbox/variant/primary/value/checked/checkbox/disabled
+```
+
+### Using Component Styles
+
+```typescript
+// In a component
+const { styles: rootStyles } = buttonStyles.useVariants({
+  size: 'md',
+  variant: 'primary',
+  disabled: isDisabled,
+  pressed: isPressed,
+});
+
+return (
+  <Pressable style={rootStyles.root}>
+    <Text style={rootStyles.text}>{children}</Text>
+  </Pressable>
+);
+```
+
+## Unistyles Patterns
+
+### Avoiding useUnistyles Re-renders
+
+`useUnistyles()` hook causes component re-renders on theme changes. For better performance, use **dynamic functions** in stylesheets:
+
+```tsx
+// ❌ Bad: useUnistyles causes re-renders
+import { useUnistyles } from 'react-native-unistyles';
+
+function ColorSwatch({ colorKey }: { colorKey: string }) {
+  const { theme } = useUnistyles();
+  const backgroundColor = theme.colors.background[colorKey];
+  return <View style={{ backgroundColor }} />;
+}
+
+// ✅ Good: Dynamic function in stylesheet (no hook needed)
+import { StyleSheet } from 'react-native-unistyles';
+
+function ColorSwatch({ colorKey }: { colorKey: string }) {
+  return <View style={styles.swatch(colorKey)} />;
+}
+
+const styles = StyleSheet.create((theme) => ({
+  swatch: (colorKey: string) => ({
+    backgroundColor: theme.colors.background[colorKey],
+    width: 64,
+    height: 64,
+  }),
+}));
+```
+
+Dynamic functions can accept multiple parameters:
+
+```tsx
+const styles = StyleSheet.create((theme) => ({
+  container: (maxWidth: number, isOdd: boolean) => ({
+    backgroundColor: theme.colors.background.primary,
+    maxWidth,
+    borderBottomWidth: isOdd ? 1 : undefined,
+  }),
+}));
+
+// Usage
+<View style={styles.container(300, true)} />;
+```
+
+### When to Use Each Approach
+
+| Approach           | Use Case                                    |
+| ------------------ | ------------------------------------------- |
+| Dynamic functions  | Static theme access with parameters         |
+| `useAnimatedTheme` | Animated worklet access (zero re-renders)   |
+| `useUnistyles`     | When you need runtime theme object in logic |
+
+## Reanimated + Unistyles
+
+When animating components, we use Reanimated with Unistyles. There are important patterns and gotchas to follow.
+
+### ⚠️ Critical: Never Mix Styles Inside useAnimatedStyle
+
+**Never spread Unistyles styles inside `useAnimatedStyle`:**
+
+```tsx
+// ❌ BAD: Spreading Unistyles inside useAnimatedStyle
+const animatedStyle = useAnimatedStyle(() => ({
+  ...styles.container, // 💥 Never do this!
+  opacity: opacity.value,
+}));
+
+return <Animated.View style={animatedStyle} />;
+```
+
+**Why this breaks:** This creates a single style object with both Unistyles C++ state and Reanimated animation metadata. Both libraries try to update the same style nodes at the ShadowTree level, causing performance issues and visual bugs.
+
+```tsx
+// ✅ GOOD: Keep styles separate in array
+const animatedStyle = useAnimatedStyle(() => ({
+  opacity: opacity.value,
+}));
+
+return <Animated.View style={[styles.container, animatedStyle]} />;
+```
+
+> **📖 Unistyles docs:** [Reanimated Integration Guide](https://www.unistyl.es/v3/guides/reanimated#:~:text=new%20color%20automatically.-,Merging%20styles,-When%20you%20want)
+
+### Animating Theme Colors
+
+Use `useAnimatedVariantColor` for color properties:
+
+```tsx
+import { useAnimatedVariantColor } from 'react-native-unistyles/reanimated';
+
+const backgroundColor = useAnimatedVariantColor(buttonStyles.root, 'backgroundColor');
+const borderColor = useAnimatedVariantColor(buttonStyles.root, 'borderColor');
+
+const animatedStyle = useAnimatedStyle(() => ({
+  backgroundColor: withTiming(backgroundColor.value, { duration: 220 }),
+  borderColor: withTiming(borderColor.value, { duration: 220 }),
+}));
+```
+
+### Animating Non-Color Theme Values
+
+Use `useAnimatedTheme` for non-color properties (`boxShadow`, etc.):
+
+```tsx
+import { useAnimatedTheme } from 'react-native-unistyles/reanimated';
+
+const animatedTheme = useAnimatedTheme(); // Zero re-renders!
+
+const animatedStyle = useAnimatedStyle(() => {
+  const shadowPressed =
+    animatedTheme.value.components[`button/variant/${variant}/root/pressed`]?.boxShadow ?? '';
+
+  return {
+    boxShadow: interpolateShadowAlpha(shadowPressed, pressProgress.value),
+  };
+});
+```
+
+### State-Driven Animations
+
+Prefer `useDerivedValue` over `useEffect` + `useSharedValue`:
+
+```tsx
+// ❌ Avoid: useEffect pattern
+const progress = useSharedValue(0);
+useEffect(() => {
+  progress.value = withTiming(visible ? 1 : 0);
+}, [visible]);
+
+// ✅ Prefer: useDerivedValue
+const progress = useDerivedValue(() => withTiming(visible ? 1 : 0), [visible]);
+```
+
+**Why:** No `useEffect` overhead, animation computed on UI thread, cleaner dependency tracking.
+
+### Staggered Animations
+
+Use `interpolate` with clamping for staggered effects:
+
+```tsx
+const progress = useDerivedValue(() => withSpring(visible ? 1 : 0, SPRING_CONFIG), [visible]);
+
+const animatedStyle = useAnimatedStyle(() => {
+  // Width animates full range
+  const width = interpolate(progress.value, [0, 1], [0, totalWidth]);
+
+  // Opacity/scale start at 50% progress - creates stagger effect
+  const opacity = interpolate(progress.value, [0.5, 1], [0, 1], 'clamp');
+  const scale = interpolate(progress.value, [0.5, 1], [0.7, 1], 'clamp');
+
+  return { width, opacity, transform: [{ scale }] };
+});
+```
+
+### Worklet Functions
+
+Mark functions that run on the UI thread:
+
+```tsx
+function interpolateShadowAlpha(shadow: string, alpha: number): string {
+  'worklet'; // Required for UI thread execution
+  if (!shadow || alpha >= 1) return shadow;
+  if (alpha <= 0) return '';
+
+  return shadow.replace(/rgba\(([^,]+),\s*([^,]+),\s*([^,]+),\s*([^)]+)\)/g, (_, r, g, b, a) => {
+    const newAlpha = parseFloat(a) * alpha;
+    return `rgba(${r}, ${g}, ${b}, ${newAlpha.toFixed(3)})`;
+  });
+}
+```
+
+### When to Use Each Hook
+
+| Property Type | Hook                      | Example Properties                        |
+| ------------- | ------------------------- | ----------------------------------------- |
+| Colors        | `useAnimatedVariantColor` | `backgroundColor`, `borderColor`, `color` |
+| Non-colors    | `useAnimatedTheme`        | `boxShadow`, `opacity`, custom values     |
+| Computed      | `useDerivedValue`         | Progress values based on props/state      |
+
+## Development Workflow
+
+### Initial Setup
+
+```bash
+# From monorepo root
+bun install
+
+# Build the package
+cd packages/mobile
+bun turbo build
+```
+
+### Making Changes
+
+1. **Components** (`src/components/`): Edit directly, run `bun turbo dev` for watch mode
+2. **Styles generation**: Edit `scripts/generateStyles.ts`, then run `bun run generate`
+3. **Types**: Edit `scripts/generateTypes.ts`, then run `bun run generate`
+4. **Theme generation**: Edit `bin/generateTheme.ts`
+
+### Testing Changes
+
+```bash
+# Run tests
+bun turbo test
+
+# Type check
+bun turbo typecheck
+
+# Lint
+bun turbo lint
+```
+
+### Rebuilding Generated Files
+
+```bash
+bun turbo build
+```
+
+## Adding New Components
+
+### 1. Create the Component File
+
+```typescript
+// src/components/MyComponent.tsx
+import { Pressable, type PressableProps } from 'react-native';
+import { myComponentStyles } from '../generated/styles';
+import { Text } from './Text';
+
+export interface MyComponentProps extends PressableProps {
+  size?: 'sm' | 'md' | 'lg';
+  variant?: 'primary' | 'secondary';
+  children: React.ReactNode;
+}
+
+export function MyComponent({
+  size = 'md',
+  variant = 'primary',
+  disabled,
+  children,
+  ...props
+}: MyComponentProps) {
+  const { styles } = myComponentStyles.useVariants({
+    size,
+    variant,
+    disabled: !!disabled,
+  });
+
+  return (
+    <Pressable style={styles.root} disabled={disabled} {...props}>
+      <Text style={styles.text}>{children}</Text>
+    </Pressable>
+  );
+}
+```
+
+### 2. Export from Index
+
+```typescript
+// src/index.ts
+export { MyComponent, type MyComponentProps } from './components/MyComponent';
+```
+
+### 3. Ensure Component Styles Exist
+
+The component styles are generated from `@yahoo/uds/tokens` component configs. If the component doesn't exist in UDS tokens:
+
+1. Add the component config to `@yahoo/uds`
+2. Run `bun run generate` to regenerate styles
+3. The component stylesheet will be auto-generated
+
+### 4. Update Types (if needed)
+
+Add prop types to `src/types.ts` if exposing new semantic types.
+
+## Debugging
+
+### Generated Styles Issues
+
+1. Check `scripts/utils/themeConfig.ts` for type → theme path mappings
+2. Run `bun run generate` with verbose logging
+3. Check the console output for skipped props/values
+
+### Component Styles Not Applying
+
+1. Verify the component config exists in `@yahoo/uds/tokens`
+2. Check `generated/styles.ts` for the component stylesheet
+3. Ensure you're calling `useVariants()` with correct prop names
+
+### Theme Mismatch
+
+1. Regenerate the consumer app's theme: `uds-mobile sync`
+2. Clear Metro cache: `expo start --clear`
+3. Verify `uds.config.ts` matches the expected format
+
+### Font Issues
+
+1. Check `fonts/index.cjs` for the font mapping
+2. Verify PostScript names match what React Native expects
+3. Ensure fonts are properly linked in `app.config.ts`
+
+## Questions?
+
+- Check the [README.md](./README.md) for usage documentation
+- Review `docs/` for architecture decisions
+- Open an issue for bugs or feature requests