solo-swiftui-design-system

swiftui-design-system — one scale, and the guards that keep it

A design system is not a colour file. It is four scales, one grid, one catalogue and one tripwire — and the tripwire is what makes it survive the next feature. Everything here is native SwiftUI: no design-system framework is worth taking on, because the platform is already built for this (Environment + style protocols + containerRelativeFrame).

Apple ships its own SwiftUI skills inside Xcode 27 — invalidation, ForEach identity, @Observable, Liquid Glass — as plain markdown any agent can read with no Xcode running. On anything about correctness or update cost they outrank this file, and they say so in their own header. Where they are, what they cover, and the rules that most often hit real code: references/apple-xcode-skills.md.

Reach for this when the symptom is "the screens look related and never line up". Measure before you believe it — see step 1.

Workflow

1. Count what is actually there

Never start from taste. Start from the inventory, because the number is the argument:

V=path/to/Views
grep -rhoE '\.padding\((\.[a-z]+, )?[0-9]+(\.[0-9])?\)' $V | grep -oE '[0-9.]+' | sort -n | uniq -c | sort -rn
grep -rhoE 'spacing: [0-9]+(\.[0-9])?' $V | sort | uniq -c | sort -rn
grep -rhoE 'cornerRadius: [0-9]+(\.[0-9])?' $V | sort | uniq -c | sort -rn
grep -rhoE '\.font\(\.[a-zA-Z0-9]+\)|\.font\(\.system\([^)]*\)\)' $V | sort | uniq -c | sort -rn
grep -rhoE '\.spring\(response: [0-9.]+, dampingFraction: [0-9.]+\)' $V | sort -u | wc -l

A real app measured this way: 27 padding values, 19 spacings, 23 radii, 48 font spellings, 21 springs — including .system(size: 17.5), 13.5, 12.5. Half a point is invisible alone and lethal in a set: it is exactly the amount by which two labels fail to look like the same label.

2. Write the scales — namespace enums, one file each

Views/Design/
  Space.swift       4-point steps: hair(2) xs sm md lg xl xxl xxxl huge + touchTarget(44)
  Grid.swift        12 columns, gutter, margin, gridSpan(_:), gridMargins(), GridOverlay
  Typography.swift  8 steps, each a platform TextStyle + Metric for sizes a font can't set
  Radii.swift       5 radii + shape(_:) — .continuous, always
  Motion.swift      6 curves + the never-repeatForever rule
  Surface.swift     3–4 levels (console/panel/inset/field), one recipe each