Gluestack UI v4 Design Patterns
This skill enforces constrained, opinionated styling patterns for gluestack-ui v4 that reduce decision fatigue, improve performance, enable consistent theming, and limit the solution space to canonical patterns.
Core Principles
- Gluestack components over React Native primitives - Gluestack wraps RN with theming, accessibility, and cross-platform consistency
- Component props over className utilities - Use built-in props (size, variant, space) instead of className when available
- Semantic tokens ONLY - NO EXCEPTIONS - NEVER use generic tokens (
typography-*, neutral-*, gray-*) or numbered colors (red-500, blue-600). ONLY use semantic tokens (text-foreground, bg-primary, border-border, etc.) with optional alpha values
- className over inline styles - Inline styles bypass optimization and consistency
- Spacing scale over pixel values - Arbitrary values create unsustainable exceptions
- Copy-paste philosophy - Components are copied into your codebase, not installed as dependencies
- Composable sub-components - Use compound component patterns for flexibility
- Remove dead code - Unused patterns mislead AI and increase cognitive load
When to Use This Skill
- Creating new components with styling
- Reviewing existing component styles
- Refactoring styles to follow the design system
- Fixing styling inconsistencies
- Adding dark mode support
- Theming components
- Copying components from gluestack-ui into your project
Before using any component, always verify the latest usage patterns at https://v4.gluestack.io/ui/docs/components/${componentName}/
Sub-Skills Organization
This skill is organized into specialized sub-skills for better token efficiency:
1. gluestack-ui-v4:setup
Use for: Initial project setup, installation, configuration, adding components
Covers:
- Using the official CLI (
npx gluestack-ui init -y and npx gluestack-ui add --all -y)
- Project initialization for Expo, React Native CLI, and Next.js
- Dependency management
- Configuration files (tailwind, metro, babel, etc.)
- GluestackUIProvider setup
- Adding individual components
- Troubleshooting setup issues
Invoke when: Setting up gluestack-ui in a new or existing project, adding components via CLI, or troubleshooting installation issues
2. gluestack-ui-v4:creating-components
Use for: Step-by-step component creation, templates, recipes
Covers:
- Component creation workflow
- 6 ready-to-use templates (simple, variants, compound, form, interactive, loading)
- Common component recipes (profile cards, badges, search, lists)
- Best practices checklist
- Quick start guide
Invoke when: Creating new components from scratch or need component templates
3. gluestack-ui-v4:components
Use for: Component usage, compound patterns, icons, provider setup
Covers:
- Using Gluestack components over React Native primitives
- Component props vs className utilities
- Compound component patterns (Input, Button, FormControl, etc.)
- Icon usage hierarchy
- Provider setup
Invoke when: Working with component structure, props, and composition
4. gluestack-ui-v4:styling
Use for: Colors, spacing, dark mode, variants, className
Covers:
- Semantic color tokens
- Spacing scale adherence
- Dark mode with CSS variables
- Variant-based styling with tva
- className merging
Invoke when: Styling components, theming, or working with colors and spacing
5. gluestack-ui-v4:variants
Use for: Creating custom variants for components, extending design system
Covers:
- When and how to create variants
- Using tva for variant management
- Extending existing Gluestack components
- Parent-child variant relationships
- Compound variants for complex combinations
- Common variant patterns (badges, alerts, cards)
- Converting repeated styles to variants
Invoke when: Need to create custom variants for components, extend component styling options, or standardize repeated style patterns
6. gluestack-ui-v4:performance
Use for: Cross-platform, performance optimization, best practices
Covers:
- Cross-platform rendering (Native & Web)
- TypeScript usage
- Component memoization
- Animations with Reanimated
- Safe area handling
- FlatList for lists
- Platform-specific code
Invoke when: Optimizing performance, ensuring cross-platform compatibility, or following React Native best practices
7. gluestack-ui-v4:validation
Use for: Code review, anti-patterns, validation checklist
Covers:
- Complete validation checklist
- Anti-patterns to avoid
- Common mistakes
- Escalation guidance
Invoke when: Reviewing code, validating implementation, or checking for anti-patterns
Quick Reference
Resolution Hierarchy (in order of preference)
- Component props - Use built-in props (size, variant, space)
- className utilities - Use existing Tailwind/NativeWind classes
- Gluestack component variants - Use built-in component variants
- tva (Tailwind Variant Authority) - Create reusable variant patterns
- NativeWind interop - Enable className on third-party components
- Inline styles - Only as absolute last resort with documented justification
Common Patterns
// Component usage with props
<VStack space="lg" className="p-4">
<Heading size="xl" bold>Title</Heading>
<Text size="md" className="text-muted-foreground">Description</Text>
</VStack>
// Button with compound components
<Button variant="outline" size="lg">
<ButtonText>Click Me</ButtonText>
<ButtonIcon as={ChevronRightIcon} />
</Button>
// Input with icon (InputIcon MUST be in InputSlot)
<Input>
<InputSlot>
<InputIcon as={MailIcon} className="text-muted-foreground" />
</InputSlot>
<InputField placeholder="Enter email" />
</Input>
// Semantic color tokens
<Box className="bg-primary text-primary-foreground">
<Text className="text-foreground">Content</Text>
</Box>
Key Rules Summary
- Always use Gluestack components instead of React Native primitives
- Use component props (space, size, variant) instead of className when available
- CRITICAL: ONLY semantic tokens for colors - NEVER use
typography-*, neutral-*, gray-*, slate-*, or numbered colors (red-500, blue-600). ONLY use semantic tokens: text-foreground, text-muted-foreground, bg-primary, bg-card, border-border, etc. with optional alpha values (/70, /90)
- No inline styles unless absolutely necessary
- Follow spacing scale (0, 0.5, 1, 2, 3, 4, etc.) - no arbitrary values
- Compound components required - ButtonText, InputSlot, FormControlLabel, etc.
- InputIcon MUST be wrapped in InputSlot - this is critical
- Use tva for variants when creating custom components with multiple styles
- Dark mode with dark: prefix - uses CSS variables
- Cross-platform compatible - use Gluestack wrappers, not direct React Native imports
Reference Documentation
IMPORTANT: Always verify component usage and patterns in the official v4 documentation before using components.
- Component Docs:
https://v4.gluestack.io/ui/docs/components/${componentName}/
- Complete Documentation: https://v4.gluestack.io/ui/docs
- Import Path:
@/components/ui/${componentName}
How to Use Sub-Skills
When working on specific tasks, invoke the appropriate sub-skill for detailed guidance:
- Setting up gluestack-ui or adding components? → Use
gluestack-ui-v4:setup
- Creating a new component? → Use
gluestack-ui-v4:creating-components
- Component structure questions? → Use
gluestack-ui-v4:components
- Styling and theming questions? → Use
gluestack-ui-v4:styling
- Creating or extending component variants? → Use
gluestack-ui-v4:variants
- Performance or cross-platform questions? → Use
gluestack-ui-v4:performance
- Need to validate or review code? → Use
gluestack-ui-v4:validation
Each sub-skill provides focused, detailed guidance on its specific domain while maintaining consistency with these core principles.
1---2name: gluestack-ui-v4-23description: Enforces constrained, opinionated styling patterns for gluestack-ui v4. Main overview skill that coordinates specialized sub-skills for setup, components, styling, variants, performance, and validation.4---56# Gluestack UI v4 Design Patterns78This skill enforces constrained, opinionated styling patterns for gluestack-ui v4 that reduce decision fatigue, improve performance, enable consistent theming, and limit the solution space to canonical patterns.910## Core Principles11121. **Gluestack components over React Native primitives** - Gluestack wraps RN with theming, accessibility, and cross-platform consistency132. **Component props over className utilities** - Use built-in props (size, variant, space) instead of className when available143. **Semantic tokens ONLY - NO EXCEPTIONS** - NEVER use generic tokens (`typography-*`, `neutral-*`, `gray-*`) or numbered colors (`red-500`, `blue-600`). ONLY use semantic tokens (`text-foreground`, `bg-primary`, `border-border`, etc.) with optional alpha values154. **className over inline styles** - Inline styles bypass optimization and consistency165. **Spacing scale over pixel values** - Arbitrary values create unsustainable exceptions176. **Copy-paste philosophy** - Components are copied into your codebase, not installed as dependencies187. **Composable sub-components** - Use compound component patterns for flexibility198. **Remove dead code** - Unused patterns mislead AI and increase cognitive load2021## When to Use This Skill2223- Creating new components with styling24- Reviewing existing component styles25- Refactoring styles to follow the design system26- Fixing styling inconsistencies27- Adding dark mode support28- Theming components29- Copying components from gluestack-ui into your project3031**Before using any component, always verify the latest usage patterns at `https://v4.gluestack.io/ui/docs/components/${componentName}/`**3233## Sub-Skills Organization3435This skill is organized into specialized sub-skills for better token efficiency:3637### 1. gluestack-ui-v4:setup38**Use for:** Initial project setup, installation, configuration, adding components3940Covers:41- Using the official CLI (`npx gluestack-ui init -y` and `npx gluestack-ui add --all -y`)42- Project initialization for Expo, React Native CLI, and Next.js43- Dependency management44- Configuration files (tailwind, metro, babel, etc.)45- GluestackUIProvider setup46- Adding individual components47- Troubleshooting setup issues4849**Invoke when:** Setting up gluestack-ui in a new or existing project, adding components via CLI, or troubleshooting installation issues5051### 2. gluestack-ui-v4:creating-components52**Use for:** Step-by-step component creation, templates, recipes5354Covers:55- Component creation workflow56- 6 ready-to-use templates (simple, variants, compound, form, interactive, loading)57- Common component recipes (profile cards, badges, search, lists)58- Best practices checklist59- Quick start guide6061**Invoke when:** Creating new components from scratch or need component templates6263### 3. gluestack-ui-v4:components64**Use for:** Component usage, compound patterns, icons, provider setup6566Covers:67- Using Gluestack components over React Native primitives68- Component props vs className utilities69- Compound component patterns (Input, Button, FormControl, etc.)70- Icon usage hierarchy71- Provider setup7273**Invoke when:** Working with component structure, props, and composition7475### 4. gluestack-ui-v4:styling76**Use for:** Colors, spacing, dark mode, variants, className7778Covers:79- Semantic color tokens80- Spacing scale adherence81- Dark mode with CSS variables82- Variant-based styling with tva83- className merging8485**Invoke when:** Styling components, theming, or working with colors and spacing8687### 5. gluestack-ui-v4:variants88**Use for:** Creating custom variants for components, extending design system8990Covers:91- When and how to create variants92- Using tva for variant management93- Extending existing Gluestack components94- Parent-child variant relationships95- Compound variants for complex combinations96- Common variant patterns (badges, alerts, cards)97- Converting repeated styles to variants9899**Invoke when:** Need to create custom variants for components, extend component styling options, or standardize repeated style patterns100101### 6. gluestack-ui-v4:performance102**Use for:** Cross-platform, performance optimization, best practices103104Covers:105- Cross-platform rendering (Native & Web)106- TypeScript usage107- Component memoization108- Animations with Reanimated109- Safe area handling110- FlatList for lists111- Platform-specific code112113**Invoke when:** Optimizing performance, ensuring cross-platform compatibility, or following React Native best practices114115### 7. gluestack-ui-v4:validation116**Use for:** Code review, anti-patterns, validation checklist117118Covers:119- Complete validation checklist120- Anti-patterns to avoid121- Common mistakes122- Escalation guidance123124**Invoke when:** Reviewing code, validating implementation, or checking for anti-patterns125126## Quick Reference127128### Resolution Hierarchy (in order of preference)1291301. **Component props** - Use built-in props (size, variant, space)1312. **className utilities** - Use existing Tailwind/NativeWind classes1323. **Gluestack component variants** - Use built-in component variants1334. **tva (Tailwind Variant Authority)** - Create reusable variant patterns1345. **NativeWind interop** - Enable className on third-party components1356. **Inline styles** - Only as absolute last resort with documented justification136137### Common Patterns138139```tsx140// Component usage with props141<VStack space="lg" className="p-4">142 <Heading size="xl" bold>Title</Heading>143 <Text size="md" className="text-muted-foreground">Description</Text>144</VStack>145146// Button with compound components147<Button variant="outline" size="lg">148 <ButtonText>Click Me</ButtonText>149 <ButtonIcon as={ChevronRightIcon} />150</Button>151152// Input with icon (InputIcon MUST be in InputSlot)153<Input>154 <InputSlot>155 <InputIcon as={MailIcon} className="text-muted-foreground" />156 </InputSlot>157 <InputField placeholder="Enter email" />158</Input>159160// Semantic color tokens161<Box className="bg-primary text-primary-foreground">162 <Text className="text-foreground">Content</Text>163</Box>164```165166## Key Rules Summary1671681. **Always use Gluestack components** instead of React Native primitives1692. **Use component props** (space, size, variant) instead of className when available1703. **CRITICAL: ONLY semantic tokens for colors** - NEVER use `typography-*`, `neutral-*`, `gray-*`, `slate-*`, or numbered colors (`red-500`, `blue-600`). ONLY use semantic tokens: `text-foreground`, `text-muted-foreground`, `bg-primary`, `bg-card`, `border-border`, etc. with optional alpha values (`/70`, `/90`)1714. **No inline styles** unless absolutely necessary1725. **Follow spacing scale** (0, 0.5, 1, 2, 3, 4, etc.) - no arbitrary values1736. **Compound components required** - ButtonText, InputSlot, FormControlLabel, etc.1747. **InputIcon MUST be wrapped in InputSlot** - this is critical1758. **Use tva for variants** when creating custom components with multiple styles1769. **Dark mode with dark: prefix** - uses CSS variables17710. **Cross-platform compatible** - use Gluestack wrappers, not direct React Native imports178179## Reference Documentation180181**IMPORTANT: Always verify component usage and patterns in the official v4 documentation before using components.**182183- **Component Docs**: `https://v4.gluestack.io/ui/docs/components/${componentName}/`184- **Complete Documentation**: https://v4.gluestack.io/ui/docs185- **Import Path**: `@/components/ui/${componentName}`186187## How to Use Sub-Skills188189When working on specific tasks, invoke the appropriate sub-skill for detailed guidance:190191- **Setting up gluestack-ui or adding components?** → Use `gluestack-ui-v4:setup`192- **Creating a new component?** → Use `gluestack-ui-v4:creating-components`193- **Component structure questions?** → Use `gluestack-ui-v4:components`194- **Styling and theming questions?** → Use `gluestack-ui-v4:styling`195- **Creating or extending component variants?** → Use `gluestack-ui-v4:variants`196- **Performance or cross-platform questions?** → Use `gluestack-ui-v4:performance`197- **Need to validate or review code?** → Use `gluestack-ui-v4:validation`198199Each sub-skill provides focused, detailed guidance on its specific domain while maintaining consistency with these core principles.