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

• 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:

swift-ui-architect

ios-design

ios-ui-refactor

ios-hig

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

token-

color-

style-

type-

space-

govern-

asset-

theme-

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