Gluestack Ui V5

Gluestack UI v5 Design Patterns

This skill enforces constrained, opinionated styling patterns for gluestack-ui v5 (Tailwind CSS v4 with CSS-first configuration) that reduce decision fatigue, improve performance, enable consistent theming, and limit the solution space to canonical patterns. Supports both NativeWind v5 (Expo + RN CLI) and UniWind (Expo only) styling engines.

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 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
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://gluestack.io/ui/docs/components/${componentName}/

Sub-Skills Organization

This skill is organized into specialized sub-skills for better token efficiency:

1. gluestack-ui-v5:setup

Use for: Initial project setup, installation, configuration, adding components

Covers:

• Using the official CLI (npx gluestack-ui@latest init and npx gluestack-ui@latest add --all)
• Project initialization for Expo and React Native CLI (Next.js support pending NativeWind v5 web)
• 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-v5: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-v5: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-v5: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-v5: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-v5: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-v5: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. CSS variables (@theme inline) - Tailwind v4 auto-resolves tokens from global.css into utility classes
5. tva (Tailwind Variant Authority) - Create reusable variant patterns
6. NativeWind interop - Enable className on third-party components
7. Inline styles - Only as absolute last resort with documented justification

Common Patterns

// Component usage with props

  Title
  Description

// Button with compound components

  Click Me
  

// Input with icon (InputIcon MUST be in InputSlot)

  
    
  
  

// Semantic color tokens

  Content

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. 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)
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 v5 documentation before using components.

• Component Docs: https://gluestack.io/ui/docs/components/${componentName}/
• Complete Documentation: https://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-v5:setup
• Creating a new component? → Use gluestack-ui-v5:creating-components
• Component structure questions? → Use gluestack-ui-v5:components
• Styling and theming questions? → Use gluestack-ui-v5:styling
• Creating or extending component variants? → Use gluestack-ui-v5:variants
• Performance or cross-platform questions? → Use gluestack-ui-v5:performance
• Need to validate or review code? → Use gluestack-ui-v5:validation

Each sub-skill provides focused, detailed guidance on its specific domain while maintaining consistency with these core principles.

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: gluestack
• Source: gluestack/agent-skills
• License: MIT

Install and usage instructions live in the source repository linked above.