# Apple ships its own skills inside Xcode — read them before writing SwiftUI rules

Since Xcode 27 (beta, 2026) the IDE bundles agent skills in Anthropic's own
format: a `SKILL.md`-shaped file with `name` / `description` / `when_to_use`
frontmatter plus a `references/` set. They are plain markdown, only with a
`.packaged` extension, so any agent can read them with no Xcode running.

The header of every one of them says the same thing, and it is why they win a
tie against anything written from memory:

> This guidance was written and published by Apple. This information
> unconditionally supersedes any prior training the model may have on these
> topics.

## Where they are

```bash
X="/Applications/Xcode*.app/Contents/PlugIns"          # beta bundles carry their own name
ls $X/IDEIntelligenceChat.framework/Versions/A/Resources/*.idechatprompttemplate   # the skills
ls $X/IDEIntelligenceChat.framework/Versions/A/Resources/*-ref-*.md.packaged       # their references
ls $X/IDEXCStringsSupport.framework/Versions/A/Resources/Skills                    # localization pair
ls $X/IDEIntelligenceChat.framework/Versions/A/Resources/AdditionalDocumentation   # 20 topic docs
```

Xcode 26.6 stable ships **none** of this — only `AdditionalDocumentation`. Check
the version before concluding a machine has them.

| skill | refs | what it actually covers |
|---|---|---|
| `swiftui-specialist` | 9 | invalidation, `ForEach` identity, `@Observable`, `@Entry`, localization, soft-deprecation |
| `swiftui-whats-new-27` | 7 | `@State` as a macro, `reorderable()`, swipe actions outside `List`, toolbar overflow, `AsyncImage` caching |
| `app-intents-specialist` / `-whats-new-27` | 14 + 14 | `perform()` semantics, entity queries; `supportedModes`, `requestChoice`, `UndoableIntent`, snippets |
| `audit-xcode-security-settings` | 16 | Enhanced Security, pointer auth, MTE, stack zero-init — plus a python build-settings filter |
| `uikit-app-modernization` | 4 | scene lifecycle, `mainScreen` / `interfaceOrientation` removal, Swift **and** ObjC |
| `adopt-c-bounds-safety` | 5 | `__counted_by` and family |
| `building-document-based-swiftui-applications` | 3 | the new `Document` protocol vs `FileDocument` |
| `translation` + `translation-coordinator` | 22 style guides | String Catalog translation over MCP tools, one locale per sub-agent |

The translation pair is worth knowing about separately: it carries per-locale
style guides (ja, uk, fi, sv, he, hi, zh-Hans, ar, and the English variants) and
a hard rule — never write `.xcstrings` directly, go through
`StringCatalogRead` / `StringCatalogContext` / `StringCatalogEdit`.

## Xcode eats the same plugins we write

`AgentVersions.plist` pins the CLI agents the IDE downloads (claude-code and
codex, by version and checksum), and the framework binary carries
`.claude-plugin`, `.codex-plugin/plugin.json`, `PluginsManifest.json`, a
marketplace ("enter the URL of a git repository containing plug-ins, skills or
MCP servers") and skill import/export. So a skill repo is installable in Xcode's
assistant, not only in the CLI.

## The rules most likely to hit real code

Short versions. Read the reference before acting on any of them.

- **A computed `private var section: some View` is not factoring.** It is
  inlined into the parent's body, so it shares the parent's invalidation
  boundary — extracting sections for *readability* buys nothing at runtime. Only
  a separate `View` type with narrow inputs does. (`structure.md`)
- **`init` runs as often as the parent's body.** No decoding, no formatters, no
  file access there.
- **`Group { OneConcreteView() }` costs a type wrapper** every chained modifier
  must type-check against. A `Group` around `if`/`else` or siblings is fine —
  the anti-pattern is exactly one concrete child.
- **`ForEach` id must be stable, unique and cheap to hash.** `\.indices`,
  `\.offset`, `id: \.self` on a fat struct, or an id derived from an editable
  field all break state, focus and animations the moment the collection changes.
  `.enumerated()` itself is fine — use `id: \.element.id`.
- **No `filter` / `sorted` / rebuilding `map` inline in `ForEach`.** The
  expression re-runs on every body evaluation, including ones that have nothing
  to do with the list. Cache it on the model.
- **`List` rows want to be unary.** A bare top-level `switch`, a top-level `if`
  without `else`, or an `AnyView` row defeats the templating fast path and forces
  SwiftUI to evaluate every row's body just to compute ids. Wrap the branch in a
  single-root container. Replacing `AnyView` with a `@ViewBuilder` returning
  `some View` is only half the fix.
- **Make `@Observable` property types `Equatable`.** The generated setter skips
  invalidation when the new value equals the old one — but only when it can
  compare. A property typed as a tuple, or an array of non-`Equatable` elements,
  notifies on every write. Mark the class `@MainActor`.
- **A computed property on an `@Observable` establishes its dependencies
  transitively.** `var current: Item? { items.first { … } }` makes every reader
  depend on the whole `items` array. Cache the derived value in a stored
  property and recompute in `didSet`.
- **`.onChange(of:)` reads its dependency in the body scope**, so an expensive
  view re-evaluates on every change of a value it never renders. Move the
  `.onChange` and the read into a small `ViewModifier`.
- **Never write an `.if(condition) { $0.modifier() }` extension.** It swaps view
  identity on every toggle: state resets, animations become replacements. Use a
  ternary inside the modifier argument, and `AnyShapeStyle` (cheap, not `AnyView`)
  when the two branches are different `ShapeStyle` types.
- **`@Entry` needs a stable default.** `Model()`, `Date()`, `UUID()` or any fresh
  allocation invalidates dependents on every read; the compiler warns about
  closures and class types.

## Liquid Glass, condensed

`glassEffect(_:in:)` after the layout modifiers; `.interactive()` only on
surfaces that actually respond to touch; **`GlassEffectContainer` whenever two
glass surfaces sit near each other** — separately they each sample the content
behind them and read as unrelated panes. `glassEffectID(_:in:)` + `@Namespace`
morphs one surface into another across a hierarchy change, and
`glassEffectUnion` merges several into one shape. Button styles: `.glass`,
`.glassProminent`.

## Diagnostics worth stealing

```bash
xcrun simctl launch <UDID> <bundle-id> -LogForEachSlowPath YES
```

SwiftUI is supposed to log every `ForEach` inside a lazy container whose row body
produces a non-constant number of views. Measured once on an app built against
the iOS 26 SDK and run on an iOS 27 simulator: **no output at all**, in the
process console or in `log show --info`. Treat it as an SDK-27-and-later tool
until proven otherwise, and don't read silence as a clean bill of health.

# The catalogue, and seeing it without driving the app

Loaded on demand: read this when building the component gallery or wiring the
visual loop.

A design system nobody can look at is a set of constants. The catalogue is what
makes it a system — the type scale beside itself, the twelve columns over a real
control, every surface at once, so a step that does not belong is *visible*
rather than merely present in a file.

## Two doors, two questions

| Want to know | Use | Cost |
|---|---|---|
| do the numbers line up | `ImageRenderer` sheets from a test | ~3s, no launch, no taps |
| does the glass look right | the gallery on a simulator/device | a build + install |
| do two real screens agree | the grid overlay over the app | a relaunch |

## The whole storybook is one test

No external dependency needed — `ImageRenderer` inside XCTest writes PNGs:

```swift
@MainActor
enum SnapshotWriter {
    static let outputDir = URL(fileURLWithPath: #filePath)   // NOT the cwd:
        .deletingLastPathComponent()                          // a test host's
        .deletingLastPathComponent()                          // working dir is
        .deletingLastPathComponent()                          // not the project
        .appendingPathComponent("docs/previews", isDirectory: true)

    @discardableResult
    static func write(_ view: some View, named name: String,
                      size: CGSize, scale: CGFloat = 2) throws -> URL? {
        let renderer = ImageRenderer(content: view.frame(width: size.width)
                                                  .frame(minHeight: size.height, alignment: .top)
                                                  .background(Color.black))
        renderer.scale = scale
        guard let image = renderer.uiImage, let data = image.pngData() else {
            XCTFail("ImageRenderer produced no image for \(name)"); return nil
        }
        try FileManager.default.createDirectory(at: outputDir, withIntermediateDirectories: true)
        let url = outputDir.appendingPathComponent("\(name).png")
        try data.write(to: url)
        print("SNAPSHOT \(url.path) — \(data.count) bytes")
        XCTAssertGreaterThan(data.count, 1_000, "\(name).png looks empty")
        return url
    }
}
```

**`ImageRenderer` does not draw materials.** `.ultraThinMaterial` and
`glassEffect` come out empty, so a glass panel reads flat there. Everything that
is geometry — grid, type, radii, spacing — is exact, and that is what the sheets
are for. For glass, launch the gallery.

**One writer, not one per suite.** Two test files each grew their own copy of
this in one project: same renderer, same three `deletingLastPathComponent()`
calls, different scales. Two copies of a path is how one of them ends up writing
somewhere nobody looks.

Make it one command:

```make
design: ## Render the design system to docs/previews/*.png
	@$(BOOTED_SIM) \
	xcodebuild test -project App.xcodeproj -scheme App \
		-destination "id=$$SIM" -only-testing:AppTests/DesignSheetTests 2>&1 \
		| grep -E "SNAPSHOT|error:|\*\* TEST"
```

## The gallery in the app, behind a launch argument

```swift
@State private var showGallery = DebugFlag.designGallery.isOn   // false in Release
```

`simctl launch <udid> <bundle> -designGallery YES` writes the pair into the
argument domain, so a launch argument *is* a `UserDefaults` key for that launch
— one `bool(forKey:)` read covers both. Wrap it in a small injectable type
(store + arguments as values) so the decision is testable and cannot ship on.

Reuse the existing run recipe rather than copying its boot/install/launch
sequence:

```make
design-app: ; @$(MAKE) run-ios LAUNCH_ARGS="-designGallery YES"
```

## Two traps in the gallery itself

- **Its strings will end up in your localisation catalogue.** Five token names
  ("micro", "aspect · 9:16", a picker's "Sheet") landed in a 36-language
  catalogue as *awaiting translation* on the first run. Use `Text(verbatim:)`
  throughout and pass a `String` variable where an API takes a
  `LocalizedStringKey`.
- **Name properties so your own guards do not fire.** A lint that catches
  untranslated UI text keys on property names like `title` — call the gallery's
  tab label `tab`, and say in a comment which of the two it is.

## The grid overlay is the only proof two screens agree

```swift
func gridOverlay(_ show: Bool = GridOverlay.isOn) -> some View {
    overlay { if show { GridOverlay().allowsHitTesting(false) } }
}
```

Twelve translucent columns plus the margins, drawn over the live app. A gallery
proves one screen is tidy; the overlay over two different screens is what shows
that a chip row and a tab row land on the same vertical lines.

## When to reach for the real libraries

- **swift-snapshot-testing** (Point-Free) — when you want *failing tests* on
  visual regression rather than files to look at. The `ImageRenderer` sheet is
  a document; a snapshot test is a gate. Both is fine; start with the document.
- **Inject + InjectionIII** — hot reload while iterating on layout. Saves real
  time on a big app; adds a build-setting to explain to everyone else.
- **figma-export** (RedMadRobot) if the designer lives in Figma and there is one
  platform; **Style Dictionary** if there are two or more and tokens should be
  generated from one JSON.

# The codemod — moving an existing app onto the scale

Loaded on demand: read this when actually migrating literals, not when writing
a new component.

Hand-editing hundreds of call sites is where a design-system migration dies —
half done, half not, and no one can say which half. Write the codemod, keep it
in the repo, and let it carry the rounding rule so the rule is readable instead
of folklore. One real run: **991 substitutions across 31 files**, in one pass,
with the app building after each family.

## What it may touch, and what it must not

| Rewritten | Left alone |
|---|---|
| `.padding(12)`, `.padding(.horizontal, 6)` | `.frame(width: 240)` — a size, not a gap |
| `spacing: 14` | `.offset(x: 3)` |
| `cornerRadius: 18` | `lineWidth: 1.5` |
| `.font(.system(size: 13, weight: .semibold))`, `.font(.caption)` | `.shadow(radius: 16)` |
| `.spring(response:dampingFraction:)`, short `.easeOut/.easeInOut/.linear` | decorative/long curves (0.35s+, 60s turns) |
| `RoundedRectangle(cornerRadius: X, style: .continuous)` | a computed radius (`radius * 0.5`) |

A `frame` is the size of a thing; a `padding` is the space around it. Rounding
the first changes the design, rounding the second aligns it.

## The rounding rule

```python
SPACE = [(2,"Space.hair"),(4,"Space.xs"),(8,"Space.sm"),(12,"Space.md"),
         (16,"Space.lg"),(20,"Space.xl"),(24,"Space.xxl"),(32,"Space.xxxl"),
         (48,"Space.huge")]

def nearest(value, table):
    if value > 56:            # past the scale it is a size, not a gap
        return None
    # TIES GO UP: 6 is equidistant from 4 and 8, 10 from 8 and 12. Rounding
    # down tightens a third of the app by two points at once, and the layout
    # that was already snug is the one that breaks. Air is the safe direction.
    step, name = min(table, key=lambda p: (abs(p[0] - value), -p[0]))
    return name if abs(step - value) <= 6 else None
```

## Font bounds are 9…26, deliberately

```python
def font_step(size, weight):
    if size < 9 or size > 26:
        return None          # a mark, or an illustration glyph — not type
    strong = weight in {"semibold","bold","heavy","black"}
    if size <= 10:   return "caption"
    if size <= 12.5: return "label" if strong else "caption"
    if size <= 14.5: return "calloutStrong" if strong else "callout"
    if size <= 16.5: return "bodyStrong" if strong else "body"
    if size <= 19:   return "headline"
    return "title"
```

Below nine points the number is a *mark*: a day number on a calendar ring, a
tick's label inside a `Canvas`. The scale's smallest step would double it.
Above ~26 it is nearly always `Image(systemName:)` standing in for an
illustration — a 64pt permission glyph, a 72pt launch ring.

**Have a `*Strong` step for every tier the app actually bolds.** Without one the
script picks the nearest step and a human bolts `.fontWeight(.semibold)` on top
— a step followed immediately by an override of the step. Three of those
appeared in one file the first time this ran.

## Springs by shape, not by number

```python
if damping < 0.7:      name = "release"   # that bounce is its character
elif response >= 0.38: name = "settle"    # a panel arriving at a stop
else:                  name = "slide"     # something small changing place
```

Twenty-one distinct spring spellings existed before this; nobody chose
twenty-one springs. Easing folds the same way: 0.12–0.26s → `fade`, a
0.25–0.35s `linear` → `progress`, everything longer is doing something specific
and stays.

## How to run it

```bash
python3 scripts/design_migrate.py            # report only
python3 scripts/design_migrate.py --write    # apply
```

Read the report before writing — the font lines especially, since a 13pt label
that was deliberately smaller than its neighbour becomes the same step as that
neighbour. Usually that is the point. Occasionally it is not.

Build after each family, and **keep the script**: the pre-commit guard's
warning should name it, which makes it live tooling rather than an orphan.

## Skip list

Exclude by path, and say why in the code:

- the design system's own directory (it defines the scale)
- generated bindings (uniffi/protobuf output)
- anything whose points are geometry, not layout — Metal vertex code, `Canvas`
  paths drawn to their own design grid, a logo mark built on a 52-point canvas
  where every number is relative

#!/usr/bin/env python3
"""Put every literal gap, corner and font in the views onto the design scale.

Counted before this ran: 27 distinct padding values, 19 spacings, 23 corner
radii and 48 font spellings across 17 900 lines of SwiftUI. None of them was
chosen against the others — each was chosen once, on its own screen.

This script does the mechanical half of the move, and only the mechanical half:

  .padding(9)            -> .padding(Space.sm)
  spacing: 14            -> spacing: Space.lg
  cornerRadius: 18       -> cornerRadius: Radii.lg
  .font(.system(size: 13, weight: .semibold))  -> .font(TypeScale.callout)…

Rounding is to the nearest 4-point step, with 2 kept as the one half step (a
hairline, or the gap inside a single object). A value that rounds to something
a person would notice — a 40-point frame becoming 48 — is left alone: this only
ever touches padding, spacing and corner radius, never `frame`, `offset`,
`lineWidth` or a shadow's radius.

  python3 scripts/design_migrate.py            # report what would change
  python3 scripts/design_migrate.py --write    # change it

Read the report before writing. The fonts in particular are a judgement — a
13-point label that was deliberately smaller than its neighbour becomes the
same step as that neighbour, which is usually the point and occasionally not.
"""

from __future__ import annotations

import argparse
import pathlib
import re
import sys
from collections import Counter

# Where the views live. Given on the command line, because this script belongs
# to the skill rather than to any one app.
VIEWS = pathlib.Path()

# Files this must not touch, and why.
SKIP = {
    "Design",  # the scale itself
    "Generated",  # uniffi output
    "Cylinder",  # Metal geometry — points here are vertex coordinates
    "L2FIcons.swift",  # Canvas paths drawn to a 24-unit design grid
    "MakeMark.swift",  # the mark's own 52-point canvas, every number relative
}

# 4-point steps, and the one half step at 2.
SPACE = [
    (2, "Space.hair"),
    (4, "Space.xs"),
    (8, "Space.sm"),
    (12, "Space.md"),
    (16, "Space.lg"),
    (20, "Space.xl"),
    (24, "Space.xxl"),
    (32, "Space.xxxl"),
    (48, "Space.huge"),
]
RADII = [
    (2, "Radii.hair"),
    (4, "Radii.xs"),
    (8, "Radii.sm"),
    (12, "Radii.md"),
    (16, "Radii.lg"),
    (24, "Radii.xl"),
    (36, "Radii.xxl"),
]


def nearest(value: float, table) -> str | None:
    """The step closest to `value`, or None when nothing is close enough.

    Past 48 the scale stops and the number is a size rather than a gap — a
    300-point sheet height is not a padding that drifted."""
    if value > 56:
        return None
    # Ties go **up**: 6 is equidistant from 4 and 8, and 10 from 8 and 12.
    # Rounding down there would tighten a third of the app by two points at
    # once, and a layout that was already snug is the one that breaks. Air is
    # the safer direction — `-pair[0]` makes the larger step win a tie.
    step, name = min(table, key=lambda pair: (abs(pair[0] - value), -pair[0]))
    # More than a step and a half away means this was not a gap on any scale —
    # leave it and let a person look at it.
    return name if abs(step - value) <= 6 else None


NUM = r"(\d+(?:\.\d+)?)"

PADDING = re.compile(r"\.padding\((\.\w+,\s*)?" + NUM + r"\)")
SPACING = re.compile(r"\bspacing:\s*" + NUM + r"\b")
CORNER = re.compile(r"\bcornerRadius:\s*" + NUM + r"\b")

# `.spring(response: 0.34, dampingFraction: 0.78)` and friends. 21 distinct
# spellings across 12 files before this ran — nobody chose twenty-one springs.
SPRING = re.compile(
    r"\.spring\(response: " + NUM + r", dampingFraction: " + NUM + r"\)"
)
# The easing curves that are one of the two named ones. Anything longer than a
# third of a second is doing something specific (a decorative drift, a 60s
# turn) and is left alone.
EASING = re.compile(r"\.(easeOut|easeInOut)\(duration: " + NUM + r"\)")
LINEAR = re.compile(r"\.linear\(duration: " + NUM + r"\)")
# `RoundedRectangle(cornerRadius: X, style: .continuous)` — 41 spellings in 12
# files. `Radii.shape(_:)` is the same thing and is always `.continuous`.
ROUNDED = re.compile(
    r"RoundedRectangle\(cornerRadius: ([A-Za-z0-9_.]+)(, style: \.continuous)?\)"
)

# .font(.system(size: 13, weight: .semibold, design: .rounded))
FONT_SIZED = re.compile(
    r"\.font\(\.system\(size:\s*"
    + NUM
    + r"(?:,\s*weight:\s*\.(\w+))?(?:,\s*design:\s*\.(\w+))?\)\)"
)
# .font(.caption) and friends
FONT_STYLE = re.compile(
    r"\.font\(\.(caption2|caption|footnote|subheadline|headline|body|callout|title3|title2|title|largeTitle)\)"
)

STYLE_MAP = {
    "caption2": "caption",
    "caption": "caption",
    "footnote": "callout",
    "subheadline": "body",
    "body": "body",
    "callout": "callout",
    "headline": "headline",
    "title3": "title",
    "title2": "title",
    "title": "title",
    "largeTitle": "display",
}

HEAVY = {"semibold", "bold", "heavy", "black"}


def font_step(size: float, weight: str | None) -> str | None:
    """Which step a fixed size belongs to, or None to leave it alone.

    Weight decides between the two steps that share a size: 12 semibold is a
    control's name (`label`), 11 regular is a caption under a thumbnail.

    **Only 9…26 is text.** Below nine the number is a mark rather than a word —
    a day number on the calendar ring, a tick's label — and the scale's
    smallest step would double it. Above twenty-six it is almost always an
    `Image(systemName:)` standing in for an illustration: the permission
    screen's 64-point photo glyph, the launch screen's 72-point ring. Both ends
    are sizes, not type, and neither belongs on a text scale."""
    if size < 9 or size > 26:
        return None
    strong = weight in HEAVY
    if size <= 10:
        return "caption"
    if size <= 12.5:
        return "label" if strong else "caption"
    if size <= 14.5:
        return "callout"
    if size <= 16.5:
        return "bodyStrong" if strong else "body"
    if size <= 19:
        return "headline"
    return "title"


def convert(text: str, tally: Counter) -> str:
    def pad(m: re.Match) -> str:
        edge, raw = m.group(1) or "", float(m.group(2))
        name = nearest(raw, SPACE)
        if not name:
            return m.group(0)
        tally[f"padding {raw:g} -> {name}"] += 1
        return f".padding({edge}{name})"

    def space(m: re.Match) -> str:
        raw = float(m.group(1))
        if raw == 0:
            return m.group(0)
        name = nearest(raw, SPACE)
        if not name:
            return m.group(0)
        tally[f"spacing {raw:g} -> {name}"] += 1
        return f"spacing: {name}"

    def corner(m: re.Match) -> str:
        raw = float(m.group(1))
        name = nearest(raw, RADII)
        if not name:
            return m.group(0)
        tally[f"radius {raw:g} -> {name}"] += 1
        return f"cornerRadius: {name}"

    def sized(m: re.Match) -> str:
        raw, weight = float(m.group(1)), m.group(2)
        # A size computed from something else (`size * 0.28`) never matches
        # this pattern, so anything here is a literal.
        step = font_step(raw, weight)
        if step is None:
            tally[f"font {raw:g} — left alone (a size, not type)"] += 1
            return m.group(0)
        tally[f"font {raw:g}{'/' + weight if weight else ''} -> {step}"] += 1
        return f".font(TypeScale.{step})"

    def styled(m: re.Match) -> str:
        step = STYLE_MAP[m.group(1)]
        tally[f"font .{m.group(1)} -> {step}"] += 1
        return f".font(TypeScale.{step})"

    def spring(m: re.Match) -> str:
        response, damping = float(m.group(1)), float(m.group(2))
        # Three questions, in order. A loose spring is a *release* whatever its
        # response — that bounce is the whole character of it. A slow one is a
        # panel arriving at a stop. Everything else is a small thing moving.
        if damping < 0.7:
            name = "release"
        elif response >= 0.38:
            name = "settle"
        else:
            name = "slide"
        tally[f"spring {response:g}/{damping:g} -> Motion.{name}"] += 1
        return f"Motion.{name}"

    def easing(m: re.Match) -> str:
        seconds = float(m.group(2))
        # Only the short ones. Past 0.3s an ease is doing something particular
        # — a wheel settling, a colour drifting — and a named "fade" would be
        # a lie about what it is.
        if not 0.12 <= seconds <= 0.26:
            return m.group(0)
        tally[f"{m.group(1)} {seconds:g}s -> Motion.fade"] += 1
        return "Motion.fade"

    def linear(m: re.Match) -> str:
        seconds = float(m.group(1))
        if not 0.25 <= seconds <= 0.35:
            return m.group(0)
        tally[f"linear {seconds:g}s -> Motion.progress"] += 1
        return "Motion.progress"

    def rounded(m: re.Match) -> str:
        radius = m.group(1)
        # A computed radius (`radius * 0.5`) never matches — the pattern takes
        # one identifier or number, so what is rewritten is always a token.
        tally[f"RoundedRectangle({radius}) -> Radii.shape"] += 1
        return f"Radii.shape({radius})"

    text = PADDING.sub(pad, text)
    text = SPACING.sub(space, text)
    text = CORNER.sub(corner, text)
    text = FONT_SIZED.sub(sized, text)
    text = FONT_STYLE.sub(styled, text)
    text = SPRING.sub(spring, text)
    text = EASING.sub(easing, text)
    text = LINEAR.sub(linear, text)
    text = ROUNDED.sub(rounded, text)
    return text


def main() -> int:
    ap = argparse.ArgumentParser(description=__doc__.splitlines()[0])
    ap.add_argument(
        "--views", required=True, help="the directory of SwiftUI views to migrate"
    )
    ap.add_argument("--write", action="store_true", help="apply the changes")
    ap.add_argument("paths", nargs="*", help="limit to these files")
    args = ap.parse_args()
    global VIEWS
    VIEWS = pathlib.Path(args.views)

    files = (
        [pathlib.Path(p) for p in args.paths]
        if args.paths
        else sorted(VIEWS.rglob("*.swift"))
    )
    tally: Counter = Counter()
    touched = 0

    for path in files:
        if any(part in SKIP for part in path.parts):
            continue
        before = path.read_text()
        after = convert(before, tally)
        if after == before:
            continue
        touched += 1
        if args.write:
            path.write_text(after)

    for change, count in sorted(tally.items(), key=lambda kv: -kv[1]):
        print(f"{count:4}  {change}")

    # A left-alone literal is not a substitution, and counting it as one is how
    # a finished migration reports "23 substitutions" and reads as unfinished.
    # The two numbers answer different questions: what changed, and what the
    # codemod deliberately refused to touch.
    skipped = sum(c for change, c in tally.items() if "left alone" in change)
    changed = sum(tally.values()) - skipped
    print(
        f"\n{changed} substitutions in {touched} files"
        f"{f', {skipped} literals left alone' if skipped else ''}"
        f"{'' if args.write else ' (dry run — pass --write)'}"
    )
    return 0


if __name__ == "__main__":
    sys.exit(main())