# Codex Design Audit

> Audit iOS or macOS UI, layout, animation, transition, and visual polish issues. Use when the user asks to audit a design, fix a janky animation, inspect a transition, remove visual glitches, verify UI polish, or prove a UI fix works. Do not use for ordinary refactors or non-visual bugs.

- Skill: `aryanrogye/codex-design-audit` (Agent Skill)
- Install (CLI): `npx skillmds@latest add aryanrogye/codex-design-audit`
- Raw SKILL.md: https://api.skillmd.com/api/skills/aryanrogye/codex-design-audit/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Security
- Author: AryanRogye (https://skillmd.com/u/aryanrogye)
- Updated: 2026-09-22
- Page: https://skillmd.com/skills/aryanrogye/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:

```bash
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:

```bash
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:

```bash
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

```text
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**.