swiftui-atomic-design

name

swiftui-atomic-design

description

Guide for building SwiftUI components using Brad Frost's Atomic Design methodology — organizing views into Atoms, Molecules, Organisms, Templates, and Pages with Design Tokens for theming. Use this skill whenever building new SwiftUI UI components, refactoring existing views into reusable pieces, creating a design system, or organizing a component library. Also trigger when the user mentions "atomic design", "design system", "component hierarchy", "reusable components", "atoms and molecules", "design tokens", or wants to decompose a complex SwiftUI view into smaller, composable parts, or needs to implement theming/customization across a SwiftUI app.

SwiftUI Atomic Design System

Atomic Design is Brad Frost's methodology for building UI systems from small, composable pieces. In SwiftUI, this maps naturally to the framework's declarative, compositional view architecture. The hierarchy flows from simple to complex:

Design Tokens → Atoms → Molecules → Organisms → Templates → Pages

Each level composes the one below it. Design Tokens provide the visual foundation that all levels reference. The discipline is knowing where a component belongs — that's what makes the system scalable, consistent, and maintainable.

Design Tokens — The Visual Foundation

Design tokens are the centralized source of truth for all visual properties: colors, typography, spacing. They sit beneath atoms — every component references tokens rather than hardcoding values. This ensures consistency across the entire design system and makes sweeping visual changes (rebranding, dark mode, accessibility) a single-point update.

Why tokens matter:

• Change a brand color once, and it propagates everywhere
• Enable theming (light/dark, high contrast) without touching component code
• Create a shared vocabulary between design and development
• Prevent visual drift as the codebase grows

// Design Tokens: Centralized visual constants
  {
      {
          primary  ()
          secondary  ()
          background  ()
          surface  (.secondarySystemGroupedBackground)
          textPrimary  .primary
          textSecondary  .secondary
    }

      {
          largeTitle  .largeTitle.weight(.bold)
          title  .title2.weight(.semibold)
          headline  .headline.weight(.medium)
          body  .body
          caption  .caption
          captionBold  .caption2.weight(.medium)
    }

      {
          xs:   
          sm:   
          md:   
          lg:   
          xl:   
    }

      {
          sm:   
          md:   
          lg:   
    }
}