A design system is not a colour file. It is four scales, one grid, one\ncatalogue and one tripwire — and the tripwire is what makes it survive the\nnext feature. Everything here is native SwiftUI: no design-system framework is\nworth taking on, because the platform is already built for this (Environment +\nstyle protocols + containerRelativeFrame).
Apple ships its own SwiftUI skills inside Xcode 27 — invalidation, ForEach\nidentity, @Observable, Liquid Glass — as plain markdown any agent can read\nwith no Xcode running. On anything about correctness or update cost they\noutrank this file, and they say so in their own header. Where they are, what\nthey cover, and the rules that most often hit real code:\nreferences/apple-xcode-skills.md.
Reach for this when the symptom is \"the screens look related and never line\nup\". Measure before you believe it — see step 1.
\nNever start from taste. Start from the inventory, because the number is the\nargument:
\nV=path/to/Views\ngrep -rhoE '\\.padding\\((\\.[a-z]+, )?[0-9]+(\\.[0-9])?\\)' $V | grep -oE '[0-9.]+' | sort -n | uniq -c | sort -rn\ngrep -rhoE 'spacing: [0-9]+(\\.[0-9])?' $V | sort | uniq -c | sort -rn\ngrep -rhoE 'cornerRadius: [0-9]+(\\.[0-9])?' $V | sort | uniq -c | sort -rn\ngrep -rhoE '\\.font\\(\\.[a-zA-Z0-9]+\\)|\\.font\\(\\.system\\([^)]*\\)\\)' $V | sort | uniq -c | sort -rn\ngrep -rhoE '\\.spring\\(response: [0-9.]+, dampingFraction: [0-9.]+\\)' $V | sort -u | wc -l\nA real app measured this way: 27 padding values, 19 spacings, 23 radii, 48\nfont spellings, 21 springs — including .system(size: 17.5), 13.5, 12.5.\nHalf a point is invisible alone and lethal in a set: it is exactly the amount by\nwhich two labels fail to look like the same label.
Views/Design/\n Space.swift 4-point steps: hair(2) xs sm md lg xl xxl xxxl huge + touchTarget(44)\n Grid.swift 12 columns, gutter, margin, gridSpan(_:), gridMargins(), GridOverlay\n Typography.swift 8 steps, each a platform TextStyle + Metric for sizes a font can't set\n Radii.swift 5 radii + shape(_:) — .continuous, always\n Motion.swift 6 curves + the never-repeatForever rule\n Surface.swift 3–4 levels (console/panel/inset/field), one recipe each\nEnums over structs: compile-time names, zero runtime, no instance to thread.\nReach for @Entry var theme in the Environment only when there is a second\ntheme (white-label, per-brand, light/dark that is not the system's). Until\nthen a theme object is one indirection buying nothing.
Two rules that decide the arguments in step 3:
\nFont.system(.subheadline, weight:), not .system(size: 15). Fixed sizes never grow with Dynamic Type;\nin the measured app 78 of them didn't. For sizes a font cannot set (an icon's\nbox, a ring's diameter) use @ScaledMetric(relativeTo:) over a Metric\nconstant.containerRelativeFrame( .horizontal, count: 12, span: 4, spacing: gutter) is iOS 17+ and is the\nplatform's own grid arithmetic — no GeometryReader, no percentages.Hand-editing hundreds of literals is where a migration dies — half done, half\nnot, and nobody can say which half. Write a codemod, keep it in the repo, and\nlet it carry the rule:
\n# nearest 4-point step, TIES GO UP (6→8, not 4): rounding down tightens a\n# third of the app by two points at once, and a snug layout is the one that\n# breaks. Only padding / spacing / cornerRadius / fonts in 9…26pt —\n# never frame, offset, lineWidth or a shadow radius.\nstep, name = min(SCALE, key=lambda p: (abs(p[0] - value), -p[0]))\nFull rule, the skip list, the spring and font tables: references/codemod.md.\nRead it when actually migrating; one measured run was 991 substitutions in 31\nfiles, dry-run first, build after each family.
SwiftUI's extension points are the system's spine — use them before inventing\n.myButton():
struct PressableStyle: ButtonStyle { // one feel for every control\n func makeBody(configuration: Configuration) -> some View {\n configuration.label\n .scaleEffect(configuration.isPressed ? 0.97 : 1)\n .animation(configuration.isPressed ? Motion.press : Motion.release,\n value: configuration.isPressed)\n }\n}\nLabelStyle, ToggleStyle, ProgressViewStyle, MenuStyle the same way; a\nViewModifier + extension View for what has no protocol (.surface(.inset)).
Two doors, answering different questions:
\nmake design # ImageRenderer → PNG sheets from a test: no launch, no taps, ~3s\nmake design-app # the same gallery in the simulator: glass, blur, motion\n… launch <app> -designGrid YES # the 12 columns over the REAL screens\nImageRenderer inside an XCTest is the whole storybook you need — a gallery\nview rendered to docs/previews/*.png, one file per sheet, no navigation and no\nexternal dependency. It does not draw materials: .ultraThinMaterial and\nglassEffect come out empty, so glass reads flat there. Geometry is exact,\nwhich is what the sheets are for.
The grid overlay over the real app is the only thing that proves two screens\nagree; a gallery only proves one screen is tidy.
\nThe writer, the debug flag, the localisation trap and when to reach for\nswift-snapshot-testing: references/catalogue.md.
Three layers, cheapest first:
\n.padding(12), spacing: 6, cornerRadius: 18, .font(.system(size: 13)).\nDiff-scoped and warning-only is the right calibration — a whole-tree lint at\nfail severity breaks on inherited debt and gets bypassed, and a bypassed hook\nchecks nothing.span(6) * 2 + gutter == width; every space step divisible by 4\nexcept the one deliberate half step.containerRelativeFrame measures the container, not its content. Apply\ngridMargins() first, or every span is a margin too wide and nothing lines\nup with anything.Sendable warning on static let tokens in Swift 6: an enum of\nstatic let CGFloat is fine; a struct holding UserDefaults needs\n@unchecked Sendable with a one-line reason.GlassEffectContainer(spacing:) and give morphing pairs a\n.glassEffectID(_:in:); below 26 fall back to .ultraThinMaterial in one\nplace, not per screen.compositingGroup() + a zero shadow is still an offscreen pass. Apply\nthe lift only where there is a shadow to draw.repeatForever. A UI that never goes idle hangs everything that\nwaits for idle: accessibility snapshots, UI automation, VoiceOver. Use\n.repeatCount(n) and honour \\.accessibilityReduceMotion.-designGallery YES from simctl\nlands in the argument domain, so one UserDefaults.bool(forKey:) read covers\nit — but wrap it in a small injectable type that is false in Release, or the\nflag ships.glassEffect,\nGlassEffectContainer, .buttonStyle(.glass)), @Entry for environment\ntokens with no EnvironmentKey boilerplate, ToolbarSpacer,\nbackgroundExtensionEffect(), scrollEdgeEffectStyle.ContentBuilder collapses the\ncontainer overloads that cause \"unable to type-check this expression in\nreasonable time\" — and it helps when built with the new Xcode regardless of\ndeployment target. .reorderable() in any container (not just List), swipe\nactions outside List, toolbar overflow priorities, @State as a macro with\nlazy @Observable init (back-deployed to iOS 17). Resizable iPhone apps is\nthe one that touches a design system directly: baked-in sizes stop being safe,\nso snapshot at several widths.Xcode ships agent skills in the toolchain — plain SKILL.md folders, so they\nwork in any agent, not only Xcode's assistant.
make apple-skills # solo-factory: export into ~/.agents/skills, diffed\nmake apple-skills-check # what it would bring, without writing\nXcode 26.6 exports nothing — the agent tool is there and answers \"No\nskills available to export\", so the script says that plainly rather than look\nbroken. Xcode 27.0 beta 2 exports ten: swiftui-specialist,\nswiftui-whats-new-27, uikit-app-modernization, modernize-tests,\naudit-xcode-security-settings, adopt-c-bounds-safety, device-interaction,\napp-intents-specialist, app-intents-whats-new-27 and\nbuilding-document-based-swiftui-applications. The names are not stable across\nversions — four of the seven guessed from the 26.6 release notes came back\nspelled differently — so read the export rather than a list.
Re-run after every Xcode update: these track the SDK, and a stale \"what's new\"\nskill is worse than none. A beta installed alongside the release is not the\nactive toolchain, and xcode-select is machine-wide — scope one run instead:\nDEVELOPER_DIR=\"/Applications/Xcode-beta.app/Contents/Developer\" make apple-skills.\nIf the export names the toolchain instead, Xcode → Settings → Locations →\nCommand Line Tools points at the wrong Xcode.
device-interaction is the one that matters for a design system: it drives a\nreal device or simulator — screenshots, view hierarchy, synthesised taps — which\ncloses the loop a build tool alone cannot (write layout → build → look at it →\ncorrect it) without a human running the walk.
Community skills worth reading before installing — a skill is injected into\nthe assistant's context and changes how it writes your code:
\n| Where | \nWhy | \n
|---|---|
twostraws/Swift-Agent-Skills | \ncurated index; start here | \n
twostraws/SwiftUI-Agent-Skill (swiftui-pro) | \naimed at the mistakes LLMs actually make: navigation, layout, state, VoiceOver, deprecated APIs | \n
AvdLee/SwiftUI-Agent-Skill | \nthe architecture to copy — references loaded on demand, so deep context costs nothing until asked for. Also a maintenance skill that refreshes the deprecated-API list after each release | \n
Dimillian/Skills | \nswiftui-liquid-glass, swiftui-view-refactor, swiftui-performance-audit | \n
dpearson2699/swift-ios-skills | \n86 skills on iOS 26+ — PolyForm Perimeter licence, not MIT; read it before commercial use | \n
Design-system repos worth reading rather than depending on: DSKit (organised\nfor agents — generated docs link every component to its source, snapshots and\nusage), OversizeUI (semantic colours, Dynamic Type, spacing scale),\ndesign-foundation (MIT, Swift 6 concurrency-safe), ouds-ios (corporate\nscale, strong accessibility).
\nblue500. Semantic names (surfaceElevated,\ntextSecondary) survive a re-skin; a palette index turns one into a\nfind-and-replace across the app.isSelected ? .semibold : .regular\nis a step plus .fontWeight() on top — folding it in is how a scale of eight\nbecomes a scale of sixteen.Brand.tabRadius = Radii.lg reads as tidy and puts\ntwo spellings of 16pt in one file within a week.vm.loadavg\nfirst; three \"regressions\" in one project were the laptop.