gluestack-ui-v4

Gluestack UI v4 设计模式

此技能为 gluestack-ui v4 规定了约束性强、立场明确的样式模式，可减少决策疲劳、提升性能、实现一致的主题设置，并将解决方案限定在规范模式的范围内。

核心原则

1. 优先使用 Gluestack 组件，而非 React Native 原生组件——Gluestack 为 RN 封装了主题设置、无障碍功能和跨平台一致性
2. 优先使用组件 props，而非 className 工具类——有内置 props（size、variant、space）可用时，不要使用 className
3. 只使用语义化 token——绝无例外——绝不使用通用 token（typography-*、neutral-*、gray-*）或带编号的颜色（red-500、blue-600）。只使用语义化 token（text-foreground、bg-primary、border-border 等），可选用 alpha 值
4. 优先使用 className，而非内联样式——内联样式会绕过优化，破坏一致性
5. 优先使用间距比例，而非像素值——任意值会造成难以维护的例外
6. 复制粘贴理念——组件会被复制到你的代码库中，而非作为依赖项安装
7. 组合式子组件——使用复合组件模式以增强灵活性
8. 移除无用代码——未使用的模式会误导 AI 并增加认知负担

何时使用此技能

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

使用任何组件前，务必先在 https://v4.gluestack.io/ui/docs/components/${componentName}/ 查看最新用法模式

子技能组织结构

此技能分为多个专用子技能，以提高 token 使用效率：

1. gluestack-ui-v4:setup

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

涵盖：

• 使用官方 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

适用于： 分步创建组件、模板、配方

涵盖：

• 组件创建工作流
• 6 个可直接使用的模板（simple、variants、compound、form、interactive、loading）
• 常见组件配方（个人资料卡片、徽章、搜索、列表）
• 最佳实践检查清单
• 快速入门指南

在以下情况下调用： 从头创建新组件或需要组件模板

3. gluestack-ui-v4:components

适用于： 组件用法、复合模式、图标、Provider 设置

涵盖：

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

在以下情况下调用： 处理组件结构、props 和组合方式

4. gluestack-ui-v4:styling

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

涵盖：

• 语义化颜色 token
• 遵循间距比例
• 使用 CSS 变量实现深色模式
• 使用 tva 进行基于变体的样式设置
• className 合并

在以下情况下调用： 为组件设置样式或主题，或处理颜色和间距

5. gluestack-ui-v4:variants

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

涵盖：

• 何时以及如何创建变体
• 使用 tva 管理变体
• 扩展现有 Gluestack 组件
• 父子变体关系
• 用于复杂组合的复合变体
• 常见变体模式（徽章、警告、卡片）
• 将重复样式转换为变体

在以下情况下调用： 需要为组件创建自定义变体、扩展组件样式选项，或统一重复样式模式时

6. gluestack-ui-v4:performance

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

涵盖：

• 跨平台渲染（Native 和 Web）
• TypeScript 用法
• 组件记忆化
• 使用 Reanimated 制作动画
• 安全区域处理
• 在列表中使用 FlatList
• 平台专属代码

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

7. gluestack-ui-v4:validation

适用于： 代码审查、反模式、验证清单

涵盖：

• 完整的验证清单
• 应避免的反模式
• 常见错误
• 升级处理指南

在以下情况下调用： 审查代码、验证实现，或检查反模式时

快速参考

解析优先级（按优先顺序）

1. 组件 props - 使用内置 props（size、variant、space）
2. className 工具类 - 使用现有的 Tailwind/NativeWind 类
3. Gluestack 组件变体 - 使用内置组件变体
4. tva（Tailwind Variant Authority） - 创建可复用的变体模式
5. NativeWind 互操作 - 为第三方组件启用 className
6. 内联样式 - 仅在绝对必要时使用，并说明理由

常见模式

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

核心规则摘要

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

参考文档

重要：使用组件前，务必查阅官方 v4 文档，确认组件用法和模式。

• 组件文档：https://v4.gluestack.io/ui/docs/components/${componentName}/
• 完整文档：https://v4.gluestack.io/ui/docs
• 导入路径：@/components/ui/${componentName}

如何使用子技能

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

• 设置 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

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