Gluestack Ui V4

# Gluestack UI v4 - Component Patterns

This sub-skill focuses on component usage, compound component patterns, icon handling, and provider setup for gluestack-ui v4.

## Rule 1: Gluestack Components Over React Native Primitives

Always use Gluestack components instead of direct React Native imports:

| React Native                         | Gluestack Equivalent                           |
| ------------------------------------ | ---------------------------------------------- |
| View from "react-native"             | Box from "@/components/ui/box"                 |
| Text from "react-native"             | Text from "@/components/ui/text"               |
| TouchableOpacity from "react-native" | Pressable from "@/components/ui/pressable"     |
| ScrollView from "react-native"       | ScrollView from "@/components/ui/scroll-view"  |
| Image from "react-native"            | Image from "@/components/ui/image"             |
| TextInput from "react-native"        | Input, InputField from "@/components/ui/input" |
| FlatList from "react-native"         | FlatList from "@/components/ui/flat-list"      |

### Correct Pattern

```tsx
import { Box } from "@/components/ui/box";
import { Text } from "@/components/ui/text";
import { Pressable } from "@/components/ui/pressable";

const Component = () => (
  <Box className="p-4">
    <Text className="text-foreground">Hello</Text>
    <Pressable onPress={handlePress}>
      <Text>Press Me</Text>
    </Pressable>
  </Box>
);
```

### Incorrect Pattern

```tsx
import { View, Text, TouchableOpacity } from "react-native";

const Component = () => (
  <View style={{ padding: 16 }}>
    <Text style={{ color: "#333" }}>Hello</Text>
    <TouchableOpacity onPress={handlePress}>
      <Text>Press Me</Text>
    </TouchableOpacity>
  </View>
);
```

### Exceptions

- Platform-specific code where RN primitives are explicitly required
- Deep integration with native modules
- Performance-critical paths where wrapper overhead matters (rare, must document)

## Rule 2: Use Component Props Over className Utilities

Always prefer component props over className utilities when a component provides built-in props. This ensures type safety, better maintainability, and consistent styling.

### Component Props vs className

Many Gluestack components provide props that map to common styling needs. Use these props instead of className utilities:

| Component | Use Prop Instead of className | Available Values |
|-----------|------------------------------|-----------------|
| `VStack` / `HStack` | `space` instead of `gap-*` | `xs`, `sm`, `md`, `lg`, `xl`, `2xl`, `3xl`, `4xl` |
| `Button` | `variant` instead of `bg-*` classes | `default`, `destructive`, `outline`, `secondary`, `ghost`, `link` |
| `Button` | `size` instead of `px-* py-*` classes | `default`, `sm`, `lg`, `icon` |
| `Heading` | `size` instead of `text-*` classes | `xs`, `sm`, `md`, `lg`, `xl`, `2xl`, `3xl`, `4xl`, `5xl` |
| `Text` | `size` instead of `text-*` classes | `2xs`, `xs`, `sm`, `md`, `lg`, `xl`, `2xl`, `3xl`, `4xl`, `5xl`, `6xl` |
| `Heading` / `Text` | `bold` prop instead of `font-bold` | boolean |
| `Heading` / `Text` | `isTruncated` prop instead of `truncate` | boolean |
| `VStack` / `HStack` | `reversed` prop instead of `flex-*-reverse` | boolean |

### Correct Pattern: Using Component Props

```tsx
// ✅ CORRECT: Using space prop instead of gap className
<VStack space="lg">
  <Box>Item 1</Box>
  <Box>Item 2</Box>
</VStack>

// ✅ CORRECT: Using Button variant and size props
<Button variant="outline" size="lg">
  <ButtonText>Click Me</ButtonText>
</Button>

// ✅ CORRECT: Using Heading size prop
<Heading size="2xl" bold>
  Title
</Heading>

// ✅ CORRECT: Using Text size and bold props
<Text size="sm" bold>
  Important text
</Text>

// ✅ CORRECT: Using HStac