---
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
title: design-system
canonical_url: https://skilld.dev/gh/rshankras/claude-code-apple-skills/design-system
last_updated: 2026-11-12T09:08:23.000Z
---

> Index of every page on this site: [llms.txt](https://skilld.dev/llms.txt)

> **Skill from skilld.dev.** Follow the user's requested action.
> If the user asked to fork this Skill, follow the fork workflow below. Do not execute the Skill instructions while copying it.
> Otherwise, follow the instructions below for this session. You do not need to install anything.
>
> Supporting files, fetch one when the Skill refers to it: [rules/swiftlint.yml](https://skilld.dev/api/skills-raw/rshankras/claude-code-apple-skills/design-system/rules/swiftlint.yml).
>
> If the user asked to install this Skill, run `npx skilld install rshankras/claude-code-apple-skills/design-system`. Install writes the Skill files into the project, so every session loads them.
>
> ## Fork workflow
>
> A fork creates an editable local Skill with its original author and licence. The request authorizes copying and local installation.
> 1. Check `./skills/design-system`, the project lockfile, and selected Agent targets together. If the local directory or installed Skill exists, stop. Never overwrite an existing directory or Agent target.
> 2. Read [source metadata](https://skilld.dev/api/v1/skills/rshankras/claude-code-apple-skills/design-system) once. Use sourceUrl, sourceCommit, skillPath, sourceGone, and license. If the source is gone or its path is missing, stop. If license is null, read licence files at the source commit.
> 3. Fetch only the source commit into a temporary Git repository. Do not clone full history. Derive repository_url from sourceUrl, including repository renames. If sourceCommit is absent, resolve the sourceUrl ref once. Set source_commit to that actual commit. Run these commands in one shell call:
>
> ```sh
> git init --quiet "$temporary_dir"
> git -C "$temporary_dir" fetch --quiet --depth=1 "$repository_url" "$source_commit"
> git -C "$temporary_dir" checkout --quiet --detach FETCH_HEAD
> ```
>
> Read applicable licence declarations and notices at that commit. If copying is not permitted, report the restriction and stop.
> 4. Inspect source entries together, then copy the directory containing skillPath into `./skills/design-system`. Use the user's path if selected. Keep the original SKILL.md, relative links, scripts, binary assets, and executable modes. Exclude .git metadata. Reject symlinks and paths outside the Skill directory. After checking entries, use cp -a where available. A regular source directory needs no custom copy script. Do not save this page wrapper as SKILL.md.
> Preserve author credit, notices, and applicable licence files from repository or parent directories. Add PROVENANCE.md with the Skill page, source URL, actual commit, original path, and licence. Retain any existing PROVENANCE.md and record new provenance separately. Batch source inspection, copying, and provenance work where practical.
> 5. In the project root, run `skilld install ./skills/design-system --mode copy --plain`. If skilld is unavailable, use `npx skilld install ./skills/design-system --mode copy --plain`. This known command needs no help lookup. Install does not support --json. Use detected Agent targets, or add --agent for the targets the user selected. Install the local path, never the upstream selector. If installation fails, preserve the local copy and report the exact failure.
> 6. Confirm the local lockfile source and installed Agent copies once. Report the local path, actual commit, and Agent targets. After edits, reinstall the same local path. Upstream updates must not replace it. Do not publish or push unless the user asks.

# 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).

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

```swift
// 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.

```swift
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 {
    let retry: (() -> Void)?
    var body: some View {
        ContentUnavailableView {
            Label("Couldn't Load", systemImage: "exclamationmark.triangle")
        } actions: {
            if let retry { Button("Try Again", action: retry) }
        }
    }
}
```
`ContentUnavailableView` needs iOS 17 / macOS 14 / watchOS 10; below that,
build the same three states from a `VStack`.

## Screen structure

10. **View files under ~300 lines** — split by section into subviews in
    their own files. Large files are where layout and logic tangle, and they
    are the slowest to restyle (also: `swift/code-size`).
11. **Logic in `@Observable` models/services**; views read state and send
    actions.
12. **Formatting through shared formatters** — money + currency, units,
    dates, distances, counts. Never format by hand in a view.
13. **`#Preview` for every state:** default, loading, empty, error, long
    text, and large Dynamic Type (iOS) / narrow + wide window (macOS) /
    smallest + largest watch (watchOS).

## Data

14. **Model the domain, not today's screen:** typed media items instead of
    `[String]` URLs, a structured `Rate` instead of a bare `Double`, a
    preferences map instead of N booleans. A redesign that adds one field
    shouldn't rewrite the model.
15. **Schema changes ship with a migration/backfill** and updated access
    rules (CloudKit/server).
16. **Status enums decode unknown values to `.unknown`**, so a server adding
    a status doesn't break older builds:

```swift
enum OrderStatus: String, Decodable {
    case pending, shipped, delivered, unknown
    init(from decoder: Decoder) throws {
        let raw = try decoder.singleValueContainer().decode(String.self)
        self = OrderStatus(rawValue: raw) ?? .unknown
    }
}
```

## Tests

17. **UI tests find elements by `accessibilityIdentifier`, never visible
    text.** A copy or case change shouldn't break the test suite. Give every
    interactive or asserted element an identifier.
18. **Snapshot-test the shared components** — each variant and state. A
    token change then shows up as a reviewable image diff in one place
    (`testing/snapshot-test-setup`).

```swift
Button("Save", action: save).accessibilityIdentifier("editor.save")
app.buttons["editor.save"].tap()        // ✅ survives "Save" → "Done"
app.buttons["Save"].tap()               // ❌ breaks on any copy change
```

## Process

19. **Design system first, screens second.** Tokens, text styles and shared
    components exist before the first feature screen.
20. **Developer review of each design section before it's final** — flag
    costly items early (paid services, large uploads, location, new backend
    work).
21. **Build each phase against a named or dated design version.** Changes
    after that are change requests, not defects.
22. **Ask designers for** a small set of text styles, role-named colour
    variables and a real spacing scale — it's what makes 1–4 possible.

## Enforcement

`rules/swiftlint.yml` adds custom rules for raw font sizes, raw colours,
numeric padding/radius, and call-site case/tracking. Merge it into the
project's `.swiftlint.yml` and **exclude the token/style files** (the rules
already skip paths containing `DesignSystem/`, `Tokens/`, `Theme/`, `Styles/`).

Existing codebase: freeze current violations, then let the baseline only
shrink — new code must be clean, migrated files leave the baseline:
```bash
swiftlint lint --write-baseline .swiftlint-baseline.json    # once
swiftlint lint --strict --baseline .swiftlint-baseline.json # every build / CI
```
Measuring how much styling bypasses the tokens (the "design debt" ratio) is
the first number to know before quoting any redesign.

## Platform notes

- **iOS / iPadOS:** text styles via `Font.custom(_:size:relativeTo:)` or the
  system styles; `@ScaledMetric` for spacing that should grow with type;
  components adapt to size classes rather than screens branching on them.
- **macOS:** no Dynamic Type — design at 100%; semantic `NSColor`
  equivalents in the asset catalog; respect control sizes (`.controlSize`);
  **hover and focus states are part of every interactive component**.
- **watchOS:** compact text styles and a smaller spacing scale; components
  sized for glanceable states and the Digital Crown; skip glass-heavy
  treatments.

## Output Format

Restyle-cost review: `File | Rule # | Finding | Fix` — group by rule, count
raw values vs token uses, and list files over 300/500 lines.

## References

- https://developer.apple.com/design/human-interface-guidelines/color
- https://developer.apple.com/design/human-interface-guidelines/typography
- https://developer.apple.com/documentation/swiftui/contentunavailableview
- Related skills: `design/typography` (type choice, Dynamic Type), `product/ux-spec` (DESIGN_SYSTEM.md spec), `swift/code-size` (size thresholds), `testing/snapshot-test-setup`, `generators/accessibility-generator`
