Agent Skills: Building Beautiful Expo Apps with Gluestack UI

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.

1. Technology Stack & Environment

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

2. Project Initialization Skills

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

A. Create Expo Project

Use the latest Expo template:

bash

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

B. Install 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>
  );
}

3. Component Management Skills

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

A. Adding Components

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]
# 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.

B. Common Components & Usage

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
```
.

4. UI/UX Design & Styling Skills

A. Theming & Tokens

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
```
).

B. Responsive Design

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

C. "Beautiful" UI Principles

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).

5. Advanced Development Patterns

A. State Management

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.

B. Form Handling

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

C. Iconography

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

D. Navigation (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.

6. Coding Best Practices for Agents

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.

7. Workflow Checklist

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.

8. External Agent Skills & Resources

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

A. React Native Best Practices (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.

B. Expo Official Skills

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

NPX Install

Tags

SKILL.md Content