UI Enhancer Radar

Quick Ref: Screenshot + code analysis of any iOS/SwiftUI view. Design intent interview (sacred elements, aggressiveness), 14-domain analysis with layout reorganization, Color Audit (adaptive Color Profile), iPad Sheet Sizing caller-side audit, Button Hit Region three-factor audit, and Silent Picker menu-presentation audit, element compaction (compact vs remove vs keep), cross-view consistency checks, design-aware refinement with push-back and App Store guardrails, incremental apply with revert safety (git or file backup), visual verification guidance, and files-changed summary.

You are performing a systematic UI enhancement on a specific iOS/SwiftUI view, analyzing both the visual screenshot and the underlying code, then implementing improvements with tests.

Required output: Every finding MUST include a severity rating (Critical / High / Medium / Low) and estimated implementation effort (Trivial / Small / Medium / Large).

Quick Commands

Command	Description
/ui-enhancer-radar	Full audit with interview
/ui-enhancer-radar space	Space efficiency analysis only
/ui-enhancer-radar hierarchy	Visual hierarchy analysis only
/ui-enhancer-radar density	Information density analysis only
/ui-enhancer-radar interaction	Interaction patterns analysis only
/ui-enhancer-radar accessibility	Accessibility audit only
/ui-enhancer-radar hig	HIG compliance check only
/ui-enhancer-radar dark-mode	Dark mode audit only
/ui-enhancer-radar performance	Performance impact analysis only
/ui-enhancer-radar design-system	Design system compliance only
/ui-enhancer-radar color	Color audit only (inventory, flatness, consistency)
/ui-enhancer-radar ipad-sheets	iPad sheet sizing audit only (caller-side .sheet() check)
/ui-enhancer-radar hit-region	Button hit region audit only (three-factor: .plain + Form/List + trailing chevron)
/ui-enhancer-radar silent-picker	Silent Picker audit only (menu Picker, no .pickerStyle, custom non-Form container)
/ui-enhancer-radar compare	Compare before/after screenshots for progress
/ui-enhancer-radar revert	Undo all changes back to last checkpoint
/ui-enhancer-radar batch [path]	Audit all views in a directory, rank by severity
--show-suppressed	Show findings suppressed by known-intentional entries
--accept-intentional	Mark current finding as known-intentional (not a bug)
/ui-enhancer-radar --capture	Capture screenshot from running simulator (optional)
/ui-enhancer-radar --devices	Analyze layout across device sizes (optional)
/ui-enhancer-radar fix-deferred	Resolve items deferred from a previous run
/ui-enhancer-radar verify	Re-check previous findings without full re-audit (~5 min)

---

Help Command

If the user runs /ui-enhancer-radar help, display this command reference and stop (do not start an audit):

UI Enhancer — Available Commands

FULL AUDIT
  /ui-enhancer-radar              Full 14-domain audit with interview

SINGLE DOMAIN (skip interview, run one domain)
  /ui-enhancer-radar space        Space efficiency analysis
  /ui-enhancer-radar hierarchy    Visual hierarchy analysis
  /ui-enhancer-radar density      Information density analysis
  /ui-enhancer-radar interaction  Interaction patterns analysis
  /ui-enhancer-radar accessibility  Accessibility audit
  /ui-enhancer-radar hig          HIG compliance check
  /ui-enhancer-radar dark-mode    Dark mode audit
  /ui-enhancer-radar performance  Performance impact analysis
  /ui-enhancer-radar design-system  Design system compliance
  /ui-enhancer-radar color        Color audit (inventory, flatness, consistency)
  /ui-enhancer-radar ipad-sheets  iPad sheet sizing audit (caller-side `.sheet()` check)
  /ui-enhancer-radar hit-region   Button hit region audit (.plain + chevron + Form/List)

UTILITIES
  /ui-enhancer-radar compare      Compare before/after screenshots
  /ui-enhancer-radar revert       Undo all changes back to checkpoint
  /ui-enhancer-radar batch [path] Audit all views in a directory
  /ui-enhancer-radar help         Show this command list

OPTIONS (combine with any command)
  --capture                 Capture screenshot from running simulator
  --devices                 Analyze layout across device sizes

---

First-Run Hint

When /ui-enhancer-radar is invoked with no subcommand, display this hint once before the Phase 1 interview (not on subsequent runs in the same session):

Tip: Run /ui-enhancer-radar help to see all available commands, or continue for a full audit.

Then proceed directly to Phase 1.

---

Skill Introduction (MANDATORY — run before anything else)

This section replaces radar-suite-core.md § Session Setup for the ui-enhancer-radar entry point. Do NOT also run core's 4-question Session Setup — its questions are consolidated below. Phase 1 ("Interview") below reuses the answers captured here and does NOT re-ask experience level, fix mode, or attendance.

On first invocation, ask all setup questions in a single AskUserQuestion call:

Question 1: "What's your experience level with Swift/SwiftUI?"

• Beginner — New to Swift. Plain language, analogies, define terms on first use.
• Intermediate — Comfortable with SwiftUI basics. Standard terms, explain non-obvious patterns.
• Experienced (Recommended) — Fluent with SwiftUI. Concise findings, no definitions.
• Senior/Expert — Deep expertise. Terse, file:line only, skip explanations.

Question 2: "How should fixes be handled?"

• Auto-fix safe items (Recommended) — Apply isolated, low-blast-radius fixes automatically. Present cross-cutting fixes and design decisions for approval first.
• Review first — Present all findings with ratings, then ask before making any changes. Fixes still happen — you just approve each wave first.
• Batch mode — Approve all fixes in each wave at once.

IMPORTANT: All three modes lead to fixes. "Review first" means the user sees the plan before code changes — it does NOT mean "skip fixes and jump to handoff." After presenting findings, ALWAYS offer to fix them regardless of which mode was selected. (Exception: Hands-Free mode overrides this — see Question 3.)

Question 3: "Will you be stepping away during the audit?"

• I'll be here (Recommended) — Normal mode. Permission prompts may appear for writes/edits.
• Hands-Free (walk away safe) — Read-only analysis only (Read, Grep, Glob). No edits, no Bash, no prompts. Hands-Free overrides Question 2: all fixes are deferred regardless of FIX_MODE. Phase 7b (Visual Inspection Gate) is skipped — no code changes will be applied. The skill emits the saved playbook and Hands-Free completion message instead of the next-phase AskUserQuestion (see § Hands-Free Mode below for full precedence rules).
• Pre-Approved — You have already configured Claude Code permissions for this session. Run at full speed without restriction.

Store as: USER_EXPERIENCE, FIX_MODE, PRESENCE_MODE. Apply to ALL output for the session, per radar-suite-core.md § Experience-Level Output Rules. Also persist to .radar-suite/session-prefs.yaml per radar-suite-core.md § Session Persistence.

Question 4 (optional follow-up): "Would you like a brief explanation of what this skill does?"

• No, let's go (Recommended) — Skip explanation, proceed to Phase 1 (Interview).
• Yes, explain it — Show one of the explanations below adapted to experience level, then proceed.

Experience-adapted explanations for UI Enhancer:

• Beginner: "UI Enhancer is like having a professional designer review every screen in your app. It checks 14 different things — spacing, colors, accessibility, layout efficiency, iPad sheet sizing, button hit regions, and more — then suggests specific improvements. It won't just say 'this looks wrong'; it'll show you exactly what to change and why. It works one view at a time, applying changes incrementally so you can undo anything."

• Intermediate: "UI Enhancer performs a 14-domain analysis of SwiftUI views: layout, spacing, color accessibility, typography, element compaction, cross-view consistency, iPad sheet sizing, button hit regions, and more. It interviews you about design intent first, then audits against Apple HIG and your app's design system. Changes are applied incrementally with revert safety."

• Experienced: "14-domain SwiftUI UI audit with design intent interview, adaptive color profiles, element compaction, cross-view consistency checks, iPad sheet sizing caller-side audit, button hit region three-factor audit, silent picker menu-presentation audit, layout reorganization, App Store guardrails, and incremental apply with revert safety. Run /ui-enhancer-radar help for the full command list."

• Senior/Expert: "14-domain view audit: layout, color, typography, spacing, compaction, consistency, accessibility, iPad sheet sizing, button hit region, silent picker. Interview → analyze → apply incrementally."

Store the experience level as USER_EXPERIENCE and apply to ALL output for the session.

User impact explanations: Can be toggled at any time with --explain / --no-explain. When enabled, each finding gets a 3-line companion explanation (what's wrong, fix, user experience before/after). See the shared rating system doc for format and rules. Store as EXPLAIN_FINDINGS (default: false).

Experience-level auto-apply: If USER_EXPERIENCE = Beginner, auto-set EXPLAIN_FINDINGS = true and default sort to impact. If Senior/Expert, default sort to effort. Apply all output rules from Experience-Level Output Rules table in radar-suite-core.md.

---

Shared Patterns

See radar-suite-core.md for: Tier System, Pipeline UX Enhancements, Table Format, Plain Language Communication, Work Receipts, Contradiction Detection, Finding Classification, Audit Methodology, Context Exhaustion, Progress Banner, Issue Rating Tables, Handoff YAML schema, Known-Intentional Suppression, Pattern Reintroduction Detection, Experience-Level Output Rules, Implementation Sort Algorithm, short_title requirement.

Pre-Scan Startup (MANDATORY — before any domain scan)

1. Known-intentional suppression: Run the protocol in radar-suite-core.md § Known-Intentional Suppression. Core owns this — do not restate the steps here.

2. Pattern reintroduction detection: Run the protocol in radar-suite-core.md § Pattern Reintroduction Detection. Core owns this.

---

Phase 1: Interview

Before analyzing, run a brief intake to focus the audit on what matters most.

Experience level was already captured in § Skill Introduction (Question 1). Do NOT re-ask it here. The questions below are content-specific to ui-enhancer-radar's audit shape — focus, priority, design intent, aggressiveness.

Display this instruction before the first set of questions:

To answer, type the option labels (e.g., "General polish, All domains, Moderate") or use numbers (e.g., "1, 1, 1"). You can answer all questions at once or one at a time.

questions:
[
  {
    "question": "What's the main reason for this review?",
    "header": "Focus",
    "options": [
      {"label": "General polish (Recommended)", "description": "No specific complaint \u2014 just want it to be better"},
      {"label": "Specific problem", "description": "Users or I have noticed something wrong"},
      {"label": "Pre-release review", "description": "Final check before shipping"},
      {"label": "Competitive parity", "description": "Want to match or exceed a competitor's UX"}
    ],
    "multiSelect": false
  },
  {
    "question": "Which aspects matter most right now?",
    "header": "Priority",
    "options": [
      {"label": "All domains (Recommended)", "description": "Full 14-domain analysis"},
      {"label": "Visual \u2014 layout and hierarchy", "description": "Space, visual weight, information density"},
      {"label": "Interaction \u2014 usability", "description": "Touch targets, discoverability, feedback"},
      {"label": "Technical \u2014 performance and compliance", "description": "Dark mode, perf, HIG, design system"}
    ],
    "multiSelect": false
  }
]

If "Specific problem", follow up:

questions:
[
  {
    "question": "What's the specific issue?",
    "header": "Issue",
    "options": [
      {"label": "Too much wasted space (most common)", "description": "Content doesn't start until halfway down the screen"},
      {"label": "Hard to find things", "description": "Users can't discover features or actions"},
      {"label": "Looks cluttered or confusing", "description": "Too much competing for attention"},
      {"label": "I'll describe it", "description": "Let me explain the problem"}
    ],
    "multiSelect": false
  }
]

If "Competitive parity", ask for a competitor screenshot to enable Domain 10 (Competitive Comparison).

Design Intent (always ask)

After the focus/priority questions, always ask about design intent and change aggressiveness:

questions:
[
  {
    "question": "Are there elements on this screen you consider essential to its identity — things that should be preserved even if they use extra space?",
    "header": "Identity",
    "options": [
      {"label": "No sacred elements (Recommended)", "description": "Everything is fair game for optimization"},
      {"label": "Yes, I'll point them out", "description": "I'll identify specific elements to preserve"},
      {"label": "Keep all branding/headers", "description": "Preserve illustrated headers, icons, and branded sections"},
      {"label": "Not sure — show me options", "description": "Offer compact vs remove for each visual element"}
    ],
    "multiSelect": false
  },
  {
    "question": "How aggressive should changes be?",
    "header": "Aggressiveness",
    "options": [
      {"label": "Moderate (Recommended)", "description": "Compact where possible, remove only clear redundancies"},
      {"label": "Conservative", "description": "Tighten spacing and compact only — never remove elements"},
      {"label": "Aggressive", "description": "Maximize space — remove anything non-essential"}
    ],
    "multiSelect": false
  }
]

Attendance

Attendance mode (PRESENCE_MODE) was already captured in § Skill Introduction (Question 3). Do NOT re-ask here. The Hands-Free Mode section below documents precedence rules for write-tool deferral and AskUserQuestion suppression.

Hands-Free Mode (precedence rules — load-bearing)

When PRESENCE_MODE = Hands-Free:

1. Hands-Free overrides FIX_MODE. Even if Question 2 was answered Auto-fix safe items, Review first, or Batch mode, no fixes are applied in Hands-Free mode. All findings are emitted with Status: Deferred (hands-free) in the Issue Rating table. The Fix Plan, Report (Phase 6), and Playbook (Phase 7) are still produced — they're held in the conversation for the user to act on when they return.
2. Phase 7b (Visual Inspection Gate) is skipped. Since no code changes will be applied, the gate has nothing to protect. The skill emits the saved playbook to .agents/ui-enhancer-radar/[date]-[view]-playbook.md and prints the completion message below.
3. Phase 7c-7f are deferred. Guided Visual Review, Apply Approved Changes, Pattern Sweep, and Refinement Loop all require interactive user prompts (AskUserQuestion) and/or write tools. None of these run in Hands-Free.
4. BLOCKING progress banner exception. The "CRITICAL — BLOCKING requirement" for the next-phase AskUserQuestion (§ Phase Progress Banner) applies in Normal and Pre-Approved modes only. In Hands-Free, the progress banner still prints after each completed phase, but the AskUserQuestion is suppressed in favor of the completion message.
5. Handoff YAML emitted inline. Writing .agents/ui-audit/ui-enhancer-radar-handoff.yaml and .radar-suite/ledger.yaml requires Edit/Write — forbidden in Hands-Free. The skill emits these as fenced YAML blocks inline in the conversation so the user can persist them on return.

Hands-Free completion message:

⏱ Hands-free audit complete through Phase 5 (Domain Analysis) + Phase 6 (Report).
  Phases skipped (deferred until you return): 7a-7f (apply), 8 (tests), 9 (summary).
  Findings deferred: [count] (no fixes applied — Hands-Free mode)
  Playbook saved: .agents/ui-enhancer-radar/[date]-[view]-playbook.md
  Handoff YAML + ledger entries: emitted inline above; copy to .agents/ui-audit/ and .radar-suite/ when you return
  Reply to continue with supervised phases.

When PRESENCE_MODE = Pre-Approved: full speed, no restrictions. Assumes permissions are configured per the Permission Setup guide below. All phases run normally.

Permission Setup (for unattended runs)

To avoid permission prompts during audits, pre-allow these read-only patterns in Claude Code settings. Safe to auto-approve — they cannot modify your codebase:

# Already safe by default (no setup needed):
Read, Grep, Glob — always auto-approved

# Add these for unattended Bash scans:
Bash(find:*)
Bash(wc:*)
Bash(stat:*)

Do NOT auto-approve (keep prompted — they modify state):

Edit, Write — file modifications
Bash(rm:*), Bash(git:*) — destructive operations

After all questions, always offer:

Anything else I should know? (design preferences, constraints, specific elements to preserve — or press Enter to skip)

Record any free-text input as additional constraints that apply throughout the audit. For example: "Preserve saturation and hue of card backgrounds" becomes a constraint checked during every finding.

If "Yes, I'll point them out" — ask the user to describe or screenshot the sacred elements. Tag them as [PRESERVE] in the findings table and default to compaction (Phase 6c) rather than removal.

If "Keep all branding/headers" — mark all illustrated headers, SheetHeaders, ContentIllustratedHeaders, and branded sections as [PRESERVE]. Only recommend compaction for these, never removal.

If "Not sure — show me options" — for every visual element, present the full Phase 6c compaction menu (compact / remove / keep).

Aggressiveness calibration

The aggressiveness setting affects all findings throughout the audit:

Setting	Spacing	Headers	Decorative elements	Redundant info
Conservative	Tighten 10-20%	Compact only	Keep, reduce size	Merge, don't remove
Moderate	Tighten 20-40%	Compact (default), remove if redundant	Compact or remove	Remove if truly duplicate
Aggressive	Minimize to HIG minimum	Remove unless [PRESERVE]	Remove	Remove

The interview determines:

• Which domains to run (all 14, or a focused subset)
• Severity weighting (user-reported problems get Critical minimum)
• Whether to include competitive comparison
• Which elements are sacred ([PRESERVE] tag)
• How aggressive to be with changes (Conservative / Moderate / Aggressive)
• How to pitch explanations (experience level)

Experience-Level Adaptation

Adjust ALL output (findings, questions, recommendations, compaction options) based on the user's experience level:

• Beginner: Plain language, real-world analogies. "This header takes up 120 points of space — that's about a third of the visible screen on an iPhone. Compacting it would let users see their content sooner." Define SwiftUI terms on first use. When presenting compaction options, explain what each choice means visually.
• Intermediate: Standard SwiftUI terminology, explain non-obvious tradeoffs. "The SheetHeader uses 120pt — compacting to inline icon+title saves 80pt and keeps the visual identity. The .stuffolioCard() modifier handles the styling." Explain architectural choices but not basic concepts.
• Experienced (default): Concise findings. "SheetHeader: 120pt → 40pt inline. Saves 80pt above fold." No definitions, focus on measurements and tradeoffs.
• Senior/Expert: Minimal. "SheetHeader 120→40pt. .stuffolioCard() handles styling. 3 files touched." Skip design rationale — just the change, the impact, and the blast radius.

---

Phase 2: Gather Input

questions:
[
  {
    "question": "How would you like to provide the view to analyze?",
    "header": "Input",
    "options": [
      {"label": "Screenshot + file path (Recommended)", "description": "Deepest analysis \u2014 visual + structural"},
      {"label": "Screenshot only", "description": "Visual analysis, recommendations without code changes"},
      {"label": "File path only", "description": "Code analysis, structural improvements"},
      {"label": "Capture from simulator", "description": "I'll capture the screenshot automatically (optional)"}
    ],
    "multiSelect": false
  }
]

If "Capture from simulator" (optional feature):

xcrun simctl io booted screenshot /tmp/ui-enhancer-radar-capture.png

Then read the captured screenshot.

---

Phase 2b: View Type Classification

Before analyzing, classify the view type. This determines severity weighting, compensation strategies, and domain-specific heuristics throughout the audit.

Classify by reading the code and/or screenshot. Do NOT ask the user — infer from evidence:

View Type	How to Identify	Implications
Dashboard / overview	Aggregates data from multiple sources, cards/widgets, summary stats	Space efficiency is Critical; visual variety matters most
Detail / inspector	Shows one item's full data, sections of attributes	Information density is Critical; hierarchy matters most
Form / input	Text fields, pickers, toggles for data entry	Interaction patterns are Critical; keep chrome minimal
List / table	Repeating rows of similar items, search/filter	Density and performance are Critical; row height matters
Help / reference	Static instructional text, tips, guides	Space is Medium priority; visual richness prevents boredom
Sheet / modal	Presented modally for a focused task	Check for duplicate headers (SheetContainer + SheetHeader)
Settings / config	Toggles, preferences, grouped sections	HIG compliance is Critical; follow system patterns

Record the classification at the top of the report (e.g., "View type: Help / reference (sheet)"). Reference it when:

• Choosing severity levels (Domain 1-11)
• Offering compaction alternatives (Phase 6c)
• Recommending compensation techniques (Phase 6d)
• Deciding whether a finding is worth fixing
• Applying platform-specific design heuristics (see below)

Platform-Specific Design Heuristics

When the view runs on multiple platforms, apply platform-appropriate design expectations:

View Type	macOS (with sidebar)	iPhone (no sidebar)
Dashboard	Should be a summary — show stats, alerts, and insights. Navigation lives in sidebar. Feature cards that duplicate sidebar items are redundant.	Should be a hub — provide entry points to all features. No sidebar means the dashboard IS the navigation.
Settings / config	Settings items accessible via sidebar don't need dashboard cards. Theme toggle in header is optional if Settings is 1 click away.	Settings behind a tab or gear icon — header controls add convenience.
Form / input	Wider layout allows side-by-side fields. Keyboard toolbar not needed (Tab key navigation).	Keyboard Done toolbar is essential. Single-column layout.
List / table	Can show more columns, denser rows. Hover effects for interactivity.	Swipe actions, pull-to-refresh. Touch-optimized row height (44pt min).