---
description: Enforce Atomic Design for components in components/ with common/scoped layers
alwaysApply: true
---

# Atomic Design Pattern

Use **Atomic Design** for all UI components in `components/`, plus a dedicated wrappers layer for third-party/UI wrappers:

- **Atoms** (`components/atoms/`): Smallest UI building blocks (Button, Icon, Heading, Input primitives).
- **Molecules** (`components/molecules/`): Small compositions of atoms with two buckets:
  - `components/molecules/common/`: Generic molecules reusable across multiple features.
  - `components/molecules/scoped/<feature>/`: Feature-specific molecules used only in that feature.
- **Organisms** (`components/organisms/`): Full sections/feature blocks composed of molecules + atoms with two buckets:
  - `components/organisms/common/`: Generic organisms reusable across multiple features.
  - `components/organisms/scoped/<feature>/`: Feature-specific organisms used only in that feature.
- **Templates** (`components/templates/`): Page-level layouts and composition shells (layout wrappers, section composition patterns).
- **Wrappers** (`components/wrappers/`): Technical wrapper components around React Native or third-party primitives (e.g., `FlashList` wrapper), focused on behavior/adaptation rather than product UI composition.

## Placement checklist (decide the layer)

- **Atom**: single responsibility, minimal/no layout, reusable across many contexts.
- **Molecule**: 2–5 atoms working together to solve one UI task.
- **Organism**: a distinct section of a page; often has layout, multiple molecules, and richer composition.
- **Template**: page framing + layout; should not contain hardcoded business content.
- **Wrapper**: abstraction/adaptation around base components (library or platform), usually to centralize defaults, loading/empty/error handling, or shared wiring.

If unsure, start **lower** (atom/molecule). Promote upward only when composition becomes clearly reusable at that level.
If the component's main purpose is adapting/wrapping a base component API (not building product UI hierarchy), place it in `wrappers`.

## Component folder conventions

Each component lives in its own folder:

```
components/<layer>/<scope>/<ComponentName>/
  index.tsx
  types.ts
  styles.ts
```

Where:
- Atoms/templates typically do not require an extra scope folder:
  - `components/atoms/<ComponentName>/`
  - `components/templates/<ComponentName>/`
- Wrappers live under:
  - `components/wrappers/<WrapperName>/`
- Molecules/organisms must be under `common` or `scoped/<feature>`:
  - `components/molecules/common/<ComponentName>/`
  - `components/molecules/scoped/<feature>/<ComponentName>/`
  - `components/organisms/common/<ComponentName>/`
  - `components/organisms/scoped/<feature>/<ComponentName>/`

Example:
- `NotificationBell` is a scoped molecule in the `notification` feature:
  - `components/molecules/scoped/notification/NotificationBell/`
- `FlashList` wrapper component:
  - `components/wrappers/flashlist/`

- **Naming**: PascalCase for folders/files/components (`HeroBanner`, `UserAvatarWithMenu`).
- **Styles**: prefer `styles.ts` colocated with the component.
- **Types**: put public props in `types.ts` and export a `ComponentNameProps` type.

## Imports and boundaries

- **Allowed dependencies**:
  - Atoms can import other atoms and shared utils/styles, but avoid depending on higher layers.
  - Wrappers can import shared utils/styles and lower-level UI primitives/libraries they wrap. Keep wrappers generic and avoid feature/business-specific dependencies.
  - Molecules can import atoms (and other molecules if truly necessary). Scoped molecules should prefer scoped dependencies within the same feature and shared dependencies from `common`.
  - Organisms can import molecules and atoms. Scoped organisms should prefer scoped dependencies within the same feature and shared dependencies from `common`.
  - Templates can import organisms/molecules/atoms/wrappers.
- **Avoid circular dependencies** across layers.
- **Scope rule**:
  - Put components in `common` only if they are genuinely reused in multiple features.
  - Keep feature-only components inside `scoped/<feature>/` and avoid importing them from unrelated features.
- **Prefer composition** over adding boolean props that create many variants; split into smaller atoms/molecules when variants grow.

## When refactoring

- If an atom grows layout/section responsibility → move it up to a molecule/organism.
- If an organism contains reusable sub-parts → extract those to molecules/atoms.
- Keep the API surface minimal: fewer props, more composable children/slots when appropriate.