ios-design-system

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Airbnb iOS Design System Best Practices

Airbnb iOS设计系统最佳实践

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.

针对SwiftUI iOS 26 / Swift 6.2应用的规范化、严格型设计系统工程方案。包含8个类别下的50条规则，按影响优先级排序。规则源自Airbnb设计语言系统（DLS）、Airbnb Swift风格指南、Apple人机界面指南（HIG）以及WWDC会议内容。要求所有视图使用@Equatable，状态管理使用@Observable，并将样式协议作为组件的核心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

本技能需与

swift-ui-architect

配合使用。所有代码示例遵循以下不可协商的约束：

Feature模块仅依赖
```
Domain
```
+
```
DesignSystem
```
；禁止直接依赖
```
Data
```
可变UI状态使用
```
@Observable
```
，绝不使用
```
ObservableObject
```
/
```
@Published
```
所有视图添加@Equatable宏
将样式协议作为组件样式的核心API（Airbnb DLS模式）
资源目录作为颜色值的唯一可信来源
使用本地SPM包划分设计系统模块边界

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

本技能属于基础设施层 —— 教授如何构建设计系统本身。与关联技能配合使用时的分工如下：

关联技能	核心关注点	本技能核心关注点
`swift-ui-architect`	架构（模块化MVVM-C、路由壳、协议边界）	设计系统基础设施（令牌、样式、治理）
`ios-design`	使用设计原语（语义化颜色、排版）	构建提供这些原语的令牌系统
`ios-ui-refactor`	审计/修复视觉质量问题	通过治理与自动化预防此类问题
`ios-hig`	HIG合规模式	资源与组件基础设施，降低合规难度

Clinic Architecture Contract (iOS 26 / Swift 6.2)

Clinic架构规范（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)

本技能的所有指导均基于Clinic模块化MVVM-C架构：

Feature模块仅导入
```
Domain
```
+
```
DesignSystem
```
（绝不导入
```
Data
```
或其他Feature模块）
App目标作为聚合点，负责
```
DependencyContainer
```
、具体协调器以及路由壳的配置
```
Domain
```
为纯Swift模块，定义模型以及仓库、
```
*Coordinating
```
、
```
ErrorRouting
```
和
```
AppError
```
协议
```
Data
```
模块负责SwiftData/网络/同步/重试/后台I/O，并实现Domain层定义的协议
读写流程默认采用 stale-while-revalidate 读取策略和乐观队列式写入策略
ViewModel直接调用仓库协议（默认不使用用例/交互器层）

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

在以下场景中参考本指南：

为新iOS应用搭建设计系统
构建令牌架构（颜色、排版、间距、尺寸）
创建可复用组件样式（ButtonStyle、LabelStyle、自定义DLS协议）
整理资源目录（颜色、图片、图标）
从临时样式迁移至受治理的令牌系统
通过自动化预防样式漂移并确保一致性
为白标或多品牌应用构建主题基础设施
审查PR中是否存在未受治理的颜色、硬编码值或阴影令牌

Rule Categories by Priority

按优先级划分的规则类别


token-
color-
style-
type-
space-
govern-
asset-
theme-

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


token-
color-
style-
type-
space-
govern-
asset-
theme-

优先级	类别	影响级别	前缀	规则数量
1	令牌架构	关键	`token-`	6
2	颜色系统工程	关键	`color-`	7
3	组件样式库	关键	`style-`	10
4	排版尺度	高	`type-`	5
5	间距与尺寸系统	高	`space-`	5
6	一致性与治理	高	`govern-`	7
7	资源管理	中高	`asset-`	5
8	主题与品牌基础设施	中	`theme-`	5

Quick Reference

快速参考

1. Token Architecture (CRITICAL)

1. 令牌架构（关键）

```
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

```
token-three-layer-hierarchy
```
- 使用原始→语义→组件的三层令牌结构
```
token-enum-over-struct
```
- 使用无案例枚举作为令牌命名空间
```
token-single-file-per-domain
```
- 每个设计领域对应一个令牌文件
```
token-shapestyle-extensions
```
- 扩展ShapeStyle以支持点语法调用颜色
```
token-asset-catalog-source
```
- 从资源目录获取颜色令牌
```
token-avoid-over-abstraction
```
- 避免过度抽象，不超过三层结构

2. Color System Engineering (CRITICAL)

2. 颜色系统工程（关键）

```
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

```
color-organized-xcassets
```
- 按角色分组整理颜色资源
```
color-complete-pairs
```
- 为每个自定义颜色定义两种外观模式
```
color-limit-palette
```
- 将自定义颜色限制在20个语义令牌以内
```
color-no-hex-in-views
```
- 视图代码中绝不使用Color字面量或十六进制值
```
color-system-first
```
- 优先使用系统颜色，再考虑自定义令牌
```
color-tint-not-brand-everywhere
```
- 将品牌色设置为应用色调，避免随处分散使用
```
color-audit-script
```
- 通过构建脚本审计未受治理的颜色

3. Component Style Library (CRITICAL)

3. 组件样式库（关键）

```
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

```
style-dls-protocol-pattern
```
- 为复杂DLS组件定义自定义样式协议
```
style-equatable-views
```
- 为所有设计系统视图添加@Equatable
```
style-accessibility-first
```
- 将无障碍支持内置到样式协议中，而非单个视图
```
style-protocol-over-wrapper
```
- 使用样式协议而非包装视图
```
style-static-member-syntax
```
- 为自定义样式提供静态成员语法
```
style-environment-awareness
```
- 让样式响应环境值变化

style-view-for-containers-modifier-for-styling

- 容器使用视图，样式使用修饰符

```
style-catalog-file
```
- 每种组件类型对应一个样式目录文件
```
style-configuration-over-parameters
```
- 优先使用配置结构体而非多个参数
```
style-preview-catalog
```
- 为所有样式创建预览目录

4. Typography Scale (HIGH)

4. 排版尺度（高）

```
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

```
type-scale-enum
```
- 定义包装系统样式的排版尺度枚举
```
type-system-styles-first
```
- 优先使用系统文本样式，再考虑自定义样式
```
type-custom-font-registration
```
- 通过集中式扩展注册自定义字体
```
type-max-styles-per-screen
```
- 每个屏幕的排版变体限制在3-4种
```
type-avoid-font-design-mixing
```
- 应用中仅使用一种字体设计风格

5. Spacing & Sizing System (HIGH)

5. 间距与尺寸系统（高）

```
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

```
space-token-enum
```
- 将间距令牌定义为无案例枚举
```
space-radius-tokens
```
- 按组件类型定义圆角半径令牌
```
space-no-magic-numbers
```
- 视图布局代码中禁止使用硬编码数值
```
space-insets-pattern
```
- 使用EdgeInsets常量定义复合内边距
```
space-size-tokens
```
- 为通用尺寸定义尺寸令牌

6. Consistency & Governance (HIGH)

6. 一致性与治理（高）

```
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

```
govern-naming-conventions
```
- 为所有令牌强制执行统一命名规范
```
govern-spm-package-boundary
```
- 将设计系统隔离为本地SPM包
```
govern-single-source-of-truth
```
- 每个视觉值仅有一个定义来源
```
govern-lint-for-tokens
```
- 使用SwiftLint规则强制令牌使用规范
```
govern-design-system-directory
```
- 将令牌隔离到专用目录中
```
govern-migration-incremental
```
- 逐步迁移至令牌系统
```
govern-prevent-local-tokens
```
- 禁止Feature模块定义本地令牌

7. Asset Management (MEDIUM-HIGH)

7. 资源管理（中高）

```
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

```
asset-separate-catalogs
```
- 将颜色、图片、图标资源目录分开管理
```
asset-sf-symbols-first
```
- 优先使用SF Symbols，再考虑自定义图标
```
asset-icon-export-format
```
- 使用PDF/SVG矢量格式，绝不使用多份PNG文件
```
asset-image-optimization
```
- 使用压缩和按需加载资源
```
asset-naming-convention
```
- 为所有资源采用统一命名规范

8. Theme & Brand Infrastructure (MEDIUM)

8. 主题与品牌基础设施（中）

```
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

```
theme-environment-key
```
- 使用EnvironmentKey实现主题传播
```
theme-dont-over-theme
```
- 除非必要，否则避免构建主题系统
```
theme-tint-for-brand
```
- 使用.tint()作为品牌的主要表达方式
```
theme-light-dark-only
```
- 使用ColorScheme实现明暗模式，不使用自定义主题
```
theme-brand-layer-separation
```
- 将品牌标识与系统机制分离

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

文件	描述
references/_sections.md	类别定义与排序规则
assets/templates/_template.md	新规则模板
metadata.json	版本与参考信息