@mgcrea/react-native-tailwind 0.5.0 → 0.5.2

package/README.md

@@ -5,6 +5,7 @@
 [![npm version](https://img.shields.io/npm/v/@mgcrea/react-native-tailwind.svg?style=for-the-badge)](https://www.npmjs.com/package/@mgcrea/react-native-tailwind)
 [![npm downloads](https://img.shields.io/npm/dt/@mgcrea/react-native-tailwind.svg?style=for-the-badge)](https://www.npmjs.com/package/@mgcrea/react-native-tailwind)
 [![license](https://img.shields.io/github/license/mgcrea/react-native-tailwind.svg?style=for-the-badge)](https://github.com/mgcrea/react-native-tailwind/blob/main/LICENSE)
+[![build status](https://img.shields.io/github/actions/workflow/status/mgcrea/react-native-tailwind/main.yaml?style=for-the-badge&branch=master)](https://github.com/mgcrea/react-native-tailwind/actions/workflows/main.yaml)
 
 </div>
 
@@ -121,292 +122,6 @@ const _twStyles = StyleSheet.create({
 });
 ```
 
-## API Reference
-
-### Spacing
-
-**Margin & Padding:**
-
-- `m-{size}`, `p-{size}` — All sides
-- `mx-{size}`, `my-{size}`, `px-{size}`, `py-{size}` — Horizontal/vertical
-- `mt-{size}`, `mr-{size}`, `mb-{size}`, `ml-{size}` — Directional margin
-- `pt-{size}`, `pr-{size}`, `pb-{size}`, `pl-{size}` — Directional padding
-- `gap-{size}` — Gap between flex items
-
-**Available sizes:** `0`, `0.5`, `1`, `1.5`, `2`, `2.5`, `3`, `3.5`, `4`, `5`, `6`, `7`, `8`, `9`, `10`, `11`, `12`, `14`, `16`, `20`, `24`, `28`, `32`, `36`, `40`, `44`, `48`, `52`, `56`, `60`, `64`, `72`, `80`, `96`
-
-**Arbitrary values:** `m-[16px]`, `p-[20]`, `mx-[24px]`, `gap-[12px]` — Custom spacing values (px only)
-
-### Layout
-
-**Flexbox:**
-
-- `flex`, `flex-1`, `flex-auto`, `flex-none` — Flex sizing
-- `flex-row`, `flex-row-reverse`, `flex-col`, `flex-col-reverse` — Direction
-- `flex-wrap`, `flex-wrap-reverse`, `flex-nowrap` — Wrapping
-- `items-start`, `items-end`, `items-center`, `items-baseline`, `items-stretch` — Align items
-- `justify-start`, `justify-end`, `justify-center`, `justify-between`, `justify-around`, `justify-evenly` — Justify content
-- `self-auto`, `self-start`, `self-end`, `self-center`, `self-stretch`, `self-baseline` — Align self
-- `grow`, `grow-0`, `shrink`, `shrink-0` — Flex grow/shrink
-
-**Other:**
-
-- `absolute`, `relative` — Position
-- `overflow-hidden`, `overflow-visible`, `overflow-scroll` — Overflow
-- `flex`, `hidden` — Display
-
-### Colors
-
-- `bg-{color}-{shade}` — Background color
-- `text-{color}-{shade}` — Text color
-- `border-{color}-{shade}` — Border color
-
-**Available colors:** `gray`, `red`, `blue`, `green`, `yellow`, `purple`, `pink`, `orange`, `indigo`, `white`, `black`, `transparent`
-
-**Available shades:** `50`, `100`, `200`, `300`, `400`, `500`, `600`, `700`, `800`, `900`
-
-> **Note:** You can extend the color palette with custom colors via `tailwind.config.*` — see [Custom Colors](#custom-colors)
-
-**Opacity Modifiers:**
-
-Apply transparency to any color using the `/` operator with a percentage value (0-100):
-
-```tsx
-<View className="bg-black/50 p-4">         {/* 50% opacity black background */}
-  <Text className="text-gray-900/80">     {/* 80% opacity gray text */}
-    Semi-transparent content
-  </Text>
-  <View className="border-2 border-red-500/30" /> {/* 30% opacity red border */}
-</View>
-```
-
-- Works with all color types: `bg-*`, `text-*`, `border-*`
-- Supports preset colors: `bg-blue-500/75`, `text-red-600/50`
-- Supports arbitrary colors: `bg-[#ff0000]/40`, `text-[#3B82F6]/90`
-- Supports custom colors: `bg-primary/60`, `text-brand/80`
-- Uses React Native's 8-digit hex format: `#RRGGBBAA`
-
-**Examples:**
-
-```tsx
-// Background opacity
-<View className="bg-white/90" />          // #FFFFFFE6
-<View className="bg-blue-500/50" />       // #3B82F680
-
-// Text opacity
-<Text className="text-black/70" />        // #000000B3
-<Text className="text-gray-900/60" />     // #11182799
-
-// Border opacity
-<View className="border-2 border-purple-500/40" /> // #A855F766
-
-// Arbitrary colors with opacity
-<View className="bg-[#ff6b6b]/25" />      // #FF6B6B40
-
-// Edge cases
-<View className="bg-black/0" />           // Fully transparent
-<View className="bg-blue-500/100" />      // Fully opaque
-<View className="bg-transparent/50" />    // Remains transparent
-```
-
-### Typography
-
-**Font Size:**
-
-`text-xs`, `text-sm`, `text-base`, `text-lg`, `text-xl`, `text-2xl`, `text-3xl`, `text-4xl`, `text-5xl`, `text-6xl`, `text-7xl`, `text-8xl`, `text-9xl`
-
-**Font Weight:**
-
-`font-thin`, `font-extralight`, `font-light`, `font-normal`, `font-medium`, `font-semibold`, `font-bold`, `font-extrabold`, `font-black`
-
-**Other:**
-
-- `italic`, `not-italic` — Font style
-- `text-left`, `text-center`, `text-right`, `text-justify` — Text alignment
-- `underline`, `line-through`, `no-underline` — Text decoration
-- `uppercase`, `lowercase`, `capitalize`, `normal-case` — Text transform
-- `leading-none`, `leading-tight`, `leading-snug`, `leading-normal`, `leading-relaxed`, `leading-loose` — Line height
-
-### Borders
-
-**Width:**
-
-- `border`, `border-0`, `border-2`, `border-4`, `border-8` — All sides
-- `border-t`, `border-r`, `border-b`, `border-l` (with variants `-0`, `-2`, `-4`, `-8`) — Directional
-- `border-[8px]`, `border-t-[12px]` — Arbitrary values
-
-**Radius:**
-
-- `rounded-none`, `rounded-sm`, `rounded`, `rounded-md`, `rounded-lg`, `rounded-xl`, `rounded-2xl`, `rounded-3xl`, `rounded-full` — All corners
-- `rounded-t`, `rounded-r`, `rounded-b`, `rounded-l` (with size variants) — Directional
-- `rounded-tl`, `rounded-tr`, `rounded-bl`, `rounded-br` (with size variants) — Individual corners
-- `rounded-[12px]`, `rounded-t-[8px]`, `rounded-tl-[16px]` — Arbitrary values
-
-**Style:**
-
-`border-solid`, `border-dotted`, `border-dashed`
-
-### Shadows & Elevation
-
-Apply platform-specific shadows and elevation to create depth and visual hierarchy. Automatically uses iOS shadow properties or Android elevation based on the platform:
-
-**Available shadow sizes:**
-
-- `shadow-sm` — Subtle shadow
-- `shadow` — Default shadow
-- `shadow-md` — Medium shadow
-- `shadow-lg` — Large shadow
-- `shadow-xl` — Extra large shadow
-- `shadow-2xl` — Extra extra large shadow
-- `shadow-none` — Remove shadow
-
-**Platform Differences:**
-
-| Platform | Properties Used | Example Output |
-|----------|----------------|----------------|
-| **iOS** | `shadowColor`, `shadowOffset`, `shadowOpacity`, `shadowRadius` | Native iOS shadow rendering |
-| **Android** | `elevation` | Native Android elevation (Material Design) |
-
-**Examples:**
-
-```tsx
-// Card with shadow
-<View className="bg-white rounded-lg shadow-lg p-6 m-4">
-  <Text className="text-xl font-bold">Card Title</Text>
-  <Text className="text-gray-600">Card with large shadow</Text>
-</View>
-
-// Button with subtle shadow
-<Pressable className="bg-blue-500 shadow-sm rounded-lg px-6 py-3">
-  <Text className="text-white">Press Me</Text>
-</Pressable>
-
-// Different shadow sizes
-<View className="shadow-sm p-4">Subtle</View>
-<View className="shadow p-4">Default</View>
-<View className="shadow-md p-4">Medium</View>
-<View className="shadow-lg p-4">Large</View>
-<View className="shadow-xl p-4">Extra Large</View>
-<View className="shadow-2xl p-4">2X Large</View>
-
-// Remove shadow
-<View className="shadow-lg md:shadow-none p-4">
-  Conditional shadow removal
-</View>
-```
-
-**iOS Shadow Values:**
-
-| Class | shadowOpacity | shadowRadius | shadowOffset |
-|-------|---------------|--------------|--------------|
-| `shadow-sm` | 0.05 | 1 | { width: 0, height: 1 } |
-| `shadow` | 0.1 | 2 | { width: 0, height: 1 } |
-| `shadow-md` | 0.15 | 4 | { width: 0, height: 3 } |
-| `shadow-lg` | 0.2 | 8 | { width: 0, height: 6 } |
-| `shadow-xl` | 0.25 | 12 | { width: 0, height: 10 } |
-| `shadow-2xl` | 0.3 | 24 | { width: 0, height: 20 } |
-
-**Android Elevation Values:**
-
-| Class | elevation |
-|-------|-----------|
-| `shadow-sm` | 1 |
-| `shadow` | 2 |
-| `shadow-md` | 4 |
-| `shadow-lg` | 8 |
-| `shadow-xl` | 12 |
-| `shadow-2xl` | 16 |
-
-> **Note:** All shadow parsing happens at compile-time with zero runtime overhead. The platform detection uses React Native's `Platform.select()` API.
-
-### Aspect Ratio
-
-Control the aspect ratio of views using preset or arbitrary values. Requires React Native 0.71+:
-
-**Preset values:**
-
-- `aspect-auto` — Remove aspect ratio constraint
-- `aspect-square` — 1:1 aspect ratio
-- `aspect-video` — 16:9 aspect ratio
-
-**Arbitrary values:**
-
-Use `aspect-[width/height]` for custom ratios:
-
-```tsx
-<View className="aspect-[4/3]" />    // 4:3 ratio (1.333...)
-<View className="aspect-[16/9]" />   // 16:9 ratio (1.778...)
-<View className="aspect-[21/9]" />   // 21:9 ultrawide
-<View className="aspect-[9/16]" />   // 9:16 portrait
-<View className="aspect-[3/2]" />    // 3:2 ratio (1.5)
-```
-
-**Examples:**
-
-```tsx
-// Square image container
-<View className="w-full aspect-square bg-gray-200">
-  <Image source={avatar} className="w-full h-full" />
-</View>
-
-// Video player container (16:9)
-<View className="w-full aspect-video bg-black">
-  <VideoPlayer />
-</View>
-
-// Instagram-style square grid
-<View className="flex-row flex-wrap gap-2">
-  {photos.map((photo) => (
-    <View key={photo.id} className="w-[32%] aspect-square">
-      <Image source={photo.uri} className="w-full h-full rounded" />
-    </View>
-  ))}
-</View>
-
-// Custom aspect ratio for wide images
-<View className="w-full aspect-[21/9] rounded-lg overflow-hidden">
-  <Image source={banner} className="w-full h-full" resizeMode="cover" />
-</View>
-
-// Portrait orientation
-<View className="h-full aspect-[9/16]">
-  <Story />
-</View>
-
-// Remove aspect ratio constraint
-<View className="aspect-square md:aspect-auto">
-  Responsive aspect ratio
-</View>
-```
-
-**Common Aspect Ratios:**
-
-| Ratio | Class | Decimal | Use Case |
-|-------|-------|---------|----------|
-| 1:1 | `aspect-square` | 1.0 | Profile pictures, thumbnails |
-| 16:9 | `aspect-video` | 1.778 | Videos, landscape photos |
-| 4:3 | `aspect-[4/3]` | 1.333 | Standard photos |
-| 3:2 | `aspect-[3/2]` | 1.5 | Classic photography |
-| 21:9 | `aspect-[21/9]` | 2.333 | Ultrawide/cinematic |
-| 9:16 | `aspect-[9/16]` | 0.5625 | Stories, vertical video |
-
-> **Note:** The aspect ratio is calculated as `width / height`. When combined with `w-full`, the height will be automatically calculated to maintain the ratio.
-
-### Sizing
-
-- `w-{size}`, `h-{size}` — Width/height
-- `min-w-{size}`, `min-h-{size}` — Min width/height
-- `max-w-{size}`, `max-h-{size}` — Max width/height
-
-**Available sizes:**
-
-- **Numeric:** `0`-`96` (same as spacing scale)
-- **Fractional:** `1/2`, `1/3`, `2/3`, `1/4`, `3/4`, `1/5`, `2/5`, `3/5`, `4/5`, `1/6`, `2/6`, `3/6`, `4/6`, `5/6`
-- **Special:** `full` (100%), `auto`
-- **Arbitrary:** `w-[123px]`, `h-[50%]`, `min-w-[200px]`, `max-h-[80%]`
-
-> **Note:** Arbitrary sizing supports pixel values (`[123px]` or `[123]`) and percentages (`[50%]`). Other units (`rem`, `em`, `vh`, `vw`) are not supported in React Native.
-
 ## Usage Examples
 
 ### Basic Example
@@ -662,10 +377,10 @@ The package exports an enhanced `TextInput` component that:
 
 **Supported Modifiers by Component:**
 
-| Component              | Supported Modifiers                          | Notes                                      |
-| ---------------------- | -------------------------------------------- | ------------------------------------------ |
-| `Pressable` (enhanced) | `active:`, `hover:`, `focus:`, `disabled:`   | Use `@mgcrea/react-native-tailwind` export |
-| `TextInput` (enhanced) | `focus:`, `disabled:`                        | Use `@mgcrea/react-native-tailwind` export |
+| Component              | Supported Modifiers                        | Notes                                      |
+| ---------------------- | ------------------------------------------ | ------------------------------------------ |
+| `Pressable` (enhanced) | `active:`, `hover:`, `focus:`, `disabled:` | Use `@mgcrea/react-native-tailwind` export |
+| `TextInput` (enhanced) | `focus:`, `disabled:`                      | Use `@mgcrea/react-native-tailwind` export |
 
 #### Disabled Modifier (Pressable & TextInput)
 
@@ -682,9 +397,7 @@ export function SubmitButton({ isLoading }) {
       disabled={isLoading}
       className="bg-blue-500 active:bg-blue-700 disabled:bg-gray-400 p-4 rounded-lg"
     >
-      <Text className="text-white font-semibold">
-        {isLoading ? "Loading..." : "Submit"}
-      </Text>
+      <Text className="text-white font-semibold">{isLoading ? "Loading..." : "Submit"}</Text>
     </Pressable>
   );
 }
@@ -870,47 +583,295 @@ export function Button({ title, onPress, style, containerStyle }: ButtonProps) {
 
 This pattern allows you to build component libraries with optimized default styling while still supporting full customization.
 
-## Architecture
+## API Reference
+
+### Spacing
 
-### Compile-Time Transformation
+**Margin & Padding:**
 
-The Babel plugin performs all transformations during build time, ensuring zero runtime overhead:
+- `m-{size}`, `p-{size}` — All sides
+- `mx-{size}`, `my-{size}`, `px-{size}`, `py-{size}` — Horizontal/vertical
+- `mt-{size}`, `mr-{size}`, `mb-{size}`, `ml-{size}` — Directional margin
+- `pt-{size}`, `pr-{size}`, `pb-{size}`, `pl-{size}` — Directional padding
+- `gap-{size}` — Gap between flex items
 
-1. **AST Transformation** — Visits JSX elements and finds `className` attributes
-2. **Static Analysis** — Only processes string literals (dynamic values produce warnings)
-3. **Style Registry** — Collects all className → style mappings per file
-4. **Code Generation** — Injects `StyleSheet.create()` at end of file
-5. **Import Management** — Adds `StyleSheet` import if needed
+**Available sizes:** `0`, `0.5`, `1`, `1.5`, `2`, `2.5`, `3`, `3.5`, `4`, `5`, `6`, `7`, `8`, `9`, `10`, `11`, `12`, `14`, `16`, `20`, `24`, `28`, `32`, `36`, `40`, `44`, `48`, `52`, `56`, `60`, `64`, `72`, `80`, `96`
 
-### Performance Characteristics
+**Arbitrary values:** `m-[16px]`, `p-[20]`, `mx-[24px]`, `gap-[12px]` — Custom spacing values (px only)
 
-| Metric           | Value              |
-| ---------------- | ------------------ |
-| Runtime Overhead | 0ms (compile-time) |
-| Bundle Size      | ~4KB typical       |
-| Build Time       | +50-200ms          |
+### Layout
 
-**Why it's fast:**
+**Flexbox:**
 
-- ⚡ All className parsing happens at build time
-- 🎯 Uses React Native's optimized `StyleSheet.create` API
-- 📦 Tree shaking — only includes styles actually used
-- 🔄 Deduplication — identical styles reused across components
+- `flex`, `flex-1`, `flex-auto`, `flex-none` — Flex sizing
+- `flex-row`, `flex-row-reverse`, `flex-col`, `flex-col-reverse` — Direction
+- `flex-wrap`, `flex-wrap-reverse`, `flex-nowrap` — Wrapping
+- `items-start`, `items-end`, `items-center`, `items-baseline`, `items-stretch` — Align items
+- `justify-start`, `justify-end`, `justify-center`, `justify-between`, `justify-around`, `justify-evenly` — Justify content
+- `self-auto`, `self-start`, `self-end`, `self-center`, `self-stretch`, `self-baseline` — Align self
+- `grow`, `grow-0`, `shrink`, `shrink-0` — Flex grow/shrink
 
-## Limitations
+**Other:**
 
-**Dynamic class names are not supported** — The Babel plugin can only transform static string literals:
+- `absolute`, `relative` — Position
+- `overflow-hidden`, `overflow-visible`, `overflow-scroll` — Overflow
+- `flex`, `hidden` — Display
+
+### Colors
+
+- `bg-{color}-{shade}` — Background color
+- `text-{color}-{shade}` — Text color
+- `border-{color}-{shade}` — Border color
+
+**Available colors:** `gray`, `red`, `blue`, `green`, `yellow`, `purple`, `pink`, `orange`, `indigo`, `white`, `black`, `transparent`
+
+**Available shades:** `50`, `100`, `200`, `300`, `400`, `500`, `600`, `700`, `800`, `900`
+
+> **Note:** You can extend the color palette with custom colors via `tailwind.config.*` — see [Custom Colors](#custom-colors)
+
+**Opacity Modifiers:**
+
+Apply transparency to any color using the `/` operator with a percentage value (0-100):
 
 ```tsx
-// ❌ This will NOT work
-const spacing = 4;
-<View className={`m-${spacing} p-2`} />
+<View className="bg-black/50 p-4">
+  {" "}
+  {/* 50% opacity black background */}
+  <Text className="text-gray-900/80">
+    {" "}
+    {/* 80% opacity gray text */}
+    Semi-transparent content
+  </Text>
+  <View className="border-2 border-red-500/30" /> {/* 30% opacity red border */}
+</View>
+```
 
-// ✅ Use inline styles for dynamic values
-<View className="p-2" style={{ margin: spacing * 4 }} />
+- Works with all color types: `bg-*`, `text-*`, `border-*`
+- Supports preset colors: `bg-blue-500/75`, `text-red-600/50`
+- Supports arbitrary colors: `bg-[#ff0000]/40`, `text-[#3B82F6]/90`
+- Supports custom colors: `bg-primary/60`, `text-brand/80`
+- Uses React Native's 8-digit hex format: `#RRGGBBAA`
+
+**Examples:**
+
+```tsx
+// Background opacity
+<View className="bg-white/90" />          // #FFFFFFE6
+<View className="bg-blue-500/50" />       // #3B82F680
+
+// Text opacity
+<Text className="text-black/70" />        // #000000B3
+<Text className="text-gray-900/60" />     // #11182799
+
+// Border opacity
+<View className="border-2 border-purple-500/40" /> // #A855F766
+
+// Arbitrary colors with opacity
+<View className="bg-[#ff6b6b]/25" />      // #FF6B6B40
+
+// Edge cases
+<View className="bg-black/0" />           // Fully transparent
+<View className="bg-blue-500/100" />      // Fully opaque
+<View className="bg-transparent/50" />    // Remains transparent
 ```
 
-For dynamic styling, use the `style` prop alongside `className`.
+### Typography
+
+**Font Size:**
+
+`text-xs`, `text-sm`, `text-base`, `text-lg`, `text-xl`, `text-2xl`, `text-3xl`, `text-4xl`, `text-5xl`, `text-6xl`, `text-7xl`, `text-8xl`, `text-9xl`
+
+**Font Weight:**
+
+`font-thin`, `font-extralight`, `font-light`, `font-normal`, `font-medium`, `font-semibold`, `font-bold`, `font-extrabold`, `font-black`
+
+**Other:**
+
+- `italic`, `not-italic` — Font style
+- `text-left`, `text-center`, `text-right`, `text-justify` — Text alignment
+- `underline`, `line-through`, `no-underline` — Text decoration
+- `uppercase`, `lowercase`, `capitalize`, `normal-case` — Text transform
+- `leading-none`, `leading-tight`, `leading-snug`, `leading-normal`, `leading-relaxed`, `leading-loose` — Line height
+
+### Borders
+
+**Width:**
+
+- `border`, `border-0`, `border-2`, `border-4`, `border-8` — All sides
+- `border-t`, `border-r`, `border-b`, `border-l` (with variants `-0`, `-2`, `-4`, `-8`) — Directional
+- `border-[8px]`, `border-t-[12px]` — Arbitrary values
+
+**Radius:**
+
+- `rounded-none`, `rounded-sm`, `rounded`, `rounded-md`, `rounded-lg`, `rounded-xl`, `rounded-2xl`, `rounded-3xl`, `rounded-full` — All corners
+- `rounded-t`, `rounded-r`, `rounded-b`, `rounded-l` (with size variants) — Directional
+- `rounded-tl`, `rounded-tr`, `rounded-bl`, `rounded-br` (with size variants) — Individual corners
+- `rounded-[12px]`, `rounded-t-[8px]`, `rounded-tl-[16px]` — Arbitrary values
+
+**Style:**
+
+`border-solid`, `border-dotted`, `border-dashed`
+
+### Shadows & Elevation
+
+Apply platform-specific shadows and elevation to create depth and visual hierarchy. Automatically uses iOS shadow properties or Android elevation based on the platform:
+
+**Available shadow sizes:**
+
+- `shadow-sm` — Subtle shadow
+- `shadow` — Default shadow
+- `shadow-md` — Medium shadow
+- `shadow-lg` — Large shadow
+- `shadow-xl` — Extra large shadow
+- `shadow-2xl` — Extra extra large shadow
+- `shadow-none` — Remove shadow
+
+**Platform Differences:**
+
+| Platform    | Properties Used                                                | Example Output                             |
+| ----------- | -------------------------------------------------------------- | ------------------------------------------ |
+| **iOS**     | `shadowColor`, `shadowOffset`, `shadowOpacity`, `shadowRadius` | Native iOS shadow rendering                |
+| **Android** | `elevation`                                                    | Native Android elevation (Material Design) |
+
+**Examples:**
+
+```tsx
+// Card with shadow
+<View className="bg-white rounded-lg shadow-lg p-6 m-4">
+  <Text className="text-xl font-bold">Card Title</Text>
+  <Text className="text-gray-600">Card with large shadow</Text>
+</View>
+
+// Button with subtle shadow
+<Pressable className="bg-blue-500 shadow-sm rounded-lg px-6 py-3">
+  <Text className="text-white">Press Me</Text>
+</Pressable>
+
+// Different shadow sizes
+<View className="shadow-sm p-4">Subtle</View>
+<View className="shadow p-4">Default</View>
+<View className="shadow-md p-4">Medium</View>
+<View className="shadow-lg p-4">Large</View>
+<View className="shadow-xl p-4">Extra Large</View>
+<View className="shadow-2xl p-4">2X Large</View>
+
+// Remove shadow
+<View className="shadow-lg md:shadow-none p-4">
+  Conditional shadow removal
+</View>
+```
+
+**iOS Shadow Values:**
+
+| Class        | shadowOpacity | shadowRadius | shadowOffset             |
+| ------------ | ------------- | ------------ | ------------------------ |
+| `shadow-sm`  | 0.05          | 1            | { width: 0, height: 1 }  |
+| `shadow`     | 0.1           | 2            | { width: 0, height: 1 }  |
+| `shadow-md`  | 0.15          | 4            | { width: 0, height: 3 }  |
+| `shadow-lg`  | 0.2           | 8            | { width: 0, height: 6 }  |
+| `shadow-xl`  | 0.25          | 12           | { width: 0, height: 10 } |
+| `shadow-2xl` | 0.3           | 24           | { width: 0, height: 20 } |
+
+**Android Elevation Values:**
+
+| Class        | elevation |
+| ------------ | --------- |
+| `shadow-sm`  | 1         |
+| `shadow`     | 2         |
+| `shadow-md`  | 4         |
+| `shadow-lg`  | 8         |
+| `shadow-xl`  | 12        |
+| `shadow-2xl` | 16        |
+
+> **Note:** All shadow parsing happens at compile-time with zero runtime overhead. The platform detection uses React Native's `Platform.select()` API.
+
+### Aspect Ratio
+
+Control the aspect ratio of views using preset or arbitrary values. Requires React Native 0.71+:
+
+**Preset values:**
+
+- `aspect-auto` — Remove aspect ratio constraint
+- `aspect-square` — 1:1 aspect ratio
+- `aspect-video` — 16:9 aspect ratio
+
+**Arbitrary values:**
+
+Use `aspect-[width/height]` for custom ratios:
+
+```tsx
+<View className="aspect-[4/3]" />    // 4:3 ratio (1.333...)
+<View className="aspect-[16/9]" />   // 16:9 ratio (1.778...)
+<View className="aspect-[21/9]" />   // 21:9 ultrawide
+<View className="aspect-[9/16]" />   // 9:16 portrait
+<View className="aspect-[3/2]" />    // 3:2 ratio (1.5)
+```
+
+**Examples:**
+
+```tsx
+// Square image container
+<View className="w-full aspect-square bg-gray-200">
+  <Image source={avatar} className="w-full h-full" />
+</View>
+
+// Video player container (16:9)
+<View className="w-full aspect-video bg-black">
+  <VideoPlayer />
+</View>
+
+// Instagram-style square grid
+<View className="flex-row flex-wrap gap-2">
+  {photos.map((photo) => (
+    <View key={photo.id} className="w-[32%] aspect-square">
+      <Image source={photo.uri} className="w-full h-full rounded" />
+    </View>
+  ))}
+</View>
+
+// Custom aspect ratio for wide images
+<View className="w-full aspect-[21/9] rounded-lg overflow-hidden">
+  <Image source={banner} className="w-full h-full" resizeMode="cover" />
+</View>
+
+// Portrait orientation
+<View className="h-full aspect-[9/16]">
+  <Story />
+</View>
+
+// Remove aspect ratio constraint
+<View className="aspect-square md:aspect-auto">
+  Responsive aspect ratio
+</View>
+```
+
+**Common Aspect Ratios:**
+
+| Ratio | Class           | Decimal | Use Case                     |
+| ----- | --------------- | ------- | ---------------------------- |
+| 1:1   | `aspect-square` | 1.0     | Profile pictures, thumbnails |
+| 16:9  | `aspect-video`  | 1.778   | Videos, landscape photos     |
+| 4:3   | `aspect-[4/3]`  | 1.333   | Standard photos              |
+| 3:2   | `aspect-[3/2]`  | 1.5     | Classic photography          |
+| 21:9  | `aspect-[21/9]` | 2.333   | Ultrawide/cinematic          |
+| 9:16  | `aspect-[9/16]` | 0.5625  | Stories, vertical video      |
+
+> **Note:** The aspect ratio is calculated as `width / height`. When combined with `w-full`, the height will be automatically calculated to maintain the ratio.
+
+### Sizing
+
+- `w-{size}`, `h-{size}` — Width/height
+- `min-w-{size}`, `min-h-{size}` — Min width/height
+- `max-w-{size}`, `max-h-{size}` — Max width/height
+
+**Available sizes:**
+
+- **Numeric:** `0`-`96` (same as spacing scale)
+- **Fractional:** `1/2`, `1/3`, `2/3`, `1/4`, `3/4`, `1/5`, `2/5`, `3/5`, `4/5`, `1/6`, `2/6`, `3/6`, `4/6`, `5/6`
+- **Special:** `full` (100%), `auto`
+- **Arbitrary:** `w-[123px]`, `h-[50%]`, `min-w-[200px]`, `max-h-[80%]`
+
+> **Note:** Arbitrary sizing supports pixel values (`[123px]` or `[123]`) and percentages (`[50%]`). Other units (`rem`, `em`, `vh`, `vw`) are not supported in React Native.
 
 ## Advanced