# Atomic Design

> Atomic Design quick reference — levels, composition rules, tokens, naming

- **Type:** Skill
- **Install:** `agentstack add skill-sarveshsea-design-skills-atomic-design`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [sarveshsea](https://agentstack.voostack.com/s/sarveshsea)
- **Installs:** 0
- **Category:** [Content & Media](https://agentstack.voostack.com/c/content-and-media)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [sarveshsea](https://github.com/sarveshsea)
- **Source:** https://github.com/sarveshsea/design-skills/tree/main/skills/atomic-design
- **Website:** https://www.memoire.cv/notes/community/

## Install

```sh
agentstack add skill-sarveshsea-design-skills-atomic-design
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# Atomic Design — Quick Reference

## Level Decision Table

| Level | Folder | Composes | Has State | Fetches Data | Real Content |
|-------|--------|----------|-----------|--------------|-------------|
| Atom | `components/ui/` | Nothing | No | No | No |
| Molecule | `components/molecules/` | 2–5 atoms | Maybe | No | No |
| Organism | `components/organisms/` | Molecules + atoms | Yes | Yes | No |
| Template | `components/templates/` | Organisms | No | No | Placeholder |
| Page | (route file) | Templates | No | Yes | Real |

**If you can't decide:** IF it composes nothing → atom. IF it composes ≤5 atoms → molecule. IF it manages state or fetches data → organism. IF it's a full layout skeleton → template.

## Composition Rules

- Atoms: no `composesSpecs`, no imports of other atoms
- Molecules: 2–5 atom imports, no data fetching, may have internal open/closed state
- Organisms: own breakpoints, document composition in spec
- Templates: CSS Grid or Flexbox only, must match Figma page spec
- Pages: handle all data states — loading, empty, error, populated

## File Structure

```
components/
  ui/            # atoms (shadcn primitives)
  molecules/
  organisms/
  templates/
```

## Design Tokens

```
Global tokens  (--blue-500, --space-4)
  → Alias tokens  (--color-primary, --spacing-component)
    → Component tokens  (--button-bg, --card-radius)
```

Override alias tokens per theme: `:root`, `.dark`, `.brand-b`.

## Accessibility by Level

| Level | Required |
|-------|---------|
| Atom | ARIA role, keyboard focus, contrast, label |
| Molecule | Focus management, error announcements |
| Organism | Landmark roles, skip links, focus trapping |
| Template | Page title, heading hierarchy, main landmark |
| Page | Full WCAG 2.1 AA |

## Naming

| Element | Convention | Example |
|---------|-----------|---------|
| Components | PascalCase | `MetricCard` |
| Props | camelCase | `isLoading` |
| CSS classes | kebab-case | `text-muted-foreground` |
| Constants | UPPER_SNAKE | `MAX_RETRY_COUNT` |
| Tokens | path/style | `color/primary/500` |

## Figma ↔ Code

| Figma | Code |
|-------|------|
| Component | React component |
| Component Set | Variant type union |
| Component Property | React prop |
| Auto Layout | Flexbox / Grid |
| Design Token | CSS Variable → Tailwind class |
| Section | Organism |

## Anti-Patterns

1. **Premature abstraction** — wait for 3+ use cases before extracting
2. **Prop explosion** — 15+ props → decompose into smaller pieces
3. **CSS override chains** — 5+ overrides → create a variant
4. **Token drift** — hardcoded values that should be tokens
5. **Missing states** — every interactive component needs: default, hover, focus, active, disabled, loading, error

## Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [sarveshsea](https://github.com/sarveshsea)
- **Source:** [sarveshsea/design-skills](https://github.com/sarveshsea/design-skills)
- **License:** MIT
- **Homepage:** https://www.memoire.cv/notes/community/

Install and usage instructions live in the source repository linked above.

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** no
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** no
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/skill-sarveshsea-design-skills-atomic-design
- Seller: https://agentstack.voostack.com/s/sarveshsea
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.