| name | fix-ui |
| description | Iteratively fix a SwiftUI View to match a design image. Captures previews with axe, compares against the target design, and modifies the code until the UI matches. Use when the user provides a design image and wants the View adjusted to match it. |
| argument-hint | <file.swift> <design-image-path> |
| disable-model-invocation | true |
| allowed-tools | Bash(axe *), Bash(cat *), Read, Edit, Glob, Grep |
Design-Driven UI Fix Loop
Iteratively modify a SwiftUI View until its preview matches a target design image.
Inputs
$0: Path to the SwiftUI source file (.swift)$1: Path to the design image (PNG, JPG, etc.)
Procedure
1. Resolve inputs
$0 may contain only a View name (e.g. ContentView) instead of a file path. Resolve it to a .swift path (e.g. TodoApp/ContentView.swift) using Glob.
2. Read the design target
Read the design image at $1 using the Read tool to understand the target appearance.
3. Read the source code
Read the SwiftUI source file to understand the current implementation.
4. Capture the current preview
axe preview report "$0" --output <output.png>
axe preview report is preferred because it waits for rendering to complete and retries on failure.
If the file has multiple #Preview blocks, --output file.png will fail (it requires exactly one preview). In that case:
- Use a directory as
--output to capture all, then pick the relevant one
- Or fall back to
axe preview "$0" --preview <title|index> (oneshot, no render wait)
Read the captured image to see the current appearance.
5. Compare and identify differences
Compare the current preview against the design image. Focus on:
- Layout structure (VStack/HStack/ZStack arrangement)
- Spacing and padding
- Font sizes and weights
- Colors and backgrounds
- Corner radius and borders
- Image sizing and aspect ratios
- Text content and alignment
6. Edit the source code
Make targeted edits to the SwiftUI source file to address the identified differences. Prioritize the most visually impactful changes first.
7. Re-capture and verify
Capture a new preview after the edits. Use --reuse-build to skip rebuilding since only the View source changed:
axe preview report "$0" --output <output.png> --reuse-build
Read the new image and compare against the design.
8. Iterate
Repeat steps 5-7 until the preview closely matches the design image. Stop after at most 5 iterations. If the design still does not match, report remaining differences to the user.
9. Report
Show the final preview image and summarize all changes made to the source file.
Guidelines
- Make minimal, focused changes per iteration
- Prefer SwiftUI modifiers over restructuring the view hierarchy
- If the file has multiple
#Preview blocks, use --preview <title|index> to target the correct one
- If the design requires assets (images, custom fonts) not present in the project, note this to the user
- If the design cannot be perfectly replicated due to platform constraints, explain the limitations
Prerequisites
Run this if the command fails because axe is not found::
curl -fsSL https://raw.githubusercontent.com/k-kohey/axe/main/install.sh | sh
