gluestack-ui-v4:styling

What this skill does

# Gluestack UI v4 - Styling Patterns

This sub-skill focuses on styling patterns, theming, colors, spacing, dark mode, and variant management for gluestack-ui v4.

## Rule 3: Semantic Color Tokens Over Raw Values (v4)

**CRITICAL**: You MUST use only Gluestack v4 semantic tokens. Generic tokens like `typography-*`, `neutral-*`, `gray-*`, `slate-*`, or any numbered color tokens (`red-500`, `blue-600`, etc.) are **STRICTLY PROHIBITED**.

### Prohibited Token Patterns

**NEVER use these token patterns:**

| Prohibited Pattern | Why It's Wrong | Use Instead |
| ------------------ | -------------- | ----------- |
| `typography-*` | Generic, not semantic | `text-foreground`, `text-muted-foreground`, `text-card-foreground` |
| `neutral-*` | Generic, not semantic | `text-foreground`, `bg-background`, `bg-muted` |
| `gray-*`, `slate-*` | Raw color, not semantic | `text-muted-foreground`, `bg-muted`, `border-border` |
| `text-red-500`, `bg-red-600` | Numbered colors, not semantic | `text-destructive`, `bg-destructive` |
| `text-green-500`, `bg-green-600` | Numbered colors, not semantic | `text-primary` (for success states) |
| `text-blue-500`, `bg-blue-600` | Numbered colors, not semantic | `text-primary`, `bg-primary` |
| `border-gray-200` | Raw color, not semantic | `border-border` |
| `#DC2626`, `#3b82f6` (inline) | Hex values, not semantic | `text-destructive`, `bg-primary` |
| `bg-white`, `bg-black` | Raw colors, not semantic | `bg-background`, `text-foreground` |
| `text-opacity-*` | Opacity utilities | Use alpha values: `text-foreground/70` |

### Correct Semantic Token Replacement Guide

Use Gluestack v4 semantic tokens instead of raw Tailwind colors or arbitrary values:

| Instead of | Use |
| ---------- | --- |
| text-red-500 | text-destructive |
| text-green-500 | text-primary (for success) |
| text-blue-500 | text-primary |
| text-gray-500, text-neutral-500 | text-muted-foreground |
| text-gray-900, text-typography-900 | text-foreground |
| bg-blue-600 | bg-primary |
| bg-gray-100, bg-neutral-100 | bg-muted |
| bg-gray-50 | bg-background |
| border-gray-200, border-neutral-200 | border-border |
| #DC2626 (inline) | text-destructive |
| bg-white | bg-background |
| text-black | text-foreground |

### Available Semantic Token Categories (v4)

| Token                | Purpose                                  | Usage Example                        |
| -------------------- | ---------------------------------------- | ------------------------------------ |
| primary              | Brand identity, key interactive elements | `bg-primary`, `text-primary`         |
| primary-foreground   | Text on primary backgrounds              | `text-primary-foreground`            |
| secondary            | Secondary actions, supporting elements   | `bg-secondary`                       |
| secondary-foreground | Text on secondary backgrounds            | `text-secondary-foreground`          |
| background           | Main background color                    | `bg-background`                      |
| foreground           | Main text color                          | `text-foreground`                    |
| card                 | Card backgrounds                         | `bg-card`                            |
| card-foreground      | Text on card backgrounds                 | `text-card-foreground`               |
| popover              | Popover/modal backgrounds                | `bg-popover`                         |
| popover-foreground   | Text on popover backgrounds              | `text-popover-foreground`            |
| muted                | Muted backgrounds                        | `bg-muted`                           |
| muted-foreground     | Muted text color                         | `text-muted-foreground`              |
| destructive          | Error states, destructive actions        | `bg-destructive`, `text-destructive` |
| border               | Border colors                            | `border-border`                      |
| input                | Input border colors                      | `border-input`                       |
| ring                 | Focus ring colors                        | `ring-ring`                          |
| accent               | Accent highlights                        | `bg-accent`                          |
| accent-foreground    | Text on accent backgrounds               | `text-accent-foreground`             |

### CRITICAL: Why Semantic Tokens Are Mandatory

**Semantic tokens are NOT optional**. They are required for:

1. **Theme Consistency** - Tokens automatically adapt to light/dark modes
2. **Maintainability** - Change theme once, update everywhere
3. **Intent Expression** - `text-destructive` communicates purpose, `text-red-500` doesn't
4. **Future-Proofing** - Theme changes don't require code updates
5. **Accessibility** - Tokens ensure proper contrast ratios

**If you use generic tokens (`typography-*`, `neutral-*`) or numbered colors (`gray-500`, `blue-600`), the component will:**
- Break in dark mode
- Fail to match the design system
- Create maintenance debt
- Violate gluestack-ui v4 design principles

### Alpha Values

All color tokens support alpha values using the `/` syntax:

```tsx
// ✅ CORRECT: Using alpha values with semantic tokens
<Box className="bg-primary/90" />
<Text className="text-foreground/70" />
<Box className="border-border/80" />

// ❌ INCORRECT: Never use opacity utilities
<Text className="text-gray-900 opacity-70" />
<Box className="bg-blue-500 bg-opacity-90" />

// ✅ CORRECT: Alpha values, not opacity utilities
<Text className="text-foreground/70" />
<Box className="bg-primary/90" />
```

### Correct Pattern

```tsx
<Box className="bg-destructive">
  <Text className="text-white">Error message</Text>
</Box>

<Box className="border border-border bg-card">
  <Text className="text-card-foreground">Success!</Text>
</Box>

<Box className="bg-primary/90">
  <Text className="text-primary-foreground">Primary action</Text>
</Box>
```

### Incorrect Pattern

```tsx
// ❌ PROHIBITED: Numbered color tokens
<Box className="bg-red-500">
  <Text className="text-white">Error message</Text>
</Box>

// ❌ PROHIBITED: Inline hex values
<Box style={{ backgroundColor: '#DC2626' }}>
  <Text style={{ color: 'green' }}>Success!</Text>
</Box>

// ❌ PROHIBITED: Arbitrary color values
<Box className="bg-[#3b82f6]">
  <Text className="text-[#ffffff]">Primary action</Text>
</Box>

// ❌ PROHIBITED: Generic tokens (typography, neutral)
<Text className="text-typography-900">Heading</Text>
<Box className="bg-neutral-100">
  <Text className="text-neutral-600">Description</Text>
</Box>

// ❌ PROHIBITED: Gray/Slate color scales
<Text className="text-gray-700">Content</Text>
<Box className="bg-slate-100 border-gray-300">
  <Text className="text-gray-900">Text</Text>
</Box>

// ❌ PROHIBITED: Opacity utilities instead of alpha
<Text className="text-black opacity-70">Muted text</Text>
<Box className="bg-blue-600 bg-opacity-90">Content</Box>
```

## Rule 3: No Inline Styles

Avoid inline `style` props when className can achieve the same result.

### Resolution Hierarchy (in order of preference)

1. **className utilities** - Use existing Tailwind/NativeWind classes
2. **Gluestack component variants** - Use built-in component variants
3. **tva (Tailwind Variant Authority)** - Create reusable variant patterns
4. **NativeWind interop** - Enable className on third-party components
5. **Inline styles** - Only as absolute last resort with documented justification

### Correct Pattern

```tsx
<Box className="w-20 h-20 rounded-full bg-background" />

<Text size="lg" bold className="text-foreground" />

<Button variant="outline" size="lg">
  <ButtonText>Click Me</ButtonText>
</Button>
```

### Incorrect Pattern

```tsx
<Box
  style={{
    width: 80,
    height: 80,
    borderRadius: 40,
    backgroundColor: "rgba(255, 255, 255, 0.1)",
  }}
/>

<Text style={{ fontSize: 18, fontWeight: "bold", color: "#000" }} />
```

### Acceptable Except