---
name: atomic-design-gluestack
description: "Enforces atomic design…"
---

# Atomic Design with Gluestack UI

## Overview

This skill enforces Brad Frost's atomic design methodology adapted for React Native/Expo projects using Gluestack UI v3 + NativeWind v4. It provides clear guidelines for component categorization, directory structure, composition patterns, and testing strategies for each atomic level.

## Sealed Design System Guard

Before applying this skill, check whether the target project has a sealed or closed design system. Common markers include `.claude/rules/use-the-design-library.md`, `.claude/rules/figma-design-system.md`, design-system ESLint rules, or a project-owned `@/components/atoms` barrel paired with design-system docs/configuration.

If a sealed design system is present, defer to the project's design-library rules and skills instead, such as `use-the-design-library` and `add-design-library-item`. Keep the atomic hierarchy concepts only when they match the local seal. Do not redefine the atom library as `@/components/ui`, use Gluestack compound trees as canonical atoms, or recommend `className` and raw Gluestack tokens where the project seal forbids them.

For open Gluestack UI v3 + NativeWind v4 projects without those seal markers, continue with the guidance below.

## Core Principles

### The Atomic Hierarchy

Components are organized into five levels, from simplest to most complex:

| Level | Definition | State | Examples |
|-------|------------|-------|----------|
| **Atoms** | Foundational building blocks that cannot be broken down further while remaining functional | Stateless (purely presentational) | Button, Text, Icon, Input, Badge |
| **Molecules** | Simple groups of UI elements functioning together as a unit | Isolated state (form validation, toggles) | SearchField, FormField, AvatarWithName |
| **Organisms** | Complex components composed of molecules and atoms forming distinct interface sections | Feature state, coordinates children | Header, ProductCard, NavigationDrawer |
| **Templates** | Page-level layouts that place components into a structure (skeleton without real content) | Layout state only | MainLayout, AuthLayout, DashboardLayout |
| **Pages** | Specific instances of templates with real content and data | Connected to global state | HomeScreen, ProfileScreen, SettingsScreen |

### Design Tokens Foundation

Design tokens sit **below atoms** as the foundational layer. In this project, tokens are defined in:
- `components/ui/gluestack-ui-provider/config.ts` - Color tokens (primary, secondary, error, success, etc.)
- `tailwind.config.js` - Spacing, typography, and other design tokens via NativeWind

## Directory Structure

### Required Structure

```
components/
├── ui/                          # Gluestack UI library components (DO NOT MODIFY unless extending)
├── atoms/                       # Project-specific atoms
│   ├── AppIcon/
│   │   ├── index.tsx
│   │   ├── AppIcon.test.tsx
│   │   └── types.ts
│   └── index.ts                 # Barrel export for atoms
├── molecules/                   # Composite simple components
│   ├── SearchField/
│   │   ├── index.tsx
│   │   ├── SearchFieldView.tsx
│   │   ├── SearchField.test.tsx
│   │   └── types.ts
│   └── index.ts
├── organisms/                   # Complex feature components
│   ├── Header/
│   │   ├── index.tsx
│   │   ├── HeaderView.tsx
│   │   ├── Header.test.tsx
│   │   └── types.ts
│   └── index.ts
└── templates/                   # Page layouts
    ├── MainLayout/
    │   ├── index.tsx
    │   ├── MainLayoutView.tsx
    │   └── types.ts
    └── index.ts

features/
└── [feature-name]/
    ├── components/              # Feature-specific components (follow atomic naming)
    │   ├── atoms/
    │   ├── molecules/
    │   └── organisms/
    └── screens/                 # Pages (specific to this feature)

app/                             # Expo Router pages (connect templates with data)
```

### Gluestack UI Components Location

The 40+ Gluestack UI components in `components/ui/` serve as the **foundation atom library**. When building custom components:

1. **Use Gluestack components as atoms** - Import from `@/components/ui/`
2. **Extend when needed** - Create project-specific atoms in `components/atoms/`
3. **Never modify `components/ui/`** - Except for theme customization in `config.ts`

## Component Classification Rules

### Rule 1: Atoms (Building Blocks)

**Definition**: Smallest functional UI elements that cannot be broken down further.

**Characteristics**:
- Stateless and purely presentational
- Accept props for customization
- No business logic
- Highly reusable across the entire app

**Gluestack Atoms** (use directly from `@/components/ui/`):
- Box, Center, HStack, VStack, ScrollView
- Text, Heading
- Button, ButtonText, ButtonIcon
- Input, InputField, InputSlot
- Icon, Image, Avatar
- Badge, Divider, Spinner

**When to create custom atoms**:
- Project-specific iconography
- Branded text variants
- Wrapper components with default styling

```typescript
/**
 * AppLogo atom - Branded logo component
 * @description Displays the application logo with consistent sizing
 */
const AppLogo = memo(function AppLogo({ size = "md" }: AppLogoProps) {
  return (
    <Image
      source={logoSource}
      className={logoSizes[size]}
      alt="App Logo"
    />
  );
});
```

### Rule 2: Molecules (Simple Compositions)

**Definition**: Simple groups of atoms functioning together as a unit.

**Characteristics**:
- Combines 2-5 atoms
- Single responsibility (does one thing well)
- May have isolated UI state (toggle, validation)
- No external data fetching

**Examples**:
```typescript
/**
 * SearchField molecule - Search input with button
 * @description Combines Input and Button atoms for search functionality
 */
const SearchField = memo(function SearchField({
  onSearch,
  placeholder
}: SearchFieldProps) {
  const [value, setValue] = useState("");

  return (
    <HStack space="sm" className="items-center">
      <Input className="flex-1">
        <InputField
          value={value}
          onChangeText={setValue}
          placeholder={placeholder}
        />
      </Input>
      <Button onPress={() => onSearch(value)}>
        <ButtonIcon as={SearchIcon} />
      </Button>
    </HStack>
  );
});
```

**Molecule Checklist**:
- [ ] Uses only atoms (Gluestack or custom)
- [ ] Has a single, clear purpose
- [ ] State is UI-only (no business logic)
- [ ] Reusable in multiple contexts

### Rule 3: Organisms (Complex Sections)

**Definition**: Relatively complex components forming distinct interface sections.

**Characteristics**:
- Combines molecules and atoms
- May have feature-specific state
- Can coordinate child component behavior
- Represents a standalone section of UI

**Examples**:
```typescript
/**
 * ProductCard organism - Complete product display
 * @description Displays product information with actions
 */
const ProductCard = memo(function ProductCard({
  product,
  onAddToCart
}: ProductCardProps) {
  return (
    <Card variant="elevated" size="md">
      <ProductImage source={product.image} />      {/* Atom */}
      <VStack space="sm" className="p-4">
        <Heading size="md">{product.name}</Heading> {/* Atom */}
        <PriceDisplay price={product.price} />      {/* Molecule */}
        <RatingStars rating={product.rating} />     {/* Molecule */}
        <AddToCartButton onPress={onAddToCart} />   {/* Molecule */}
      </VStack>
    </Card>
  );
});
```

**Organism Checklist**:
- [ ] Forms a distinct interface section
- [ ] Combines molecules and/or atoms
- [ ] Has clear boundaries
- [ ] May receive data as props (but doesn't fetch)

### Rule 4: Templates (Page Layouts)

**Definition**: Page-level layouts that place components into a structure.

**Characteristics**:
- Defines layout skeleton with slots
- No real content (uses placeholder or children)
- Handles responsive behavior
- Manages layout-specific state only

**Example**:
```typescript
/**
 * MainLayout template - Primary app layout
 * @description Provides consistent header, content, and footer structure
 */
const MainLayout = memo(function MainLayout({
  children,
  showHeader = true,
  showFooter = true
}: MainLayoutProps) {
  return (
    <SafeAreaView className="flex-1 bg-background-0">
      {showHeader && <Header />}
      <ScrollView className="flex-1">
        {children}
      </ScrollView>
      {showFooter && <Footer />}
    </SafeAreaView>
  );
});
```

### Rule 5: Pages (Screens)

**Definition**: Specific instances of templates with real content and data.

**Characteristics**:
- Connects to global state (Apollo, Context)
- Handles data fetching
- Passes data to organisms/molecules
- Lives in `app/` (Expo Router) or `features/*/screens/`

**Example**:
```typescript
/**
 * HomeScreen page - Main home page
 * @description Renders home content with fetched data
 */
export default function HomeScreen() {
  const { data, loading } = useHomeDataQuery();

  return (
    <MainLayout>
      {loading ? (
        <LoadingSpinner />
      ) : (
        <VStack space="lg">
          <FeaturedProducts products={data.featured} />
          <RecentActivity items={data.activity} />
        </VStack>
      )}
    </MainLayout>
  );
}
```

## Validation Rules

### Enforcement Checklist

When creating or reviewing components, verify:

1. **Correct Directory Placement**
   - Atoms in `components/atoms/` or `features/*/components/atoms/`
   - Molecules in `components/molecules/` or `features/*/components/molecules/`
   - Organisms in `components/organisms/` or `features/*/components/organisms/`
   - Templates in `components/templates/`
   - Pages in `app/` or `features/*/screens/`

2. **State Appropriateness**
   - Atoms: No state
   - Molecules: UI state only (useState for toggles, form values)
   - Organisms: Feature state, may use custom hooks
   - Templates: Layout state only
   - Pages: Connected to global state, data fetching

3. **Import Direction** (dependencies flow upward only)
   ```
   Pages → Templates → Organisms → Molecules → Atoms → Design Tokens
   ```
   - Atoms MUST NOT import from molecules, organisms, templates, or pages
   - Molecules MUST NOT import from organisms, templates, or pages
   - Organisms MUST NOT import from templates or pages

4. **Composition Appropriateness**
   - Molecules combine 2-5 atoms
   - Organisms can be complex but should represent a single interface section
   - If an organism becomes too large, extract sub-organisms

### Common Mistakes to Avoid

| Mistake | Problem | Solution |
|---------|---------|----------|
| Atom with useState | Atoms should be stateless | Move state to parent molecule |
| Molecule fetching data | Data fetching belongs in pages | Accept data as props |
| Organism in atoms folder | Misclassification | Move to organisms folder |
| Template with business logic | Templates handle layout only | Move logic to page |
| Importing organism in atom | Wrong dependency direction | Restructure component hierarchy |
| Spacing refactor inside a bounded-height sheet/modal | Wrapping siblings in new flex containers (e.g. margin→gap conversion) changes overflow distribution and can push a sticky footer/header out of view — pixel-faithful at rest, broken once content overflows | Route the surface through the bounded-scroll pattern: `flex-1` + `min-h-0` scroll body with a `shrink-0` pinned footer, and verify in the content-overflow state, not just the default mount |

## Testing by Atomic Level

| Level | Test Type | Focus |
|-------|-----------|-------|
| Atoms | Unit + Snapshot | Props rendering, accessibility |
| Molecules | Unit + Interaction | Composition, isolated state |
| Organisms | Integration | Data flow, child coordination |
| Templates | Layout | Slot rendering, responsiveness |
| Pages | E2E | Full user flows |

## Quick Reference

### Decision Tree: Which Level?

```
Is it a single, indivisible UI element?
├─ YES → ATOM
└─ NO → Does it combine 2-5 atoms for a single purpose?
         ├─ YES → MOLECULE
         └─ NO → Does it form a distinct interface section?
                  ├─ YES → ORGANISM
                  └─ NO → Is it a layout skeleton?
                           ├─ YES → TEMPLATE
                           └─ NO → PAGE
```

### Gluestack Component Level Map

Reference `references/gluestack-mapping.md` for the complete mapping of all 40 Gluestack UI components to their atomic levels.

## Resources

### references/
- `atomic-levels.md` - Detailed definitions with comprehensive examples
- `gluestack-mapping.md` - Complete Gluestack UI component classification
- `folder-structure.md` - Detailed directory structure requirements

### scripts/
- `validate_atomic_structure.py` - Validates component placement and imports
