ios-design-system

Airbnb iOS Design System Best Practices

Opinionated, strict design system engineering for SwiftUI iOS 26 / Swift 6.2 apps. Contains 50 rules across 8 categories, prioritized by impact. Derived from Airbnb's Design Language System (DLS), Airbnb Swift Style Guide, Apple Human Interface Guidelines, and WWDC sessions. Mandates @Equatable on every view, @Observable for state, and style protocols as the primary component API.

Mandated Architecture Alignment

This skill is designed to work alongside swift-ui-architect. All code examples follow the same non-negotiable constraints:

• Feature modules depend on Domain + DesignSystem; no direct Data dependency
• @Observable for mutable UI state, ObservableObject / @Published never
• @Equatable macro on every view
• Style protocols as the primary component styling API (Airbnb DLS pattern)
• Asset catalog as the source of truth for color values
• Local SPM package for design system module boundary

Scope & Relationship to Sibling Skills

This skill is the infrastructure layer — it teaches how to BUILD the design system itself. When loaded alongside sibling skills:

Sibling Skill	Its Focus	This Skill's Focus
swift-ui-architect	Architecture (modular MVVM-C, route shells, protocol boundaries)	Design system infrastructure (tokens, styles, governance)
ios-design	Using design primitives (semantic colors, typography)	Engineering the token system that provides those primitives
ios-ui-refactor	Auditing/fixing visual quality issues	Preventing those issues via governance and automation
ios-hig	HIG compliance patterns	Asset and component infrastructure that makes compliance easy

Clinic Architecture Contract (iOS 26 / Swift 6.2)

All guidance in this skill assumes the clinic modular MVVM-C architecture:

• Feature modules import Domain + DesignSystem only (never Data, never sibling features)
• App target is the convergence point and owns DependencyContainer, concrete coordinators, and Route Shell wiring
• Domain stays pure Swift and defines models plus repository, *Coordinating, ErrorRouting, and AppError contracts
• Data owns SwiftData/network/sync/retry/background I/O and implements Domain protocols
• Read/write flow defaults to stale-while-revalidate reads and optimistic queued writes
• ViewModels call repository protocols directly (no default use-case/interactor layer)

When to Apply

Reference these guidelines when:

• Setting up a design system for a new iOS app
• Building token architecture (colors, typography, spacing, sizing)
• Creating reusable component styles (ButtonStyle, LabelStyle, custom DLS protocols)
• Organizing asset catalogs (colors, images, icons)
• Migrating from ad-hoc styles to a governed token system
• Preventing style drift and enforcing consistency via automation
• Building theming infrastructure for whitelabel or multi-brand apps
• Reviewing PRs for ungoverned colors, hardcoded values, or shadow tokens

Rule Categories by Priority

Priority	Category	Impact	Prefix	Rules
1	Token Architecture	CRITICAL	token-	6
2	Color System Engineering	CRITICAL	color-	7
3	Component Style Library	CRITICAL	style-	10
4	Typography Scale	HIGH	type-	5
5	Spacing & Sizing System	HIGH	space-	5
6	Consistency & Governance	HIGH	govern-	7
7	Asset Management	MEDIUM-HIGH	asset-	5
8	Theme & Brand Infrastructure	MEDIUM	theme-	5

Quick Reference

1. Token Architecture (CRITICAL)

• token-three-layer-hierarchy - Use Raw → Semantic → Component token layers
• token-enum-over-struct - Use caseless enums for token namespaces
• token-single-file-per-domain - One token file per design domain
• token-shapestyle-extensions - Extend ShapeStyle for dot-syntax colors
• token-asset-catalog-source - Source color tokens from asset catalog
• token-avoid-over-abstraction - Avoid over-abstracting beyond three layers

2. Color System Engineering (CRITICAL)

• color-organized-xcassets - Organize color assets with folder groups by role
• color-complete-pairs - Define both appearances for every custom color
• color-limit-palette - Limit custom colors to under 20 semantic tokens
• color-no-hex-in-views - Never use Color literals or hex in view code
• color-system-first - Prefer system colors before custom tokens
• color-tint-not-brand-everywhere - Set brand color as app tint, don't scatter it
• color-audit-script - Audit for ungoverned colors with a build script

3. Component Style Library (CRITICAL)

• style-dls-protocol-pattern - Define custom style protocols for complex DLS components
• style-equatable-views - Apply @Equatable to every design system view
• style-accessibility-first - Build accessibility into style protocols, not individual views
• style-protocol-over-wrapper - Use Style protocols instead of wrapper views
• style-static-member-syntax - Provide static member syntax for custom styles
• style-environment-awareness - Make styles responsive to environment values
• style-view-for-containers-modifier-for-styling - Views for containers, modifiers for styling
• style-catalog-file - One style catalog file per component type
• style-configuration-over-parameters - Prefer configuration structs over many parameters
• style-preview-catalog - Create a preview catalog for all styles

4. Typography Scale (HIGH)

• type-scale-enum - Define a type scale enum wrapping system styles
• type-system-styles-first - Use system text styles before custom ones
• type-custom-font-registration - Register custom fonts with a centralized extension
• type-max-styles-per-screen - Limit typography variations to 3-4 per screen
• type-avoid-font-design-mixing - Use one font design per app

5. Spacing & Sizing System (HIGH)

• space-token-enum - Define spacing tokens as a caseless enum
• space-radius-tokens - Define corner radius tokens by component type
• space-no-magic-numbers - Zero hardcoded numbers in view layout code
• space-insets-pattern - Use EdgeInsets constants for composite padding
• space-size-tokens - Define size tokens for common dimensions

6. Consistency & Governance (HIGH)

• govern-naming-conventions - Enforce consistent naming conventions across all tokens
• govern-spm-package-boundary - Isolate the design system as a local SPM package
• govern-single-source-of-truth - Every visual value has one definition point
• govern-lint-for-tokens - Use SwiftLint rules to enforce token usage
• govern-design-system-directory - Isolate tokens in a dedicated directory
• govern-migration-incremental - Migrate to tokens incrementally
• govern-prevent-local-tokens - Prevent feature modules from defining local tokens

7. Asset Management (MEDIUM-HIGH)

• asset-separate-catalogs - Separate asset catalogs for colors, images, icons
• asset-sf-symbols-first - Use SF Symbols before custom icons
• asset-icon-export-format - Use PDF/SVG vectors, never multiple PNGs
• asset-image-optimization - Use compression and on-demand resources
• asset-naming-convention - Consistent naming convention for all assets

8. Theme & Brand Infrastructure (MEDIUM)

• theme-environment-key - Use EnvironmentKey for theme propagation
• theme-dont-over-theme - Avoid building a theme system unless needed
• theme-tint-for-brand - Use .tint() as primary brand expression
• theme-light-dark-only - Use ColorScheme for light/dark, not custom theming
• theme-brand-layer-separation - Separate brand identity from system mechanics

How to Use

Read individual reference files for detailed explanations and code examples:

• Section definitions - Category structure and impact levels
• Rule template - Template for adding new rules

Reference Files

File	Description
references/_sections.md	Category definitions and ordering
assets/templates/_template.md	Template for new rules
metadata.json	Version and reference information