/design-system

name: design-system
description: Build-time design-system rules that keep an Apple app cheap to restyle — role-named tokens, text styles that carry case and tracking, shared components with a ContentStateView, small views, identifier-based UI tests, and SwiftLint enforcement with a shrinking baseline. iOS, iPadOS, macOS, watchOS. Use when starting an app's UI, setting up tokens, adopting a designer's Figma/Sketch system, or preparing for or doing a redesign.
allowed-tools: [Read, Write, Edit, Glob, Grep]
last_verified: 2026-11-04
review_by: 2027-06-22

Design System (build-time rules)

How cheap a redesign is depends almost entirely on how styling was written, not on how big the app is. In a real ~45k-line SwiftUI app going through a full redesign, about a third of the estimate was **pure restyling** of screens that already worked — because of hand-set font sizes and colours, case applied at call sites, appearance-named tokens, per-screen loading/empty states, 3,000-line view files, and UI tests that matched visible text.

This skill is the set of rules that prevents that. `design/typography` covers *choosing* type and Dynamic Type; `product/ux-spec` writes a `DESIGN_SYSTEM.md` spec. This skill is about how the code is written so the look can change in one place.

When This Skill Activates

• Starting the UI of a new app (before the first screen)
• Setting up colour/spacing/type tokens, or adopting a designer's system
• A redesign is coming, or restyling is taking longer than it should
• Reviewing UI code for restyle cost

Styling

1. **No raw style values in views.** Fonts, colours, spacing, radius and shadow come from tokens. Allowed: `0`, and an icon-size token. 2. **Name tokens by role, mirroring the designer's variables.** `Text/Primary` → `textPrimary`, `Action/Primary/Background` → `actionPrimaryBackground`. Never by appearance (`label2`, `grey600`, `tagSemibold`) — appearance names are exactly what a redesign changes. 3. **One text style = family + size + weight + line height + tracking + case**, applied with **one** modifier. No `.textCase`, `.tracking`, `.kerning` or `.uppercased()` at call sites. **User-generated text keeps its original case** — provide an `.original` variant. 4. **Spacing and radius come from a scale** (`xxs…xxl`, `s/m/l/pill`), not loose numbers. 5. **Custom fonts:** verify registration at launch in debug builds, and scale with Dynamic Type via `relativeTo:`. A font declared in `UIAppFonts` but missing from the bundle silently falls back to the system font — teams have shipped that for months. 6. **Enforce 1–3 with SwiftLint** (`rules/swiftlint.yml`), with a baseline that only shrinks (see Enforcement).

// Tokens — role names, one file
enum Spacing { static let xs: CGFloat = 4, s: CGFloat = 8, m: CGFloat = 16, l: CGFloat = 24 }
enum Radius  { static let s: CGFloat = 6, m: CGFloat = 12, pill: CGFloat = 999 }
extension Color {
    static let textPrimary = Color("Text/Primary")          // asset catalog, light/dark
    static let actionPrimaryBackground = Color("Action/Primary/Background")
}

// Text style carries case + tracking — call sites never do
struct AppTextStyle: Sendable {
    var font: Font
    var lineSpacing: CGFloat = 0
    var tracking: CGFloat = 0
    var textCase: Text.Case? = nil

    /// Same style without the case transform — for names, titles users typed, etc.
    var original: AppTextStyle { var s = self; s.textCase = nil; return s }
}
extension AppTextStyle {
    static let body  = AppTextStyle(font: .custom("Inter-Regular", size: 17, relativeTo: .body), lineSpacing: 4)
    static let label = AppTextStyle(font: .custom("Inter-SemiBold", size: 12, relativeTo: .caption),
                                    tracking: 0.6, textCase: .uppercase)
}
extension View {
    func appText(_ style: AppTextStyle) -> some View {
        font(style.font).lineSpacing(style.lineSpacing)
            .tracking(style.tracking).textCase(style.textCase)
    }
}

// Call sites
Text("Recent").appText(.label)               // ✅ designed label
Text(item.ownerName).appText(.label.original) // ✅ user text keeps its case
Text("Recent".uppercased()).tracking(0.6)     // ❌ restyle = hunt every call site

// Debug-time font check (call once at launch)
#if DEBUG
func assertCustomFontsRegistered() {
    for name in ["Inter-Regular", "Inter-SemiBold"] {
        #if canImport(UIKit)
        assert(UIFont(name: name, size: 12) != nil, "Font \(name) not bundled/registered")
        #elseif canImport(AppKit)
        assert(NSFont(name: name, size: 12) != nil, "Font \(name) not bundled/registered")
        #endif
    }
}
#endif

Components

7. **Build shared components before screens:** button (variants + loading + disabled), card, chip, text field with error state, search field, sheet, confirm sheet, toast with undo, and **`ContentStateView`**. 8. **Every async or list screen renders through `ContentStateView`** — loading (skeleton), empty, error-with-retry, offline. No ad-hoc spinners or "No results" `Text` per screen. 9. **Variants go into the component**, never a copied-and-tweaked local version inside a screen.

enum ContentState<Value> { case loading, empty, failed, offline, loaded(Value) }

struct ContentStateView<Value, Content: View>: View {
    let state: ContentState<Value>
    var emptyTitle: LocalizedStringKey = "Nothing here yet"
    var retry: (() -> Void)? = nil
    @ViewBuilder var content: (Value) -> Content

    var body: some View {
        switch state {
        case .loading:  ProgressView()   // swap for the app's skeleton
        case .empty:    ContentUnavailableView(emptyTitle, systemImage: "tray")
        case .failed:   FailedStateView(retry: retry)
        case .offline:  ContentUnavailableView("You're Offline", systemImage: "wifi.slash")
        case .loaded(let value): content(value)
        }
    }
}

private struct FailedStateView: View {