gluestack-ui-v4

用途

gluestack-ui-v4 是一个针对 gluestack-ui v4 的样式规范技能，目标是通过约束性、有明确倾向的样式模式，减少开发者在样式决策上的负担，提升性能，实现一致的主题化，并把解决方案空间限制在规范模式内。它适用于创建带样式的新组件、审查现有组件样式、按设计系统重构样式、修复样式不一致、添加暗色模式支持、主题化组件，以及从 gluestack-ui 复制组件到项目中。

核心原则

优先使用 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 并增加认知负担。

子技能组织

该技能按专门子技能组织，以提升 token 效率：

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-v4:creating-components：用于逐步创建组件、模板与配方。涵盖组件创建工作流、6 个即用模板（simple、variants、compound、form、interactive、loading）、常见组件配方（个人资料卡、徽章、搜索、列表）、最佳实践清单、快速入门指南。
gluestack-ui-v4:components：用于组件使用、复合模式、图标、provider 设置。涵盖使用 Gluestack 组件而非 React Native 原生组件、组件 props 与 className 工具类的取舍、复合组件模式（Input、Button、FormControl 等）、图标使用层级、provider 设置。
gluestack-ui-v4:styling：用于颜色、间距、暗色模式、变体、className。涵盖语义化颜色 token、间距刻度遵循、使用 CSS 变量的暗色模式、使用 tva 的基于变体的样式、className 合并。
gluestack-ui-v4:variants：用于为组件创建自定义变体、扩展设计系统。涵盖何时以及如何创建变体、使用 tva 管理变体、扩展现有 Gluestack 组件、父子变体关系、复杂组合的复合变体、常见变体模式（徽章、警告、卡片）、将重复样式转换为变体。
gluestack-ui-v4:performance：用于跨平台、性能优化、最佳实践。涵盖跨平台渲染（Native 与 Web）、TypeScript 使用、组件记忆化、使用 Reanimated 的动画、安全区域处理、列表使用 FlatList、平台特定代码。
gluestack-ui-v4:validation：用于代码审查、反模式、校验清单。涵盖完整校验清单、应避免的反模式、常见错误、升级指导。

使用方式

根据具体任务调用相应子技能：设置 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。

解析优先级（按偏好顺序）：组件 props → className 工具类 → Gluestack 组件变体 → tva（Tailwind Variant Authority）→ NativeWind 互操作 → 内联样式（仅作为最后手段并需记录理由）。

常见模式示例：

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

// 语义化颜色 token
<Box className="bg-primary text-primary-foreground">
  <Text className="text-foreground">Content</Text>
</Box>

关键规则

始终使用 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。

参考文档

使用组件前，务必在官方 v4 文档中核实组件用法与模式。

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

适用场景与限制

适用场景：在 React Native、Expo 或 Next.js 项目中使用 gluestack-ui v4 进行组件开发、样式编写、主题化、变体扩展、性能优化与代码审查。

限制：该技能为约束性样式规范，要求严格遵循语义化 token 与复合组件模式；具体安装命令、配置细节与组件用法需以官方 v4 文档为准。关于收费、价格、平台支持范围等未在资料中提供的信息，暂未提供。