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@alpha init -y and npx gluestack-ui@alpha 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
<VStack space="lg" className="p-4">
<Heading size="xl" bold>Title</Heading>
<Text size="md" className="text-muted-foreground">Description</Text>
</VStack>
<Button variant="outline" size="lg">
<ButtonText>Click Me</ButtonText>
<ButtonIcon as={ChevronRightIcon} />
</Button>
<Input>
<InputSlot>
<InputIcon as={MailIcon} className="text-muted-foreground" />
</InputSlot>
<InputField placeholder="Enter email" />
</Input>
<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.
