expo-gluestack

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Agent Skills: Building Beautiful Expo Apps with Gluestack UI

Agent技能：使用Gluestack UI构建精美Expo应用

This document defines the skill set and operational guidelines for AI agents working on this project. The primary goal is to build high-quality, visually appealing mobile applications using Expo and gluestack-ui.

本文档定义了从事该项目的AI Agent所需的技能集和操作准则，核心目标是使用Expo和gluestack-ui构建高质量、视觉吸引力强的移动应用。

1. Technology Stack & Environment

1. 技术栈与环境

Framework: React Native (via Expo)
UI Library: gluestack-ui
Language: TypeScript (Preferred)
Navigation: Expo Router (Standard for modern Expo apps)

框架：React Native（通过Expo）
UI库：gluestack-ui
编程语言：TypeScript（优先选择）
导航：Expo Router（现代Expo应用的标准方案）

2. Project Initialization Skills

2. 项目初始化技能

When starting a new project or setting up the environment, the agent must follow these steps:

在启动新项目或配置环境时，Agent必须遵循以下步骤：

A. Create Expo Project

A. 创建Expo项目

Use the latest Expo template:

bash

npx create-expo-app@latest my-app --template default
cd my-app

使用最新的Expo模板：

bash

npx create-expo-app@latest my-app --template default
cd my-app

B. Install gluestack-ui

B. 安装gluestack-ui

Follow the official installation guide to integrate gluestack-ui:

Initialize gluestack-ui:
bash
```
npx gluestack-ui init
```
- This command installs dependencies and adds the
```
GluestackUIProvider
```
  .
- It sets up the theme configuration.
- It creates a
```
components
```
  folder for your UI components.

Wrap Application Root: Ensure the root layout (e.g.,

app/_layout.tsx

App.tsx

) is wrapped with the provider:

tsx

import { GluestackUIProvider } from "@/components/ui/gluestack-ui-provider";
import "@/global.css"; // If using NativeWind or global styles

export default function Layout() {
  return (
    <GluestackUIProvider>
      <Slot /> {/* or your main app content */}
    </GluestackUIProvider>
  );
}

遵循官方安装指南集成gluestack-ui：

初始化gluestack-ui：
bash
```
npx gluestack-ui init
```
- 该命令会安装依赖并添加
```
GluestackUIProvider
```
  。
- 它会配置主题设置。
- 它会创建一个用于存放UI组件的
```
components
```
  文件夹。

包裹应用根节点：确保根布局（例如

app/_layout.tsx

或

App.tsx

）被Provider包裹：

tsx

import { GluestackUIProvider } from "@/components/ui/gluestack-ui-provider";
import "@/global.css"; // 如果使用NativeWind或全局样式

export default function Layout() {
  return (
    <GluestackUIProvider>
      <Slot /> {/* 或你的主应用内容 */}
    </GluestackUIProvider>
  );
}

3. Component Management Skills

3. 组件管理技能

gluestack-ui is unstyled by default and headless, meaning you add components as you need them.

gluestack-ui默认是无样式且无头的，意味着你可以按需添加组件。

A. Adding Components

A. 添加组件

NEVER try to import a component that hasn't been added to the project. Always check the

components/ui

directory first.

To add a new component (e.g., Button, Box, Text):

bash

npx gluestack-ui add [component-name]

绝对不要尝试导入尚未添加到项目中的组件。请先检查

components/ui

目录。

要添加新组件（例如Button、Box、Text）：

bash

npx gluestack-ui add [component-name]

Example:

示例：

npx gluestack-ui add button box text

*Agent Note: If a user asks for a UI element, identify the corresponding gluestack component, run the add command if it's missing, and then implement it.*

npx gluestack-ui add button box text

*Agent注意事项：如果用户需要某个UI元素，请先确定对应的gluestack组件，若组件不存在则运行添加命令，然后再进行实现。*

B. Common Components & Usage

B. 常用组件及用法

Layout: Use

Box

VStack

HStack

Center

for layout instead of raw View styles.

tsx

<VStack space="md" reversed={false}>
  <Box className="w-20 h-20 bg-primary-500" />
</VStack>

Typography: Use
```
Text
```
and
```
Heading
```
with size props.
Interactivity: Use
```
Button
```
,
```
Pressable
```
,
```
Link
```
.

布局：使用

Box

、

VStack

、

HStack

、

Center

来实现布局，而非直接使用View样式。

tsx

<VStack space="md" reversed={false}>
  <Box className="w-20 h-20 bg-primary-500" />
</VStack>

排版：使用带有size属性的
```
Text
```
和
```
Heading
```
。
交互性：使用
```
Button
```
、
```
Pressable
```
、
```
Link
```
。

4. UI/UX Design & Styling Skills

4. UI/UX设计与样式技能

A. Theming & Tokens

A. 主题与令牌

Utilize the gluestack-ui tokens for spacing, colors, and typography to ensure consistency.
Avoid hardcoded pixel values for margins/padding; use tokens (e.g.,
```
$2
```
,
```
$4
```
,
```
md
```
,
```
lg
```
).

利用gluestack-ui的间距、颜色和排版令牌来确保设计一致性。
避免为边距/内边距使用硬编码的像素值；请使用令牌（例如
```
$2
```
、
```
$4
```
、
```
md
```
、
```
lg
```
）。

B. Responsive Design

B. 响应式设计

gluestack-ui supports responsive props.
Example:
```
<Box w="$full" md-w="$1/2">
```
(Full width on mobile, half width on medium screens/tablets).

gluestack-ui支持响应式属性。
示例：
```
<Box w="$full" md-w="$1/2">
```
（移动端为全屏，中等屏幕/平板为半屏）。

C. "Beautiful" UI Principles

C. "精美"UI设计原则

Whitespace: Use ample padding and margin (via
```
space
```
prop in stacks or padding props).
Hierarchy: Use font weights and colors to establish visual hierarchy.
Feedback: Ensure interactive elements have hover/pressed states (gluestack handles this by default, but customization is possible).

留白：使用充足的内边距和外边距（通过栈组件的
```
space
```
属性或内边距属性）。
层级：使用字体粗细和颜色建立视觉层级。
反馈：确保交互元素具备悬停/按压状态（gluestack默认已处理，但支持自定义）。

5. Advanced Development Patterns

5. 高级开发模式

A. State Management

A. 状态管理

Global State: Use Zustand for lightweight global state (e.g., user session, theme settings).
- Why: Minimal boilerplate, easy to use with hooks.
Server State: Use TanStack Query (React Query) for data fetching.
- Why: Handles caching, loading states, and refetching automatically.

全局状态：使用Zustand实现轻量全局状态（例如用户会话、主题设置）。
- 原因：样板代码极少，易于与Hooks配合使用。
服务端状态：使用**TanStack Query (React Query)**处理数据请求。
- 原因：自动处理缓存、加载状态和重新请求。

B. Form Handling

B. 表单处理

Use React Hook Form controlled by Zod schema validation.

Why: Performance (minimizes re-renders) and type safety.

tsx

import { useForm, Controller } from "react-hook-form";
import { zodResolver } from "@hookform/resolvers/zod";
// ... define z.object schema ...

使用由Zod schema验证控制的React Hook Form。

原因：性能优异（减少重渲染）且类型安全。

tsx

import { useForm, Controller } from "react-hook-form";
import { zodResolver } from "@hookform/resolvers/zod";
// ... 定义z.object schema ...

C. Iconography

C. 图标

Use Lucide Icons (
```
lucide-react-native
```
).

Gluestack-ui integrates well with Lucide.

tsx

import { Camera } from "lucide-react-native";
import { Icon } from "@/components/ui/icon";
// Usage: <Icon as={Camera} size="md" />

使用Lucide Icons（
```
lucide-react-native
```
）。

Gluestack-ui与Lucide集成良好。

tsx

import { Camera } from "lucide-react-native";
import { Icon } from "@/components/ui/icon";
// 使用方式：<Icon as={Camera} size="md" />

D. Navigation (Expo Router)

D. 导航（Expo Router）

Structure:
- ```
app/_layout.tsx
```
  : Root provider setup (gluestack, query client).
- ```
app/(tabs)
```
  : For tab-based navigation.
- ```
app/[id].tsx
```
  : For dynamic routes.
Linking: Use
```
Link
```
from
```
expo-router
```
for web-compatible navigation.

结构：
- ```
app/_layout.tsx
```
  ：根Provider配置（gluestack、query client）。
- ```
app/(tabs)
```
  ：用于基于标签页的导航。
- ```
app/[id].tsx
```
  ：用于动态路由。
链接：使用
```
expo-router
```
中的
```
Link
```
实现兼容Web的导航。

6. Coding Best Practices for Agents

6. Agent编码最佳实践

File Structure:
- Keep screens in
```
app/
```
  (if using Expo Router).
- Keep reusable UI components in
```
components/
```
  .
- Keep business logic/hooks in
```
hooks/
```
  or
```
utils/
```
  .
Code Style:
- Use functional components.
- Use Hooks (
```
useState
```
  ,
```
useEffect
```
  ) appropriately.
- Type Safety: strict TypeScript usage. Define interfaces for props.
Error Handling:
- When running commands (like
```
npx gluestack-ui add
```
  ), if they fail, analyze the error (e.g., missing peer dependencies) and fix it before proceeding.
Dependency Management:
- Expo Compatibility First: Always prioritize installing packages compatible with the latest Expo SDK.
- Use
```
npx expo install [package-name]
```
  instead of
```
npm install
```
  or
```
yarn add
```
  when possible, as this ensures the installed version is compatible with the project's Expo SDK version.

文件结构：
- 屏幕文件存放在
```
app/
```
  目录下（若使用Expo Router）。
- 可复用UI组件存放在
```
components/
```
  目录下。
- 业务逻辑/Hooks存放在
```
hooks/
```
  或
```
utils/
```
  目录下。
代码风格：
- 使用函数式组件。
- 合理使用Hooks（
```
useState
```
  、
```
useEffect
```
  ）。
- 类型安全：严格使用TypeScript，为Props定义接口。
错误处理：
- 运行命令（如
```
npx gluestack-ui add
```
  ）失败时，分析错误原因（例如缺少peer依赖）并在继续前修复问题。
依赖管理：
- 优先保证Expo兼容性：始终优先安装与最新Expo SDK兼容的包。
- 尽可能使用
```
npx expo install [package-name]
```
  而非
```
npm install
```
  或
```
yarn add
```
  ，因为这能确保安装的版本与项目的Expo SDK版本兼容。

7. Workflow Checklist

7. 工作流程检查清单

When assigned a task to build a screen:

Analyze requirements.
Identify necessary UI components (e.g., Card, Avatar, Button).
Check if components exist in
```
components/ui
```
; if not, run
```
npx gluestack-ui add ...
```
.
Scaffold the screen using
```
VStack
```
/
```
HStack
```
for layout.
Apply styling using theme tokens.
Verify responsiveness.

在接到构建屏幕的任务时：

分析需求。
确定所需的UI组件（例如Card、Avatar、Button）。
检查组件是否存在于
```
components/ui
```
目录；若不存在，则运行
```
npx gluestack-ui add ...
```
。
使用
```
VStack
```
/
```
HStack
```
搭建屏幕布局。
使用主题令牌设置样式。
验证响应式效果。

8. External Agent Skills & Resources

8. 外部Agent技能与资源

To enhance capability, the agent should leverage established skill sets from industry leaders:

为提升能力，Agent应借鉴行业领导者已确立的技能集：

A. React Native Best Practices (Callstack)

A. React Native最佳实践（Callstack）

Repository: callstackincubator/agent-skills
Focus: Performance optimization (re-renders, startup time), bundling, and native modules.
Instruction: Consult these skills when optimizing app performance or debugging complex native issues.

仓库地址：callstackincubator/agent-skills
重点：性能优化（重渲染、启动时间）、打包和原生模块。
使用说明：在优化应用性能或调试复杂原生问题时参考这些技能。

B. Expo Official Skills

B. Expo官方技能

Repository: expo/skills
Focus: Best practices for building, deploying (EAS), and upgrading Expo applications.
Instruction: Use these skills for:
- ```
upgrading-expo
```
  : When moving between Expo SDK versions.
- ```
expo-deployment
```
  : For setting up EAS Build and Submit.
- ```
expo-app-design
```
  : General Expo app architecture guidance.

仓库地址：expo/skills
重点：构建、部署（EAS）和升级Expo应用的最佳实践。
使用说明：以下场景可使用这些技能：
- ```
upgrading-expo
```
  ：在Expo SDK版本间升级时。
- ```
expo-deployment
```
  ：配置EAS Build和Submit时。
- ```
expo-app-design
```
  ：获取Expo应用架构的通用指导。