@mgcrea/react-native-tailwind 0.3.0 → 0.5.0

package/README.md

@@ -15,14 +15,15 @@ Compile-time Tailwind CSS for React Native with zero runtime overhead. Transform
 ## Features
 
 - ⚡ **Zero runtime overhead** — All transformations happen at compile time
-- 🎯 **Babel-only setup** — No Metro configuration required (like Reanimated)
+- 🔧 **No dependencies** — Direct-to-React-Native style generation without tailwindcss package
+- 🎯 **Babel-only setup** — No Metro configuration required
 - 📝 **TypeScript-first** — Full type safety and autocomplete support
-- 🚀 **Optimized performance** — Uses `StyleSheet.create` for optimal React Native performance
+- 🚀 **Optimized performance** — Compiles down to `StyleSheet.create` for optimal performance
 - 📦 **Small bundle size** — Only includes actual styles used in your app
-- 🔧 **No dependencies** — Direct-to-React-Native style generation without tailwindcss package
 - 🎨 **Custom colors** — Extend the default palette via `tailwind.config.*`
 - 📐 **Arbitrary values** — Use custom sizes and borders: `w-[123px]`, `rounded-[20px]`
 - 🔀 **Dynamic className** — Conditional styles with hybrid compile-time optimization
+- 🎯 **State modifiers** — `active:`, `hover:`, `focus:`, and `disabled:` modifiers for interactive components
 - 📜 **Special style props** — Support for `contentContainerClassName`, `columnWrapperClassName`, and more
 
 ## Installation
@@ -95,11 +96,11 @@ The Babel plugin transforms your code at compile time:
 ```tsx
 import { StyleSheet } from "react-native";
 
-<View style={styles._bg_blue_500_m_4_p_2_rounded_lg} />;
-<ScrollView contentContainerStyle={styles._gap_4_items_center} />;
-<FlatList columnWrapperStyle={styles._gap_4} ListHeaderComponentStyle={styles._bg_gray_100_p_4} />;
+<View style={_twStyles._bg_blue_500_m_4_p_2_rounded_lg} />;
+<ScrollView contentContainerStyle={_twStyles._gap_4_items_center} />;
+<FlatList columnWrapperStyle={_twStyles._gap_4} ListHeaderComponentStyle={_twStyles._bg_gray_100_p_4} />;
 
-const styles = StyleSheet.create({
+const _twStyles = StyleSheet.create({
   _bg_blue_500_m_4_p_2_rounded_lg: {
     margin: 16,
     padding: 8,
@@ -134,6 +135,8 @@ const styles = StyleSheet.create({
 
 **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:**
@@ -164,6 +167,48 @@ const styles = StyleSheet.create({
 
 > **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:**
@@ -201,6 +246,152 @@ const styles = StyleSheet.create({
 
 `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
@@ -235,14 +426,18 @@ export function MyComponent() {
 ### Card Component
 
 ```tsx
-import { View, Text, Pressable } from "react-native";
+import { View, Text } from "react-native";
+import { Pressable } from "@mgcrea/react-native-tailwind";
 
 export function Card({ title, description, onPress }) {
   return (
     <View className="bg-white rounded-lg p-6 mb-4 border border-gray-200">
       <Text className="text-xl font-semibold text-gray-900 mb-2">{title}</Text>
       <Text className="text-base text-gray-600 mb-4">{description}</Text>
-      <Pressable className="bg-blue-500 px-4 py-2 rounded-lg items-center" onPress={onPress}>
+      <Pressable
+        className="bg-blue-500 active:bg-blue-700 px-4 py-2 rounded-lg items-center"
+        onPress={onPress}
+      >
         <Text className="text-white font-semibold">Learn More</Text>
       </Pressable>
     </View>
@@ -279,18 +474,16 @@ export function ToggleButton() {
 ```tsx
 <Pressable
   onPress={() => setIsActive(!isActive)}
-  style={isActive ? styles._bg_green_500_p_4 : styles._bg_red_500_p_4}
+  style={isActive ? _twStyles._bg_green_500_p_4 : _twStyles._bg_red_500_p_4}
 >
-  <Text style={styles._text_white}>{isActive ? "Active" : "Inactive"}</Text>
+  <Text style={_twStyles._text_white}>{isActive ? "Active" : "Inactive"}</Text>
 </Pressable>
 ```
 
 **Template Literal (Static + Dynamic):**
 
 ```tsx
-<Pressable
-  className={`border-2 rounded-lg ${isActive ? "bg-blue-500" : "bg-gray-300"} p-4`}
->
+<Pressable className={`border-2 rounded-lg ${isActive ? "bg-blue-500" : "bg-gray-300"} p-4`}>
   <Text className="text-white">Click Me</Text>
 </Pressable>
 ```
@@ -300,13 +493,13 @@ export function ToggleButton() {
 ```tsx
 <Pressable
   style={[
-    styles._border_2,
-    styles._rounded_lg,
-    isActive ? styles._bg_blue_500 : styles._bg_gray_300,
-    styles._p_4
+    _twStyles._border_2,
+    _twStyles._rounded_lg,
+    isActive ? _twStyles._bg_blue_500 : _twStyles._bg_gray_300,
+    _twStyles._p_4,
   ]}
 >
-  <Text style={styles._text_white}>Click Me</Text>
+  <Text style={_twStyles._text_white}>Click Me</Text>
 </Pressable>
 ```
 
@@ -321,13 +514,7 @@ export function ToggleButton() {
 **Transforms to:**
 
 ```tsx
-<View
-  style={[
-    styles._p_4,
-    styles._bg_gray_100,
-    isActive && styles._border_4_border_purple_500
-  ]}
->
+<View style={[_twStyles._p_4, _twStyles._bg_gray_100, isActive && _twStyles._border_4_border_purple_500]}>
   <Text>Content</Text>
 </View>
 ```
@@ -335,9 +522,7 @@ export function ToggleButton() {
 **Multiple Conditionals:**
 
 ```tsx
-<View
-  className={`${size === "lg" ? "p-8" : "p-4"} ${isActive ? "bg-blue-500" : "bg-gray-400"}`}
->
+<View className={`${size === "lg" ? "p-8" : "p-4"} ${isActive ? "bg-blue-500" : "bg-gray-400"}`}>
   <Text>Dynamic Size & Color</Text>
 </View>
 ```
@@ -373,11 +558,184 @@ You can use inline `style` prop alongside `className`:
 The Babel plugin will merge them:
 
 ```tsx
-<View style={[styles._className_styles, { paddingTop: safeAreaInsets.top }]}>
+<View style={[_twStyles._className_styles, { paddingTop: safeAreaInsets.top }]}>
   <Text>Content</Text>
 </View>
 ```
 
+### State Modifiers
+
+Apply styles based on component state with zero runtime overhead. The Babel plugin automatically generates optimized style functions.
+
+#### Active Modifier (Pressable)
+
+Use the `active:` modifier to apply styles when a `Pressable` component is pressed. **Requires using the enhanced `Pressable` component from this package.**
+
+**Basic Example:**
+
+```tsx
+import { Text } from "react-native";
+import { Pressable } from "@mgcrea/react-native-tailwind";
+
+export function MyButton() {
+  return (
+    <Pressable className="bg-blue-500 active:bg-blue-700 p-4 rounded-lg">
+      <Text className="text-white font-semibold">Press Me</Text>
+    </Pressable>
+  );
+}
+```
+
+**Transforms to:**
+
+```tsx
+<Pressable
+  style={({ pressed }) => [_twStyles._bg_blue_500_p_4_rounded_lg, pressed && _twStyles._active_bg_blue_700]}
+>
+  <Text style={_twStyles._font_semibold_text_white}>Press Me</Text>
+</Pressable>;
+
+// Generated styles:
+const _twStyles = StyleSheet.create({
+  _bg_blue_500_p_4_rounded_lg: { backgroundColor: "#3B82F6", padding: 16, borderRadius: 8 },
+  _active_bg_blue_700: { backgroundColor: "#1D4ED8" },
+  _font_semibold_text_white: { fontWeight: "600", color: "#FFFFFF" },
+});
+```
+
+**Multiple Active Modifiers:**
+
+```tsx
+<Pressable className="bg-green-500 active:bg-green-700 p-4 active:p-6 rounded-lg">
+  <Text className="text-white">Press for darker & larger padding</Text>
+</Pressable>
+```
+
+**Complex Styling:**
+
+```tsx
+<Pressable className="bg-purple-500 active:bg-purple-800 border-2 border-purple-700 active:border-purple-900 p-4 rounded-lg">
+  <Text className="text-white">Background + Border Changes</Text>
+</Pressable>
+```
+
+**Key Features:**
+
+- ✅ **Zero runtime overhead** — All parsing happens at compile-time
+- ✅ **Native Pressable API** — Uses Pressable's `style={({ pressed }) => ...}` pattern
+- ✅ **Type-safe** — Full TypeScript autocomplete for `active:` classes
+- ✅ **Optimized** — Styles deduplicated via `StyleSheet.create`
+- ✅ **Works with custom colors** — `active:bg-primary`, `active:bg-secondary`, etc.
+
+#### Focus Modifier (TextInput)
+
+Use the `focus:` modifier to apply styles when a `TextInput` component is focused. **Requires using the enhanced `TextInput` component from this package.**
+
+**Basic Example:**
+
+```tsx
+import { TextInput } from "@mgcrea/react-native-tailwind";
+
+export function MyInput() {
+  return (
+    <TextInput
+      className="border-2 border-gray-300 focus:border-blue-500 p-3 rounded-lg bg-white"
+      placeholder="Email address"
+    />
+  );
+}
+```
+
+**How it works:**
+
+The package exports an enhanced `TextInput` component that:
+
+1. Manages focus state internally using `onFocus`/`onBlur` callbacks
+2. Passes focus state to the style function: `style={({ focused }) => ...}`
+3. Works seamlessly with the `focus:` modifier in className
+
+**Multiple Focus Modifiers:**
+
+```tsx
+<TextInput className="border-2 border-gray-300 focus:border-green-500 bg-gray-50 focus:bg-white p-3 rounded-lg" />
+```
+
+**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 |
+
+#### Disabled Modifier (Pressable & TextInput)
+
+Use the `disabled:` modifier to apply styles when a component is disabled. **Requires using the enhanced components from this package.**
+
+**Pressable Example:**
+
+```tsx
+import { Pressable, Text } from "@mgcrea/react-native-tailwind";
+
+export function SubmitButton({ isLoading }) {
+  return (
+    <Pressable
+      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>
+    </Pressable>
+  );
+}
+```
+
+**TextInput Example:**
+
+```tsx
+import { TextInput } from "@mgcrea/react-native-tailwind";
+
+export function MyInput({ isEditing }) {
+  return (
+    <TextInput
+      disabled={!isEditing}
+      className="border-2 border-gray-300 focus:border-blue-500 disabled:bg-gray-100 disabled:border-gray-200 p-3 rounded-lg"
+      placeholder="Enter text"
+    />
+  );
+}
+```
+
+**How it works:**
+
+The enhanced components inject the `disabled` prop value into the style function context:
+
+- **Pressable**: Extends the existing `{ pressed, hovered, focused }` state with `disabled`
+- **TextInput**: Provides `{ focused, disabled }` state to style functions
+
+**TextInput `disabled` Prop:**
+
+The enhanced `TextInput` also provides a convenient `disabled` prop that overrides React Native's `editable` prop:
+
+```tsx
+// These are equivalent:
+<TextInput disabled={true} />
+<TextInput editable={false} />
+
+// If both are provided, disabled takes precedence:
+<TextInput disabled={true} editable={true} /> // Component is disabled
+```
+
+**Important Notes:**
+
+- ⚠️ **Enhanced components required** — State modifiers require using the enhanced components from this package
+- ℹ️ **Component-specific** — Each modifier only works on compatible components
+- ℹ️ **No nested modifiers** — Combinations like `active:focus:bg-blue-500` are not currently supported
+- ✅ **Zero styling overhead** — All className parsing happens at compile-time
+- ✅ **Minimal runtime cost** — Only adds state management (focus tracking, disabled injection)
+- ✅ **Type-safe** — Full TypeScript autocomplete for all modifiers
+- ✅ **Works with custom colors** — `focus:border-primary`, `active:bg-secondary`, `disabled:bg-gray-200`, etc.
+
 ### ScrollView Content Container
 
 Use `contentContainerClassName` to style the ScrollView's content container:
@@ -451,6 +809,67 @@ export function ListWithHeaderFooter({ items }) {
 }
 ```
 
+### Building Reusable Components
+
+When building reusable components, use static `className` strings internally. To support `className` props from parent components, you **must** accept the corresponding `style` props (the Babel plugin transforms `className` to `style` before your component receives it):
+
+```tsx
+import { Pressable, Text, View, StyleProp, ViewStyle } from "react-native";
+
+type ButtonProps = {
+  title: string;
+  onPress?: () => void;
+  // REQUIRED: Must accept style props for className to work
+  style?: StyleProp<ViewStyle>;
+  containerStyle?: StyleProp<ViewStyle>;
+  // Optional: Include in type for TypeScript compatibility
+  className?: string; // compile-time only
+  containerClassName?: string; // compile-time only
+};
+
+export function Button({ title, onPress, style, containerStyle }: ButtonProps) {
+  // Use static className strings - these get optimized at compile-time
+  return (
+    <View className="p-2 bg-gray-100 rounded-lg" style={containerStyle}>
+      <Pressable className="bg-blue-500 px-6 py-4 rounded-lg items-center" onPress={onPress} style={style}>
+        <Text className="text-white text-center font-semibold text-base">{title}</Text>
+      </Pressable>
+    </View>
+  );
+}
+```
+
+**Key Points:**
+
+- ✅ Use **static className strings** internally for default styling
+- ✅ **Must accept `style` props** - the Babel plugin transforms `className` → `style` before your component receives it
+- ✅ Include `className` props in the type (for TypeScript compatibility)
+- ✅ **Don't destructure** className props - they're already transformed to `style` and will be `undefined` at runtime
+- ✅ Babel plugin optimizes all static strings to `StyleSheet.create` calls
+
+**Usage:**
+
+```tsx
+// Default styling (uses internal static classNames)
+<Button title="Click Me" onPress={handlePress} />
+
+// Override with runtime styles
+<Button
+  title="Custom"
+  style={{ backgroundColor: '#10B981' }}
+  containerStyle={{ padding: 16 }}
+  onPress={handlePress}
+/>
+
+// className props are accepted but transformed by Babel upstream
+<Button className="bg-red-500 p-8" title="Red Button" />
+// At compile-time, this becomes:
+// <Button style={_twStyles._bg_red_500_p_8} title="Red Button" />
+// At runtime, className is undefined (already transformed to style)
+```
+
+This pattern allows you to build component libraries with optimized default styling while still supporting full customization.
+
 ## Architecture
 
 ### Compile-Time Transformation
@@ -497,24 +916,25 @@ For dynamic styling, use the `style` prop alongside `className`.
 
 ### Arbitrary Values
 
-Use arbitrary values for custom sizes and borders not in the preset scales:
+Use arbitrary values for custom sizes, spacing, and borders not in the preset scales:
 
 ```tsx
-<View className="w-[350px] h-[85%] border-[3px] rounded-[20px]" />
+<View className="w-[350px] h-[85%] m-[16px] p-[24px] border-[3px] rounded-[20px]" />
 ```
 
 **Supported:**
 
-- **Sizing:** `w-[...]`, `h-[...]`, `min-w-[...]`, `min-h-[...]`, `max-w-[...]`, `max-h-[...]`
-- **Border width:** `border-[...]`, `border-t-[...]`, `border-r-[...]`, `border-b-[...]`, `border-l-[...]`
-- **Border radius:** `rounded-[...]`, `rounded-t-[...]`, `rounded-tl-[...]`, etc.
+- **Spacing:** `m-[...]`, `mx-[...]`, `my-[...]`, `mt-[...]`, `p-[...]`, `px-[...]`, `gap-[...]`, etc. (px only)
+- **Sizing:** `w-[...]`, `h-[...]`, `min-w-[...]`, `min-h-[...]`, `max-w-[...]`, `max-h-[...]` (px and %)
+- **Border width:** `border-[...]`, `border-t-[...]`, `border-r-[...]`, `border-b-[...]`, `border-l-[...]` (px only)
+- **Border radius:** `rounded-[...]`, `rounded-t-[...]`, `rounded-tl-[...]`, etc. (px only)
 
 **Formats:**
 
-- Pixels: `[123px]` or `[123]`
-- Percentages: `[50%]`, `[33.333%]`
+- Pixels: `[123px]` or `[123]` — Supported by all utilities
+- Percentages: `[50%]`, `[33.333%]` — Only supported by sizing utilities (`w-*`, `h-*`, etc.)
 
-> **Note:** Only `px` and `%` units are supported. CSS units (`rem`, `em`, `vh`, `vw`) are not supported by React Native.
+> **Note:** CSS units (`rem`, `em`, `vh`, `vw`) are not supported by React Native.
 
 ### Custom Colors
 
@@ -567,7 +987,7 @@ Access the parser and constants programmatically:
 import { parseClassName, COLORS, SPACING_SCALE } from "@mgcrea/react-native-tailwind";
 
 // Parse className strings
-const styles = parseClassName("m-4 p-2 bg-blue-500");
+const _twStyles = parseClassName("m-4 p-2 bg-blue-500");
 // Returns: { margin: 16, padding: 8, backgroundColor: '#3B82F6' }
 
 // Access default scales