mcpField
G
gluestack-ui-v5

gluestack-ui-v5

github.com/gluestack设计与 UI11.4k 次安装17 周前更新
代码仓库

关于 gluestack-ui-v5

gluestack-ui-v5 是用于构建和审查 gluestack-ui v5 界面的设计模式技能，适合相关项目开发者。它提供设置、组件、样式、变体、性能和验证指导，涵盖 NativeWind v5 与 UniWind。

主要功能

  1. 01指导项目设置与组件创建
  2. 02优先使用组件属性和复合模式
  3. 03强制使用语义颜色令牌
  4. 04遵循间距与暗色模式规范
  5. 05检查跨平台性能与代码

适用场景

  1. 01在项目中设置 gluestack-ui
  2. 02创建或重构 UI 组件
  3. 03检查样式是否符合设计系统
  4. 04添加主题与暗色模式支持

安装

复制下面的命令，在终端中运行。

$npx skills add https://github.com/gluestack/agent-skills --skill gluestack-ui-v5

安装后在 Claude Code 中输入/gluestack-ui-v5确认已加载。

详细介绍

Gluestack UI v5 设计模式

此技能为 gluestack-ui v5（采用 CSS 优先配置的 Tailwind CSS v4）强制执行受限且明确的样式模式，以减少决策负担、提升性能、实现一致的主题设置，并将解决方案限制在规范模式范围内。支持 NativeWind v5（Expo + RN CLI）和 UniWind（仅限 Expo）样式引擎。

核心原则

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

何时使用此技能

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

使用任何组件前，务必在 https://gluestack.io/ui/docs/components/${componentName}/ 确认最新的使用模式

子技能组织方式

此技能按用途拆分为专门的子技能，以更高效地使用令牌：

1. gluestack-ui-v5:setup

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

涵盖内容：

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

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

涵盖内容：

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

适用于： 从头创建新组件，或需要组件模板时

3. gluestack-ui-v5:components

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

涵盖内容：

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

适用于： 处理组件结构、props 和组合时

4. gluestack-ui-v5:styling

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

涵盖内容：

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

适用于： 为组件设置样式、配置主题，或处理颜色和间距时

5. gluestack-ui-v5:variants

用途： 为组件创建自定义变体，扩展设计系统

涵盖：

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

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

6. gluestack-ui-v5:performance

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

涵盖：

  • 跨平台渲染（Native 和 Web）
  • TypeScript 的使用
  • 组件记忆化
  • 使用 Reanimated 创建动画
  • 安全区域处理
  • 使用 FlatList 呈现列表
  • 平台专属代码

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

7. gluestack-ui-v5:validation

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

涵盖：

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

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

快速参考

解析层级（按优先顺序）
  1. 组件属性 - 使用内置属性（size、variant、space）
  2. className 工具类 - 使用现有的 Tailwind/NativeWind 类
  3. Gluestack 组件变体 - 使用内置组件变体
  4. CSS 变量（@theme inline） - Tailwind v4 会自动将 global.css 中的令牌解析为工具类
  5. tva（Tailwind Variant Authority） - 创建可复用的变体模式
  6. NativeWind 互操作 - 为第三方组件启用 className
  7. 内联样式 - 仅在绝对必要时使用，并提供有据可查的理由
常见模式
// 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. 优先使用组件属性（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 模块

参考文档

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

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

如何使用子技能

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

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

每个子技能都会针对其特定领域提供重点明确的详细指导，同时遵循这些核心原则。

评论

支持 Markdown