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

1. Gluestack components over React Native primitives - Gluestack wraps RN with theming, accessibility, and cross-platform consistency
2. Component props over className utilities - Use built-in props (size, variant, space) instead of className when available
3. Semantic tokens over arbitrary values - Tokens encode intent, not just appearance
4. className over inline styles - Inline styles bypass optimization and consistency
5. Spacing scale over pixel values - Arbitrary values create unsustainable exceptions
6. Copy-paste philosophy - Components are copied into your codebase, not installed as dependencies
7. Composable sub-components - Use compound component patterns for flexibility
8. 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 and add)
• 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)

1. Component props - Use built-in props (size, variant, space)
2. className utilities - Use existing Tailwind/NativeWind classes
3. Gluestack component variants - Use built-in component variants
4. tva (Tailwind Variant Authority) - Create reusable variant patterns
5. NativeWind interop - Enable className on third-party components
6. 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

1. Always use Gluestack components instead of React Native primitives
2. Use component props (space, size, variant) instead of className when available
3. Use semantic tokens for colors (text-primary, bg-card, etc.)
4. No inline styles unless absolutely necessary
5. Follow spacing scale (0, 0.5, 1, 2, 3, 4, etc.) - no arbitrary values
6. Compound components required - ButtonText, InputSlot, FormControlLabel, etc.
7. InputIcon MUST be wrapped in InputSlot - this is critical
8. Use tva for variants when creating custom components with multiple styles
9. Dark mode with dark: prefix - uses CSS variables
10. 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.