gluestack-ui-v5

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Gluestack UI v5 Design Patterns

Gluestack UI v5 设计规范

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.

本技能为gluestack-ui v5（采用CSS优先配置的Tailwind CSS v4）强制执行受限的、约定式的样式规范，可减少决策疲劳、提升性能、实现一致的主题化，并将解决方案限定为标准模式。同时支持NativeWind v5（Expo + RN CLI）和UniWind（仅Expo）样式引擎。

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

优先使用Gluestack组件而非React Native原生组件 - Gluestack为RN封装了主题、无障碍支持和跨平台一致性特性
优先使用组件props而非className工具类 - 当存在内置props（size、variant、space）时，优先使用它们而非className
仅使用语义化令牌——无例外 - 绝不能使用通用令牌（
```
typography-*
```
、
```
neutral-*
```
、
```
gray-*
```
）或带编号的颜色（
```
red-500
```
、
```
blue-600
```
）。仅可使用语义化令牌（
```
text-foreground
```
、
```
bg-primary
```
、
```
border-border
```
等），可选择性添加透明度值
优先使用className而非内联样式 - 内联样式会绕过优化机制，破坏一致性
优先使用间距刻度而非像素值 - 任意值会导致难以维护的例外情况
复制粘贴理念 - 组件需复制到你的代码库中，而非作为依赖安装
可组合的子组件 - 使用复合组件模式提升灵活性
移除无用代码 - 未使用的模式会误导AI并增加认知负担

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}/

创建带样式的新组件
审查现有组件样式
重构样式以遵循设计系统
修复样式不一致问题
添加深色模式支持
组件主题化
将gluestack-ui组件复制到你的项目中

在使用任何组件之前，请务必在
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

适用场景： 初始项目设置、安装、配置、添加组件

涵盖内容：

使用官方CLI（

npx gluestack-ui@latest init

和

npx gluestack-ui@latest add --all

）

Expo和React Native CLI的项目初始化（Next.js支持需等待NativeWind v5 web版本）
依赖管理
配置文件（tailwind、metro、babel等）
GluestackUIProvider设置
添加单个组件
设置问题排查

调用时机： 在新项目或现有项目中设置gluestack-ui、通过CLI添加组件，或排查安装问题时

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

适用场景： 分步创建组件、模板、方案

涵盖内容：

组件创建流程
6个可直接使用的模板（简单型、变体型、复合型、表单型、交互型、加载型）
常见组件方案（资料卡片、徽章、搜索框、列表）
最佳实践检查清单
快速入门指南

调用时机： 从零创建新组件或需要组件模板时

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

适用场景： 组件使用、复合模式、图标、Provider设置

涵盖内容：

优先使用Gluestack组件而非React Native原生组件
组件props与className工具类的对比
复合组件模式（Input、Button、FormControl等）
图标使用层级
Provider设置

调用时机： 处理组件结构、props和组合时

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

适用场景： 颜色、间距、深色模式、变体、className

涵盖内容：

语义化颜色令牌
遵循间距刻度
使用CSS变量实现深色模式
基于tva的变体样式
className合并

调用时机： 组件样式设计、主题化，或处理颜色和间距时

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

适用场景： 为组件创建自定义变体、扩展设计系统

涵盖内容：

创建变体的时机与方法
使用tva管理变体
扩展现有Gluestack组件
父子组件变体关系
用于复杂组合的复合变体
常见变体模式（徽章、提示框、卡片）
将重复样式转换为变体

调用时机： 需要为组件创建自定义变体、扩展组件样式选项，或标准化重复样式模式时

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

适用场景： 跨平台、性能优化、最佳实践

涵盖内容：

跨平台渲染（原生端与Web端）
TypeScript使用
组件 memoization
使用Reanimated实现动画
安全区域处理
使用FlatList实现列表
平台专属代码

调用时机： 优化性能、确保跨平台兼容性，或遵循React Native最佳实践时

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)

优先级层级（按优先顺序）

Component props - Use built-in props (size, variant, space)
className utilities - Use existing Tailwind/NativeWind classes
Gluestack component variants - Use built-in component variants
CSS variables (
@theme inline
) - Tailwind v4 auto-resolves tokens from
```
global.css
```
into utility classes
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

组件props - 使用内置props（size、variant、space）
className工具类 - 使用现有Tailwind/NativeWind类
Gluestack组件变体 - 使用内置组件变体
CSS变量（
@theme inline
） - Tailwind v4会自动将
```
global.css
```
中的令牌解析为工具类
tva（Tailwind Variant Authority） - 创建可复用的变体模式
NativeWind互操作 - 为第三方组件启用className
内联样式 - 仅作为最后的绝对手段，并需附上文档说明理由

Common Patterns

常见模式

tsx

// 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>

tsx

// 结合props使用组件
<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>

// 带图标的输入框（InputIcon必须放在InputSlot内）
<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

始终使用Gluestack组件而非React Native原生组件
优先使用组件props（space、size、variant）而非className
关键规则：仅使用语义化颜色令牌 - 绝不能使用
```
typography-*
```
、
```
neutral-*
```
、
```
gray-*
```
、
```
slate-*
```
或带编号的颜色（
```
red-500
```
、
```
blue-600
```
）。仅可使用语义化令牌：
```
text-foreground
```
、
```
text-muted-foreground
```
、
```
bg-primary
```
、
```
bg-card
```
、
```
border-border
```
等，可选择性添加透明度值（
```
/70
```
、
```
/90
```
）
禁止使用内联样式，除非绝对必要
遵循间距刻度（0、0.5、1、2、3、4等）- 禁止使用任意值
必须使用复合组件 - ButtonText、InputSlot、FormControlLabel等
InputIcon必须包裹在InputSlot内 - 这一点至关重要
创建带多样式的自定义组件时，使用tva管理变体
使用dark:前缀实现深色模式 - 基于CSS变量
确保跨平台兼容 - 使用Gluestack封装组件，而非直接导入React Native组件

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}
```

重要提示：使用组件前，请务必在官方v5文档中验证组件用法和模式。

组件文档：

https://gluestack.io/ui/docs/components/${componentName}/

完整文档：https://gluestack.io/ui/docs
导入路径：
```
@/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.

处理特定任务时，调用对应的子技能获取详细指导：

设置gluestack-ui或添加组件？ → 使用
```
gluestack-ui-v5:setup
```
创建新组件？ → 使用
```
gluestack-ui-v5:creating-components
```
有组件结构相关问题？** → 使用
```
gluestack-ui-v5:components
```
样式和主题相关问题？ → 使用
```
gluestack-ui-v5:styling
```
创建或扩展组件变体？ → 使用
```
gluestack-ui-v5:variants
```
性能或跨平台相关问题？ → 使用
```
gluestack-ui-v5:performance
```
需要验证或审查代码？ → 使用
```
gluestack-ui-v5:validation
```

每个子技能都会在其特定领域提供聚焦、详细的指导，同时保持与这些核心原则的一致性。