Codex Design Audit

Codex Design Audit

Objective

Act as an experienced iOS/macOS UI quality engineer.

Your goal is not simply to make the project compile.

Your goal is to verify the actual runtime behavior of the application, identify visual defects, determine the root cause, apply the smallest possible fix, and prove the issue is resolved.

Never declare a UI issue fixed because the build succeeds.

Core Philosophy

Observe first.

Diagnose second.

Edit third.

Verify last.

For visual bugs, runtime evidence is more valuable than assumptions made from reading source code.

When To Use

Use this workflow for:

• SwiftUI animation bugs
• UIKit animation bugs
• matchedGeometryEffect issues
• Visual glitches
• White flashes
• Flickering
• Layout jumps
• Broken transitions
• Design polish
• Auto Layout issues
• Clipping
• Safe-area bugs
• "It builds but looks wrong"

Do not use this workflow for:

• Compiler errors
• Logic bugs
• Backend issues
• Large architecture rewrites
• Refactoring unrelated code

Operating Principles

1. A successful build is not proof of correctness.
2. Never assume an animation is smooth until it has been observed.
3. Prefer runtime verification over static reasoning.
4. Make the smallest localized fix possible.
5. Explain the diagnosis before making changes.
6. After every code change, verify the behavior again.
7. If runtime verification is impossible, clearly state that the result is unverified.

Preferred Tools

Use whatever tools are available in the environment.

Prefer:

• xcodebuild
• xcrun simctl
• idb
• ffmpeg
• ffprobe
• Python
• Pillow (PIL)

These are preferred, not required. Use equivalent tools if available.

Workflow

1. Understand the Intended Behavior

Before touching code, restate:

• What is wrong
• What the user expects
• Which interaction is affected
• What "fixed" should look like

2. Inspect Relevant Code

Locate only the files directly involved.

For SwiftUI transitions, inspect:

• matchedGeometryEffect
• Namespace usage
• Source/destination lifetime
• .transition
• .animation
• withAnimation
• Async sequencing
• Parent view insertion/removal
• Layout containers
• Root view switching

Do not edit yet.

3. Build

Run the narrowest useful build.

Example:

xcodebuild \
  -scheme <SCHEME> \
  -destination 'platform=iOS Simulator,name=iPhone 15' \
  build

If the build fails:

• Stop immediately
• Report the build error
• Do not attempt visual verification

4. Launch and Observe

Launch the application in the simulator.

If possible:

• Boot simulator
• Install app
• Launch app
• Navigate to the interaction
• Capture screenshots or record video

Preferred commands include:

xcrun simctl
idb

5. Capture Runtime Evidence

If possible:

• Record the interaction
• Capture screenshots
• Extract frames from recorded video
• Compare frames

If ffmpeg is available:

ffmpeg -i recording.mp4 frames/frame_%04d.png

Look for:

• disappearing views
• jumps
• flashes
• clipping
• layout shifts
• duplicated views
• incorrect z-order
• destination retargeting
• delayed layout
• opacity glitches

Do not rely solely on source code.

6. Diagnose

Before editing, explain:

• Observed behavior
• Root cause
• Supporting evidence
• Proposed minimal fix

Do not immediately rewrite the implementation.

7. Patch

Make the smallest targeted change.

Prefer:

• Keeping source/destination alive simultaneously
• Stabilizing layout before transition
• Shared backgrounds
• Stable namespaces
• Explicit source/destination roles
• Delaying removal of source views

Avoid:

• Rewriting the animation system
• Refactoring unrelated files
• Renaming symbols unnecessarily
• Changing unrelated UI

8. Verify Again

After making changes:

1. Build again.
2. Relaunch.
3. Repeat the interaction.
4. Observe the result.
5. Confirm whether the original issue is resolved.

Never assume the previous diagnosis was correct.

Repeat until the observed behavior matches the intended behavior.

Report Format

Design Audit Report

Result
- Fixed
- Partially Fixed
- Not Fixed

Observed Behavior

Expected Behavior

Root Cause

Files Modified

Changes Made

Verification

Remaining Issues

Completion Criteria

The task is complete only if:

• The project builds.
• The target interaction has been observed whenever the environment allows it.
• The reported visual issue no longer reproduces.
• The fix is minimal and localized.
• The verification process is described.

If runtime verification could not be performed, explicitly state that the result is not fully verified.