Atomic Design iOS — Expert Decisions
Expert decision frameworks for Atomic Design choices in SwiftUI. Claude knows view composition — this skill provides judgment calls for when component hierarchy adds value and how to define boundaries.
Decision Trees
Do You Need Atomic Design?
How large is your design system?
├─ Small (< 10 components)
│ └─ Skip formal hierarchy
│ Simple "Components" folder is fine
│
├─ Medium (10-30 components)
│ └─ Consider Atoms + Molecules
│ Skip Organisms/Templates if not needed
│
└─ Large (30+ components, multiple teams)
└─ Full Atomic Design hierarchy
Atoms → Molecules → Organisms → Templates
The trap: Atomic Design for a 5-screen app. The overhead of categorization exceeds the benefit.
Atom vs Molecule Boundary
Does this component combine multiple distinct elements?
├─ NO (single visual element)
│ └─ Atom
│ Button, TextField, Badge, Icon, Label
│
└─ YES (2+ elements that work together)
└─ Can these elements be used independently?
├─ YES → Molecule (SearchBar = Icon + TextField + Button)
└─ NO → Still Atom (password field with toggle is one unit)
Component Extraction Decision
Will this be used in multiple places?
├─ NO (one-off)
│ └─ Don't extract
│ Inline in parent view
│
├─ YES (2-3 places)
│ └─ Extract as local component
│ Same file or sibling file
│
└─ YES (4+ places or cross-feature)
└─ Extract to design system
Full Atom/Molecule treatment
Design Token Scope
What type of value?
├─ Color
│ └─ Is it semantic or brand?
│ ├─ Semantic (error, success) → Color.error, Color.success
│ └─ Brand (primary, accent) → Color.brandPrimary
│
├─ Spacing
│ └─ Use named scale (xs, sm, md, lg, xl)
│ Never magic numbers
│
├─ Typography
│ └─ Use semantic names (body, heading, caption)
│ Map to Font.body, Font.heading
│
└─ Corner radius, shadows
└─ Named tokens if used consistently
Radius.card, Shadow.elevated
NEVER Do
Component Design
NEVER create atoms that know about app state:
// ❌ Atom depends on app-level state
struct PrimaryButton: View {
@EnvironmentObject var authManager: AuthManager
var body: some View {
Button(action: action) {
if authManager.isLoading { ProgressView() }
else { Text(title) }
}
}
}
// ✅ Atom receives all state as parameters
struct PrimaryButton: View {
let title: String
let action: () -> Void
var isLoading: Bool = false
var body: some View {
Button(action: action) {
if isLoading { ProgressView() }
else { Text(title) }
}
}
}
NEVER hardcode values in components:
// ❌ Magic numbers everywhere
struct Card: View {
var body: some View {
content
.padding(16) // Magic number
.background(Color(hex: "#FFFFFF")) // Hardcoded
.cornerRadius(12) // Magic number
}
}
// ✅ Use design tokens
struct Card: View {
var body: some View {
content
.padding(Spacing.md)
.background(Color.surface)
.cornerRadius(Radius.card)
}
}
NEVER create components with too many parameters:
// ❌ Too many parameters — hard to use
struct ComplexButton: View {
let title: String
let subtitle: String?
let icon: String?
let iconPosition: IconPosition
let size: Size
let style: Style
let isLoading: Bool
let isEnabled: Bool
let hasBorder: Bool
let cornerRadius: CGFloat
// ... 10 more parameters
}
// ✅ Split into focused variants
struct PrimaryButton: View { ... }
struct SecondaryButton: View { ... }
struct IconButton: View { ... }
struct LoadingButton: View { ... }
Hierarchy Mistakes
NEVER skip levels in composition:
// ❌ Template directly uses atoms (no molecules/organisms)
struct ProductListTemplate: View {
var body: some View {
ForEach(products) { product in
// Building organism inline from atoms
HStack {
AsyncImage(url: product.imageURL)
VStack {
Text(product.name).font(.headline)
Text("$\(product.price)").foregroundColor(.blue)
}
Button("Add") { }
}
}
}
}
// ✅ Template uses organisms
struct ProductListTemplate: View {
var body: some View {
ForEach(products) { product in
ProductCard(product: product, onAddToCart: { })
}
}
}
NEVER put business logic in design system components:
// ❌ Organism fetches data
struct UserCard: View {
@StateObject private var viewModel = UserViewModel()
var body: some View {
Card {
// Uses viewModel.user
}
.onAppear { viewModel.load() }
}
}
// ✅ Organism is purely presentational
struct UserCard: View {
let user: User
let onTap: () -> Void
var body: some View {
Card {
// Uses passed-in user
}
}
}
Design Token Mistakes
NEVER use platform colors directly:
// ❌ Hardcoded system colors
.foregroundColor(.blue)
.background(Color(.systemGray6))
// ✅ Semantic tokens that can be themed
.foregroundColor(Color.interactive)
.background(Color.surfaceSecondary)
NEVER duplicate token definitions:
// ❌ Same value defined in multiple places
struct Card { let cornerRadius: CGFloat = 12 }
struct Button { let cornerRadius: CGFloat = 12 }
struct TextField { let cornerRadius: CGFloat = 12 }
// ✅ Single source of truth
enum Radius {
static let sm: CGFloat = 4
static let md: CGFloat = 8
static let lg: CGFloat = 12
}
struct Card { ... .cornerRadius(Radius.lg) }
Essential Patterns
Token System Structure
// Spacing tokens
enum Spacing {
static let xs: CGFloat = 4
static let sm: CGFloat = 8
static let md: CGFloat = 16
static let lg: CGFloat = 24
static let xl: CGFloat = 32
}
// Color tokens (support dark mode)
extension Color {
// Semantic
static let textPrimary = Color("TextPrimary")
static let textSecondary = Color("TextSecondary")
static let surface = Color("Surface")
static let surfaceSecondary = Color("SurfaceSecondary")
// Brand
static let brandPrimary = Color("BrandPrimary")
static let brandAccent = Color("BrandAccent")
// Feedback
static let success = Color("Success")
static let warning = Color("Warning")
static let error = Color("Error")
}
// Typography tokens
extension Font {
static let displayLarge = Font.system(size: 34, weight: .bold)
static let heading1 = Font.system(size: 28, weight: .bold)
static let heading2 = Font.system(size: 22, weight: .semibold)
static let bodyLarge = Font.system(size: 17)
static let bodyRegular = Font.system(size: 15)
static let caption = Font.system(size: 13)
}
Composable Atom Pattern
// Atom with sensible defaults and overrides
struct PrimaryButton: View {
let title: String
let action: () -> Void
var isLoading: Bool = false
var isEnabled: Bool = true
var size: Size = .regular
enum Size {
case small, regular, large
var padding: EdgeInsets {
switch self {
case .small: return EdgeInsets(horizontal: Spacing.sm, vertical: Spacing.xs)
case .regular: return EdgeInsets(horizontal: Spacing.md, vertical: Spacing.sm)
case .large: return EdgeInsets(horizontal: Spacing.lg, vertical: Spacing.md)
}
}
var font: Font {
switch self {
case .small: return .caption
case .regular: return .bodyRegular
case .large: return .heading2
}
}
}
var body: some View {
Button(action: action) {
Group {
if isLoading {
ProgressView()
} else {
Text(title).font(size.font)
}
}
.frame(maxWidth: .infinity)
.padding(size.padding)
}
.background(isEnabled ? Color.brandPrimary : Color.textSecondary)
.foregroundColor(.white)
.cornerRadius(Radius.md)
.disabled(!isEnabled || isLoading)
}
}
Molecule with Slot Pattern
// Generic molecule with customizable slots
struct Card<Content: View, Footer: View>: View {
let content: Content
let footer: Footer?
init(
@ViewBuilder content: () -> Content,
@ViewBuilder footer: () -> Footer
) {
self.content = content()
self.footer = footer()
}
var body: some View {
VStack(alignment: .leading, spacing: Spacing.md) {
content
if let footer = footer {
Divider()
footer
}
}
.padding(Spacing.md)
.background(Color.surface)
.cornerRadius(Radius.lg)
.shadow(color: .black.opacity(0.1), radius: 4, y: 2)
}
}
// Convenience initializer without footer
extension Card where Footer == EmptyView {
init(@ViewBuilder content: () -> Content) {
self.content = content()
self.footer = nil
}
}
Quick Reference
When to Extract Components
| Scenario | Action | |----------|--------| | Used once | Keep inline | | Used 2-3 times in same feature | Local extraction | | Used across features | Design system component | | Complex but single-use | Extract for readability only |
Component Classification
| Level | Examples | Knows About | |-------|----------|-------------| | Atom | Button, TextField, Icon, Badge | Nothing external | | Molecule | SearchBar, FormInput, Card | Atoms only | | Organism | NavigationBar, ProductCard, UserList | Atoms + Molecules | | Template | ListPageLayout, FormLayout | Organisms |
Design Token Categories
| Category | Token Examples | |----------|----------------| | Spacing | xs, sm, md, lg, xl | | Color | textPrimary, surface, brandPrimary, error | | Typography | displayLarge, heading1, body, caption | | Radius | sm, md, lg, full | | Shadow | subtle, elevated, prominent |
Red Flags
| Smell | Problem | Fix | |-------|---------|-----| | Atom uses @EnvironmentObject | Knows too much | Pass state as params | | 10+ parameters on component | Too flexible | Split into variants | | Magic numbers in components | Not themeable | Use tokens | | Template builds from atoms | Skipping levels | Use molecules/organisms | | Different corner radius per component | Inconsistency | Token system | | Component fetches data | Wrong layer | Presentational only |