Guidance-driven skill plus a small deterministic CLI that audits macOS SwiftUI / AppKit cross-screen consistency, reports with evidence, and repairs only clear accidental app-owned drift. Deterministic tooling plus a native SwiftPM fixture. No benchmarks claimed.
In scope: whole-window relationships, shared shells and page families, pane-local keylines, control appearance, state transitions, optical hierarchy, declared numeric contracts compared against supplied measurements, eligible repairs of accidental app-owned drift with before/after verification.
Out of scope: universal Swift rewriting, screenshot parsing or automated keyline measurement, exhaustive scanning or coverage proof, built-in XCUI adapter, repositioning native titlebar / toolbar / traffic lights / safe areas, normalizing intentional variants. Examples are synthetic and illustrative, not Apple requirements.
Example contract (app-decided, fixture-regular, pane-local pt; 24 is
the app choice, not a platform value):
| Surface | contentTitle.leading |
Contract | Result |
|---|---|---|---|
| albums | 24.0 pt | 24.0 pt ± 0.5 | pass |
| tracks | 24.0 pt | 24.0 pt ± 0.5 | pass |
| playlists | 32.0 pt | 24.0 pt ± 0.5 | fail (delta 8.0) |
- Skill — entrypoint, progressive disclosure.
- Discovery, layout contracts, verification, window adaptation, whole-window review, data format (normative CLI JSON schema).
- CLI — stdlib-only
scan,compare,report. - Contracts, measurements, expected comparison — synthetic repo-root samples.
- Tests —
unittestsuite. - Validation scope — exercised behavior and remaining limits.
- Fixture — seeded native demo app.
- Scenarios — checks and negative controls.
- Transfer cases — contrasting tasks plus adversarial majority-wrong case; results are recorded in validation.
- Provenance, contributing.
Python 3.10+ stdlib only for CLI and tests. Swift toolchain only for the
optional fixture on macOS. Any skill-compatible host that can load SKILL.md.
Clone, then copy the skill into one host directory you use. Never overwrites.
For Codex, use ~/.codex/skills/macos-ui-consistency as the canonical
installation. Codex may also discover a copy in ~/.agents/skills; installing
both can create duplicate entries. A checkout of this repository is the source,
not another global installation.
git clone https://github.com/Niko96-dotcom/macos-ui-consistency.git
SRC="macos-ui-consistency/skills/macos-ui-consistency"
DEST="$HOME/.codex/skills/macos-ui-consistency"
SHARED="$HOME/.agents/skills/macos-ui-consistency"
if [ -e "$DEST" ] || [ -L "$DEST" ]; then
echo "exists, leaving untouched: $DEST"
elif [ -e "$SHARED" ] || [ -L "$SHARED" ]; then
echo "shared installation exists; choose one Codex location before copying: $SHARED"
else
mkdir -p "$(dirname "$DEST")"
cp -R "$SRC" "$DEST"
fiFor Claude Code, use $HOME/.claude/skills/macos-ui-consistency as the destination. Use the appropriate skill folder for other hosts. Or point the host at the
checked-out skills/macos-ui-consistency/SKILL.md with no install.
For an authorized update of an existing copy, compare it with the checkout
first and back it up outside the skill directory. Update the entrypoint,
references, scripts, and agent metadata together; copying only SKILL.md
can leave the host running an older schema. Preserve deliberate host-only
frontmatter such as Claude's argument-hint. Verify file hashes against the
source afterward (compare the entrypoint body separately if frontmatter
has an adapter field), and run a sample comparison through the installed
script. Do not remove unknown host-local files or copy __pycache__.
Load skills/macos-ui-consistency/SKILL.md in the host. Default invocation
audits and applies only eligible repairs within the current authorization;
an explicit audit-only, review, or planning request forbids all app edits.
$macos-ui-consistency audit native Mac UI across all known pages and fix eligible drift.
$macos-ui-consistency audit-only review of native Mac UI across all known pages. Do not edit anything.
Family-only contracts remain version 1 compatible. Contracts version 2 adds
explicit window and component scopes selecting named surfaces across
families; absent targets are unverified. Measurements and outputs stay version 1.
Older CLIs reject version 2 contracts instead of ignoring the new scope. Details in the
data format.
Existing outputs are refused unless --force; symlinked outputs are refused.
mkdir -p .audit
python3 skills/macos-ui-consistency/scripts/ui_consistency.py scan fixture/Sources --output .audit/candidates.json
if python3 skills/macos-ui-consistency/scripts/ui_consistency.py compare examples/contracts.json examples/measurements.json --output .audit/comparison.json; then
echo "pass"
else
compare_status=$?
if [ "$compare_status" -eq 1 ]; then echo "fail by design: see .audit/comparison.json"; else exit "$compare_status"; fi
fi
python3 skills/macos-ui-consistency/scripts/ui_consistency.py report .audit/comparison.json --output .audit/report.mdThe sample playlists entry fails by design, so compare exits 1:
0 pass, 1 fail, 2 invalid input or I/O, 3 unverified without fail.
scan emits heuristic candidates only, never coverage proof. compare
checks supplied numbers only, not screenshots or taste.
Installed layout: resolve scripts relative to the loaded SKILL.md, e.g.
SKILL_DIR is the directory containing it, then
python3 "$SKILL_DIR/scripts/ui_consistency.py" scan . --output .audit/candidates.json.
See the fixture for the exact target. It seeds one accidental keyline drift plus intentional variants that stay excluded.
swift build --package-path fixture
swift run --package-path fixture ConsistencyFixture --page playlists
swift run --package-path fixture ConsistencyFixture --page playlists --aligned
swift run --package-path fixture ConsistencyFixture --page playlists --compact--aligned shows the reference layout mode. --compact starts at the
fixture-specific 560×450-point content minimum. Optional panes yield as the
window narrows, navigation remains available, and Inspector uses a sheet when
there is insufficient pane space. See the window adaptation research
and fixture policy; these dimensions are not Apple-wide rules.
python3 -m unittest discover -s tests -v| Seeded reference | Aligned reference |
|---|---|
 |
 |
Compact composition (native menu picker, secondary actions under More):
Tested minimum after an attempted drag below the supported size:
The seeded/aligned pair records the initial title-inset example; the compact and minimum images show the subsequent window-policy revision. Reference captures from the fixture on the verified host below. The sheet dismisses with Return.
- 55 Python tests pass locally, including explicit shared scopes, missing targets, ownership/evidence gates, and byte-identical legacy output.
- Native fixture built with Swift 6.3.3 on macOS 26; seeded and aligned modes visually inspected, sheet Return dismissal checked. Compact navigation, inspector controls, and scrolling checked; long description truncation at minimum width remains a documented fixture limitation.
- GitHub CI runs
unitteston Ubuntu Python 3.10 / 3.13 and compiles the fixture on macOS 14. The live badge above links to hosted results. - First scored eval runs live on macOS (S1–S6 and S8 pass, S7 conditional pass with About-expand blocked; transfer cases 1–5 pass incl. a blinded adversarial run; true drags clamp; shortcuts/Escape/Return proven, Tab-order and VoiceOver-announcement open). Full evidence: validation.
Shipped: heuristic Swift candidate scan, declared numeric contract compare, Markdown report, six guidance checks, seeded fixture, eval scenarios. Not shipped: screenshot parsing, universal auto-patcher, exhaustive coverage proof, built-in XCUI adapter. Instrumented probe unimplemented.
MIT.