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
// 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
3description: 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.
4metadata:
5 source: https://skillmd.com/skills/gluestack/gluestack-ui-v4
6---
7
8# Gluestack UI v4 Design Patterns
9
10This 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.
11
12## Core Principles
13
141. **Gluestack components over React Native primitives** - Gluestack wraps RN with theming, accessibility, and cross-platform consistency
152. **Component props over className utilities** - Use built-in props (size, variant, space) instead of className when available
163. **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
174. **className over inline styles** - Inline styles bypass optimization and consistency
185. **Spacing scale over pixel values** - Arbitrary values create unsustainable exceptions
196. **Copy-paste philosophy** - Components are copied into your codebase, not installed as dependencies
207. **Composable sub-components** - Use compound component patterns for flexibility
218. **Remove dead code** - Unused patterns mislead AI and increase cognitive load
22
23## When to Use This Skill
24
25- Creating new components with styling
26- Reviewing existing component styles
27- Refactoring styles to follow the design system
28- Fixing styling inconsistencies
29- Adding dark mode support
30- Theming components
31- Copying components from gluestack-ui into your project
32
33**Before using any component, always verify the latest usage patterns at `https://v4.gluestack.io/ui/docs/components/${componentName}/`**
34
35## Sub-Skills Organization
36
37This skill is organized into specialized sub-skills for better token efficiency:
38
39### 1. gluestack-ui-v4:setup
40**Use for:** Initial project setup, installation, configuration, adding components
41
42Covers:
43- Using the official CLI (`npx gluestack-ui@alpha init -y` and `npx gluestack-ui@alpha add --all -y`)
44- Project initialization for Expo, React Native CLI, and Next.js
45- Dependency management
46- Configuration files (tailwind, metro, babel, etc.)
47- GluestackUIProvider setup
48- Adding individual components
49- Troubleshooting setup issues
50
51**Invoke when:** Setting up gluestack-ui in a new or existing project, adding components via CLI, or troubleshooting installation issues
52
53### 2. gluestack-ui-v4:creating-components
54**Use for:** Step-by-step component creation, templates, recipes
55
56Covers:
57- Component creation workflow
58- 6 ready-to-use templates (simple, variants, compound, form, interactive, loading)
59- Common component recipes (profile cards, badges, search, lists)
60- Best practices checklist
61- Quick start guide
62
63**Invoke when:** Creating new components from scratch or need component templates
64
65### 3. gluestack-ui-v4:components
66**Use for:** Component usage, compound patterns, icons, provider setup
67
68Covers:
69- Using Gluestack components over React Native primitives
70- Component props vs className utilities
71- Compound component patterns (Input, Button, FormControl, etc.)
72- Icon usage hierarchy
73- Provider setup
74
75**Invoke when:** Working with component structure, props, and composition
76
77### 4. gluestack-ui-v4:styling
78**Use for:** Colors, spacing, dark mode, variants, className
79
80Covers:
81- Semantic color tokens
82- Spacing scale adherence
83- Dark mode with CSS variables
84- Variant-based styling with tva
85- className merging
86
87**Invoke when:** Styling components, theming, or working with colors and spacing
88
89### 5. gluestack-ui-v4:variants
90**Use for:** Creating custom variants for components, extending design system
91
92Covers:
93- When and how to create variants
94- Using tva for variant management
95- Extending existing Gluestack components
96- Parent-child variant relationships
97- Compound variants for complex combinations
98- Common variant patterns (badges, alerts, cards)
99- Converting repeated styles to variants
100
101**Invoke when:** Need to create custom variants for components, extend component styling options, or standardize repeated style patterns
102
103### 6. gluestack-ui-v4:performance
104**Use for:** Cross-platform, performance optimization, best practices
105
106Covers:
107- Cross-platform rendering (Native & Web)
108- TypeScript usage
109- Component memoization
110- Animations with Reanimated
111- Safe area handling
112- FlatList for lists
113- Platform-specific code
114
115**Invoke when:** Optimizing performance, ensuring cross-platform compatibility, or following React Native best practices
116
117### 7. gluestack-ui-v4:validation
118**Use for:** Code review, anti-patterns, validation checklist
119
120Covers:
121- Complete validation checklist
122- Anti-patterns to avoid
123- Common mistakes
124- Escalation guidance
125
126**Invoke when:** Reviewing code, validating implementation, or checking for anti-patterns
127
128## Quick Reference
129
130### Resolution Hierarchy (in order of preference)
131
1321. **Component props** - Use built-in props (size, variant, space)
1332. **className utilities** - Use existing Tailwind/NativeWind classes
1343. **Gluestack component variants** - Use built-in component variants
1354. **tva (Tailwind Variant Authority)** - Create reusable variant patterns
1365. **NativeWind interop** - Enable className on third-party components
1376. **Inline styles** - Only as absolute last resort with documented justification
138
139### Common Patterns
140
141```tsx
142// Component usage with props
143<VStack space="lg" className="p-4">
144 <Heading size="xl" bold>Title</Heading>
145 <Text size="md" className="text-muted-foreground">Description</Text>
146</VStack>
147
148// Button with compound components
149<Button variant="outline" size="lg">
150 <ButtonText>Click Me</ButtonText>
151 <ButtonIcon as={ChevronRightIcon} />
152</Button>
153
154// Input with icon (InputIcon MUST be in InputSlot)
155<Input>
156 <InputSlot>
157 <InputIcon as={MailIcon} className="text-muted-foreground" />
158 </InputSlot>
159 <InputField placeholder="Enter email" />
160</Input>
161
162// Semantic color tokens
163<Box className="bg-primary text-primary-foreground">
164 <Text className="text-foreground">Content</Text>
165</Box>
166```
167
168## Key Rules Summary
169
1701. **Always use Gluestack components** instead of React Native primitives
1712. **Use component props** (space, size, variant) instead of className when available
1723. **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`)
1734. **No inline styles** unless absolutely necessary
1745. **Follow spacing scale** (0, 0.5, 1, 2, 3, 4, etc.) - no arbitrary values
1756. **Compound components required** - ButtonText, InputSlot, FormControlLabel, etc.
1767. **InputIcon MUST be wrapped in InputSlot** - this is critical
1778. **Use tva for variants** when creating custom components with multiple styles
1789. **Dark mode with dark: prefix** - uses CSS variables
17910. **Cross-platform compatible** - use Gluestack wrappers, not direct React Native imports
180
181## Reference Documentation
182
183**IMPORTANT: Always verify component usage and patterns in the official v4 documentation before using components.**
184
185- **Component Docs**: `https://v4.gluestack.io/ui/docs/components/${componentName}/`
186- **Complete Documentation**: https://v4.gluestack.io/ui/docs
187- **Import Path**: `@/components/ui/${componentName}`
188
189## How to Use Sub-Skills
190
191When working on specific tasks, invoke the appropriate sub-skill for detailed guidance:
192
193- **Setting up gluestack-ui or adding components?** → Use `gluestack-ui-v4:setup`
194- **Creating a new component?** → Use `gluestack-ui-v4:creating-components`
195- **Component structure questions?** → Use `gluestack-ui-v4:components`
196- **Styling and theming questions?** → Use `gluestack-ui-v4:styling`
197- **Creating or extending component variants?** → Use `gluestack-ui-v4:variants`
198- **Performance or cross-platform questions?** → Use `gluestack-ui-v4:performance`
199- **Need to validate or review code?** → Use `gluestack-ui-v4:validation`
200
201Each sub-skill provides focused, detailed guidance on its specific domain while maintaining consistency with these core principles.