gluestack-ui-v4

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Gluestack UI v4 Design Patterns

Gluestack UI v4 设计规范

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.

本技能为gluestack-ui v4强制执行受限的、约定式的样式规范，可减少决策疲劳、提升性能、实现一致的主题化，并将解决方案限定为标准模式。

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
仅使用语义化Token——无例外 - 绝不要使用通用Token（
```
typography-*
```
、
```
neutral-*
```
、
```
gray-*
```
）或带编号的颜色（
```
red-500
```
、
```
blue-600
```
）。仅使用语义化Token（
```
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://v4.gluestack.io/ui/docs/components/${componentName}/

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

在使用任何组件之前，请务必访问
https://v4.gluestack.io/ui/docs/components/${componentName}/
验证最新的使用模式

Sub-Skills Organization

子技能架构

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

本技能被划分为多个专项子技能，以提升Token使用效率：

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

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

涵盖内容：

使用官方CLI（

npx gluestack-ui@alpha init -y

和

npx gluestack-ui@alpha add --all -y

）

Expo、React Native CLI和Next.js的项目初始化
依赖管理
配置文件（tailwind、metro、babel等）
GluestackUIProvider的设置
添加单个组件
搭建问题排查

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

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

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

涵盖内容：

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

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

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

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

涵盖内容：

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

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

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

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

涵盖内容：

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

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

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

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

涵盖内容：

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

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

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

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

涵盖内容：

跨平台渲染（原生与Web）
TypeScript的使用
组件 memoization（记忆化）
使用Reanimated实现动画
安全区域处理
使用FlatList实现列表
平台特定代码

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

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

组件props - 使用内置props（size、variant、space）
className工具类 - 使用现有Tailwind/NativeWind类
Gluestack组件变体 - 使用内置组件变体
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

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

始终使用Gluestack组件 而非React Native原生组件
优先使用组件props（space、size、variant）而非className
重点规则：仅使用语义化颜色Token - 绝不要使用
```
typography-*
```
、
```
neutral-*
```
、
```
gray-*
```
、
```
slate-*
```
或带编号的颜色（
```
red-500
```
、
```
blue-600
```
）。仅使用语义化Token：
```
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 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}
```

重要提示：在使用组件之前，请务必查阅官方v4文档以验证组件的使用方式和模式。

组件文档：

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

完整文档：https://v4.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-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.

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

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

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