duo-lint
The fold linter for iPhone Duo, Apple's foldable with an outer display and an inner display. Run it to find code Apple says to remove before an app runs on the foldable; it reports each finding with t
SKILL.mdplugins/duology-ship/skills/duo-lint/SKILL.md
GitHubduo-lint
duo-lint scans Swift (and optionally Objective-C) code, Info.plist files and build settings for patterns that break on iPhone Duo. Each finding names the rule, the code, a fix and the Apple page behind it.
It is one Python 3 file with no dependencies. It runs locally and sends nothing anywhere.
Most rules come from Step 2 of Apple's Three steps to make your app shine on iPhone Duo. Xcode 27.1 also ships an App Resizability agent skill that looks for the same patterns (prepare page). duo-lint doesn't replace it. Use duo-lint where you need a repeatable check: CI, the lint hook, or another coding agent.
duo-lint reads code. It can't see the screen. For a full iPhone Duo audit, run /duo-audit (in the duology-ship plugin): it runs duo-lint, then the 15-point duo-design-review checklist on screenshots from the Duo simulator, and ranks everything in one list. Without Claude Code, run duo-lint, then follow the duo-design-review skill.
Related skills: duo-layout (size classes, reserved regions, arrangements), duo-continuity (state through a fold), duo-testing (tests on the Duo simulator).
Run it
The command depends on how you installed this skill:
| Installed with | Run |
|---|---|
The duology-ship plugin in Claude Code |
duo-lint. The plugin puts its bin/ folder on the Bash tool's PATH. |
npx skills add, or copied by hand |
<skill-folder>/scripts/duo-lint. <skill-folder> is the folder that holds this SKILL.md. |
In Claude Code, <skill-folder> is ${CLAUDE_SKILL_DIR}. If duo-lint is not found or not allowed, run ${CLAUDE_SKILL_DIR}/scripts/duo-lint instead. If scripts/duo-lint can't be executed, run python3 <skill-folder>/scripts/duo-lint.py. The examples below say duo-lint; use the script path when the plugin isn't installed.
# Whole project
duo-lint .
# One folder or file
duo-lint Sources/Feed/FeedView.swift
# With the fix and the Apple link under each finding
duo-lint -v Sources/
In folders it skips build/, DerivedData/, Pods/, Carthage/, .build/, SourcePackages/, .claude/, .agents/ and its own tests/fixtures/, wherever this skill is installed. Name a skipped folder on the command line to check it anyway.
It needs Python 3.9 or later. On a Mac with Xcode 27.1, /usr/bin/python3 is Xcode's Python 3.9, which is enough.
| Option | What it does |
|---|---|
PATH ... |
Files or folders. Default: the current folder. |
-v, --verbose |
Prints fix: and see: lines under each finding. |
--json |
JSON output. Same as --format json. |
--format github |
GitHub Actions annotations. |
--strict |
Exit 1 on warnings too, not only errors. |
--objc |
Also scan .m, .mm and .h files in folders. Files you name are always scanned. |
--select DUO001,DUO004 |
Run only these rules. |
--ignore DUO007 |
Skip these rules. |
--exclude 'Tests/*' |
Skip matching paths. Repeat it for more patterns. |
--list-rules |
Print the rules. Add --json for machine-readable output. |
Exit codes: 0 no errors, 1 errors (or any finding with --strict), 2 a bad option or a missing path.
Read the output
Real output on the four-file sample in tests/fixtures/sample, run from that folder:
$ duo-lint Sources/
Sources/App/RootView.swift:7 DUO004 warning userInterfaceIdiom == .pad layout picked by device type; pick it by size class or space
Sources/Feed/FeedView.swift:8 DUO001 error UIScreen.main.bounds your window is not the screen on a two-display phone; size from the view or window
Sources/Player/Controls.swift:9 DUO007 warning frame(width: 390) fixed width of 320 pt or more; let the container size it
Sources/Settings/SettingsView.swift:6 DUO009 warning <= 667 GeometryReader size compared to a device size; use size class or ViewThatFits
4 findings · 1 error · 3 warnings (4 files checked)
Each line is path:line RULE severity code message. The last line counts findings and files.
- error: an API the SDK already deprecates and Apple tells you to remove. Fix it.
- warning: a pattern that is almost always wrong on iPhone Duo. Fix it, or silence it with a reason if the code is not about layout.
--json gives each finding as an object with path, line, column, rule, name, severity, snippet, message, fix, source (an Apple URL) and code (the source line). Use it when you need to sort or group findings.
Fix each finding
| Rule | Severity | Catches | Fix |
|---|---|---|---|
| DUO001 | error | UIScreen.main, UIScreen.screens, .main where the file shows Swift infers UIScreen |
view.bounds, GeometryReader, onGeometryChange; traitCollection.displayScale; UIWindow(windowScene:) |
| DUO002 | warning | UIDevice.current.orientation, its notification, effectiveGeometry.interfaceOrientation, an interfaceOrientation whose owner it can't see |
Compare width with height. Camera: AVCaptureDevice.RotationCoordinator. |
| DUO003 | error | statusBarOrientation, interfaceOrientation on a UIWindowScene or view controller |
Compare width with height. |
| DUO004 | warning | userInterfaceIdiom compared with .pad or .phone |
Size class, NavigationSplitView, ViewThatFits. |
| DUO005 | warning | horizontalSizeClass == .regular next to "iPad" |
Treat regular as "wide", not as iPad. |
| DUO006 | warning | bounds.height == 844, lists of device sizes |
Size class, ViewThatFits, width vs height. |
| DUO007 | warning | .frame(width: 390), width constraints of 320 pt or more |
.frame(maxWidth:), containerRelativeFrame, readable content guide. |
| DUO008 | warning | UIRequiresFullScreen = true |
Remove it, or add UIRequiresFullScreenIgnoredStartingWithVersion. |
| DUO009 | warning | proxy.size.width == 393 |
Width vs height, size class, even column counts. |
Bad and good code for every rule, with the Apple source: references/rules.md.
The three fixes you will write most often:
import SwiftUI
// DUO001, DUO002, DUO003, DUO009: size from the space you have.
struct MediaScreen: View {
var body: some View {
GeometryReader { proxy in
let isWide = proxy.size.width > proxy.size.height
let layout = isWide ? AnyLayout(HStackLayout()) : AnyLayout(VStackLayout())
layout {
Color.black
Text("Up next")
}
}
}
}
// DUO004, DUO005: pick the layout by size class, and name it after the space.
struct InboxScreen: View {
@Environment(\.horizontalSizeClass) private var sizeClass
var body: some View {
let isWide = sizeClass == .regular
Text(isWide ? "List and message side by side" : "List, then message")
}
}
// DUO007: cap a width instead of fixing it.
struct PromoBanner: View {
var body: some View {
Text("Try the new editor")
.frame(maxWidth: 600)
.padding()
}
}
AnyLayout keeps view identity when the layout switches, so state survives the fold (AnyLayout).
Workflow
- Run
duo-lint -v .from the project root (or the script path, see Run it). Add--objcfor mixed projects. - Fix every error first. They are deprecated APIs. If one is a bare
.mainon your own type, notUIScreen, silence it with a reason. - Fix the warnings, one rule at a time. Read the rule in references/rules.md before changing code you don't own.
- Re-run until the summary shows
0 errors. Aim for0 findings. - Silence only code that is not layout, with a reason (see below). Never silence a finding just to get a clean run.
- Build with Xcode 27.1 and check the screens on the iPhone Duo simulator, closed and open. A clean lint does not prove the layout works.
- Report what you changed, and any finding you silenced, with its reason.
Silence a finding on purpose
import UIKit
@MainActor
func crashReportScale() -> CGFloat {
// duo-lint:disable-next-line DUO001 -- crash reports need the device scale, not layout
UIScreen.main.scale
}
// duo-lint:disable-next-line DUO001skips that rule on the next line.// duo-lint:disable-line DUO001skips it on the same line.// duo-lint:disable-file DUO004skips it in the whole file.- No rule id means every rule. Name the rule anyway.
- In a plist:
<!-- duo-lint:disable-next-line DUO008 -->.
In CI
# .github/workflows/duo-lint.yml
name: duo-lint
on: [pull_request]
jobs:
lint:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- run: python3 tools/duo-lint/duo-lint.py --format github --strict .
Copy scripts/duo-lint.py into the repo first (the path above is an example). The linter is plain Python, so a Linux runner is fine. GitHub shows each finding as an annotation on the pull request. Drop --strict to fail only on errors.
The lint hook (Claude Code)
The duology-ship plugin has an optional hook. After Claude edits or writes a .swift file, it runs duo-lint on that file and passes the findings back to Claude, with the fix for each. It never blocks an edit.
- It is off by default. Turn it on with
export DUOLOGY_LINT_HOOK=1before you start Claude Code. Unset it to turn it off. - After an edit, it reports only findings in the lines that changed, plus a count of the rest of the file. After a full write, it reports the whole file (up to 15 findings).
- It stays silent when there is nothing to report, when the file isn't Swift, and when Python 3 is missing.
- Files:
hooks/hooks.jsonandhooks/lint-hook.shin the plugin.
When the hook reports a finding, fix it in your next edit, or silence it with a reason if the code is not layout.
What it doesn't catch
duo-lint finds patterns in code. It can't see controls sitting in the fold, state lost on a fold, a UIScreen kept in a property, sizes read once at launch, or window bounds used as the screen size. The full list is at the end of references/rules.md. For what only a screenshot shows, run /duo-audit or the duo-design-review checklist.
duo-lint reads text, not types. So these are heuristics: DUO001 on a bare .main (it looks for UIScreen in the file), the split between DUO003 and DUO002, and DUO004, DUO005 and DUO006. They can flag code that is fine, and miss code that hides a device size or type behind a name. references/rules.md says how each one decides. Read each finding before you change it.
Checklist
- Ran
duo-lint -von the whole project (with--objcif it has Objective-C). - Fixed every error (DUO001, DUO003).
- Fixed or justified every warning; each silenced line has a
-- reason. - Re-ran duo-lint:
0 errorsin the summary. - If the app set
UIRequiresFullScreen: removed it, or addedUIRequiresFullScreenIgnoredStartingWithVersion. - Built with Xcode 27.1 and looked at the changed screens on the iPhone Duo simulator, closed and open.
- Told the user which findings were fixed, which were silenced, and why.