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