Skip to main content
skill CX Codex

ios-ui-refactor — Claude Code skill: SwiftUI UI review

The ios-ui-refactor skill reviews existing SwiftUI screens and guides refactoring of hierarchy, transitions, animations, and visual systems for iOS 26 and Swift 6.2.

MIT 299 installs ★ 227 updated 2026-08-15

Install into Claude Code · Skills CLI (Vercel) All methods and platforms ↓
npx skills add pproenca/dot-skills --skill ios-ui-refactor -a claude-code
Open on GitHub

What ios-ui-refactor does

ios-ui-refactor is a review lens for existing SwiftUI screens. It helps an agent spot unnecessary elements, unclear labels, weak hierarchy, decorative motion, and mismatched spacing, radii, or colors. The rules move from reducing interface noise and clarifying meaning to system consistency, edge-case handling, enduring choices, and final refinement.

The skill assumes a clinic-style modular MVVM-C architecture. Feature modules may import Domain and DesignSystem, while Data and sibling features stay outside their boundary. Domain contains pure Swift models and contracts; Data handles SwiftData, networking, sync, retries, and background I/O; the App target connects dependency wiring and coordinators.

Use it for auditing and improving screens already in the project, not as the primary guide for greenfield UI. The source distinguishes ios-design for new interfaces, ios-hig for HIG checks, and swift-refactor for code-level changes. If the project does not follow the clinic architecture boundaries, some recommendations can clash with its module structure.

What it helps with

  • audit hierarchy on an existing SwiftUI screen
  • remove controls and motion that lack a clear purpose
  • align colors, spacing, and corner radii across a visual system
  • check state communication, contrast, and dark-mode variants
  • review transitions and edge-case behavior

Example prompts for the agent

  • Review AppointmentView.swift and list problems with its visual hierarchy.
  • Refactor the transitions and animations in this SwiftUI screen using ios-ui-refactor rules.
  • Check this feature module against the Domain, Data, and App boundaries and identify conflicts.

How to install ios-ui-refactor

1Skills CLI (Vercel)

npx skills add pproenca/dot-skills --skill ios-ui-refactor -a claude-code

2Manually: put the files in place

~/.claude/skills/ios-ui-refactor/SKILL.md

Copy the whole skill folder; for one project use .claude/skills/ios-ui-refactor/

Step by step, with commands for each platform: How to install skills in Claude Code: five ways

Questions about ios-ui-refactor

How do I install ios-ui-refactor in Claude Code?

Run npx skills add pproenca/dot-skills --skill ios-ui-refactor -a claude-code, then check ~/.claude/skills/ios-ui-refactor/SKILL.md.

What does ios-ui-refactor do?

It reviews existing SwiftUI interfaces and guides fixes for visual anti-patterns, navigation, animation, state presentation, and visual-system consistency. It targets iOS 26 and Swift 6.2 projects.

How is ios-ui-refactor different from ios-design?

ios-ui-refactor audits and improves screens that already exist. ios-design covers new UI work, while ios-ui-refactor takes precedence where their rules overlap and supplies more specific before-and-after transformations.

Source text

SKILL.md · MIT
---
name: ios-ui-refactor
description: Principal-level SwiftUI UI review and refactoring patterns for iOS 26 / Swift 6.2 clinic-architecture apps, grounded in Rams, Segall, and Edson principles. Use when auditing or improving existing SwiftUI screens, transitions, animations, and visual systems while preserving brand identity and respecting clinic Domain/Data/App boundaries.
---

# Apple HIG SwiftUI iOS 26 / Swift 6.2 Best Practices

A principal designer's lens for evaluating and refactoring SwiftUI interfaces to Apple-quality standards, grounded in Rams, Segall, and Edson. Contains 51 rules across 8 categories, each grounded in specific principles from three foundational design texts:

- **Dieter Rams** — *Ten Principles for Good Design* ("less, but better," "design should be honest")
- **Ken Segall** — *Insanely Simple* (simplicity as a core principle for intuitive, beautiful products)
- **John Edson** — *Design Like Apple* (design-focused culture, prototyping to perfection, the product is the marketing)

Categories are ordered by a visual review process: start with what to remove, then what to clarify, then what to make honest, invisible, systematic, thorough, enduring, and finally what to refine.

## Scope & Relationship to Sibling Skills

This skill is the **refactoring and review lens** — it evaluates existing UI and identifies visual anti-patterns to fix. When loaded alongside `ios-design` (building new UI), `ios-hig` (HIG compliance), or `swift-refactor` (code-level refactoring), this skill supersedes overlapping rules with more detailed "incorrect -> correct" transformations and "When NOT to apply" guidance. Use this skill for auditing and improving existing screens; use the siblings for greenfield implementation.


## Clinic Architecture Contract (iOS 26 / Swift 6.2)

All guidance in this skill assumes the clinic modular MVVM-C architecture:

- Feature modules import `Domain` + `DesignSystem` only (never `Data`, never sibling features)
- App target is the convergence point and owns `DependencyContainer`, concrete coordinators, and Route Shell wiring
- `Domain` stays pure Swift and defines models plus repository, `*Coordinating`, `ErrorRouting`, and `AppError` contracts
- `Data` owns SwiftData/network/sync/retry/background I/O and implements Domain protocols
- Read/write flow defaults to stale-while-revalidate reads and optimistic queued writes
- ViewModels call repository protocols directly (no default use-case/interactor layer)

## When to Apply

Reference these guidelines when:
- Reviewing existing SwiftUI screens for visual quality issues
- Auditing whether every element on screen earns its place (Rams #10)
- Evaluating if the interface is self-explanatory without tooltips (Rams #4)
- Checking that colors, states, and hierarchy tell the truth (Rams #6)
- Ensuring animations and materials are invisible, not decorative (Rams #5)
- Verifying spacing, radii, and colors form a coherent system (Edson "Systems Thinking")
- Confirming edge cases — reduce motion, touch targets, safe areas — are handled (Rams #8)
- Adopting iOS 26 / Swift 6.2 APIs that refine previously impossible interactions (Edson "Design Out Loud")

## Rule Categories by Priority

| Priority | Category | Principle | Impact | Prefix | Rules |
|----------|----------|-----------|--------|--------|-------|
| 1 | Less, But Better | Rams #10 + Segall "Think Minimal" | CRITICAL | `less-` | 7 |
| 2 | Self-Evident Design | Rams #4 + Segall "Think Human" | CRITICAL | `evident-` | 6 |
| 3 | Honest Interfaces | Rams #6 + Segall "Think Brutal" | CRITICAL | `honest-` | 6 |
| 4 | Invisible Design | Rams #5 + Edson "Product Is Marketing" | HIGH | `invisible-` | 6 |
| 5 | Systems, Not Pieces | Edson "Systems Thinking" + Rams #8 | HIGH | `system-` | 6 |
| 6 | Thorough to the Last Detail | Rams #8 + Rams #2 | HIGH | `thorough-` | 7 |
| 7 | Enduring Over Trendy | Rams #7 + Edson "Design With Conviction" | MEDIUM-HIGH | `enduring-` | 5 |
| 8 | Refined Through Iteration | Edson "Design Out Loud" + Rams #1/#3 | MEDIUM | `refined-` | 8 |

## Quick Reference

### 1. Less, But Better (CRITICAL)

Rams #10: "Good design is as little design as possible." Segall: Apple succeeded by saying no to a thousand things.

- [`less-single-focal`](references/less-single-focal.md) - One primary focal point per screen
- [`less-type-restraint`](references/less-type-restraint.md) - Limit to 3-4 distinct type treatments per screen
- [`less-one-typeface`](references/less-one-typeface.md) - One typeface per app, differentiate with weight and size
- [`less-color-restraint`](references/less-color-restraint.md) - Reserve saturated colors for small interactive elements
- [`less-one-color-purpose`](references/less-one-color-purpose.md) - Each semantic color serves exactly one purpose
- [`less-purposeful-motion`](references/less-purposeful-motion.md) - Every animation must communicate state change or provide feedback
- [`less-fewer-controls`](references/less-fewer-controls.md) - Remove controls that do not serve the core task

### 2. Self-Evident Design (CRITICAL)

Rams #4: "Good design makes a product understandable." Segall: interfaces must speak in terms people understand.

- [`evident-visual-weight`](references/evident-visual-weight.md) - Combine size, weight, and contrast for hierarchy
- [`evident-whitespace-grouping`](references/evident-whitespace-grouping.md) - Use whitespace to separate conceptual groups
- [`evident-progressive-disclosure`](references/evident-progressive-disclosure.md) - Use progressive disclosure for dense information
- [`evident-reading-order`](references/evident-reading-order.md) - Align visual weight with logical reading order
- [`evident-navigation-intent`](references/evident-navigation-intent.md) - Sheets for tasks and creation, push for drill-down hierarchy
- [`evident-label-clarity`](references/evident-label-clarity.md) - Use clear labels over ambiguous icons

### 3. Honest Interfaces (CRITICAL)

Rams #6: "Good design is honest." Segall: clarity without sugar-coating.

- [`honest-semantic-colors`](references/honest-semantic-colors.md) - Use semantic colors, never hard-coded black or white
- [`honest-contrast`](references/honest-contrast.md) - Ensure WCAG AA contrast ratios
- [`honest-dark-mode`](references/honest-dark-mode.md) - Define light and dark variants for every custom color
- [`honest-foreground-style`](references/honest-foreground-style.md) - Use foregroundStyle over foregroundColor
- [`honest-depth-cues`](references/honest-depth-cues.md) - Use materials for layering, not drop shadows for depth
- [`honest-loading-states`](references/honest-loading-states.md) - Show real progress, not indefinite spinners

### 4. Invisible Design (HIGH)

Rams #5: "Good design is unobtrusive." Edson: the product itself is the marketing.

- [`invisible-spring-physics`](references/invisible-spring-physics.md) - Default to spring animations for all UI transitions
- [`invisible-spring-presets`](references/invisible-spring-presets.md) - Use .smooth for routine, .snappy for interactive, .bouncy for delight
- [`invisible-no-easing`](references/invisible-no-easing.md) - Prefer springs over linear and easeInOut for UI elements
- [`invisible-system-materials`](references/invisible-system-materials.md) - Use system materials, not custom semi-transparent backgrounds
- [`invisible-symbol-effects`](references/invisible-symbol-effects.md) - Use built-in symbolEffect, not manual symbol animation
- [`invisible-content-transitions`](references/invisible-content-transitions.md) - Use contentTransition for changing text and numbers

### 5. Systems, Not Pieces (HIGH)

Edson: "Design is systems thinking." Rams #8: nothing must be arbitrary or left to chance.

- [`system-spacing-grid`](references/system-spacing-grid.md) - Use a 4pt base unit for all spacing
- [`system-consistent-padding`](references/system-consistent-padding.md) - Use consistent padding across all screens
- [`system-corner-radii`](references/system-corner-radii.md) - Standardize corner radii per component type
- [`system-alignment`](references/system-alignment.md) - Consistent alignment per content type within a screen
- [`system-color-naming`](references/system-color-naming.md) - Name custom colors by role, not hue
- [`system-brand-integration`](references/system-brand-integration.md) - Map brand palette onto iOS semantic color roles

### 6. Thorough to the Last Detail (HIGH)

Rams #8: "Care and accuracy in the design process show respect for the user." Rams #2: if the user cannot reliably use it, the product has failed.

- [`thorough-reduce-motion`](references/thorough-reduce-motion.md) - Always provide reduce motion fallback
- [`thorough-touch-targets`](references/thorough-touch-targets.md) - All interactive elements at least 44x44 points
- [`thorough-safe-areas`](references/thorough-safe-areas.md) - Always respect safe areas
- [`thorough-readable-weights`](references/thorough-readable-weights.md) - Avoid light font weights for body text
- [`thorough-vibrancy-levels`](references/thorough-vibrancy-levels.md) - Match vibrancy level to content importance
- [`thorough-material-thickness`](references/thorough-material-thickness.md) - Choose material thickness by contrast needs
- [`thorough-background-interaction`](references/thorough-background-interaction.md) - Enable background interaction for peek-style sheets

### 7. Enduring Over Trendy (MEDIUM-HIGH)

Rams #7: "Good design is long-lasting." Edson: commit to a voice that persists across product generations.

- [`enduring-system-text-styles`](references/enduring-system-text-styles.md) - Use Apple text styles, never fixed font sizes
- [`enduring-weight-not-caps`](references/enduring-weight-not-caps.md) - Use weight for emphasis, not ALL CAPS
- [`enduring-swipe-back`](references/enduring-swipe-back.md) - Never break the system back-swipe gesture
- [`enduring-zoom-navigation`](references/enduring-zoom-navigation.md) - Use zoom transitions for collection-to-detail navigation
- [`enduring-card-modularity`](references/enduring-card-modularity.md) - Use self-contained cards for dashboard layouts

### 8. Refined Through Iteration (MEDIUM)

Edson: "Design out loud" — prototype relentlessly until every interaction feels inevitable. Rams #1: innovation serves genuine purpose.

- [`refined-scroll-transitions`](references/refined-scroll-transitions.md) - Use scrollTransition for scroll-position visual effects
- [`refined-phase-animator`](references/refined-phase-animator.md) - Use PhaseAnimator for multi-step animation sequences
- [`refined-mesh-gradients`](references/refined-mesh-gradients.md) - Use MeshGradient for premium dynamic backgrounds
- [`refined-text-renderer`](references/refined-text-renderer.md) - Use TextRenderer for hero text animations only
- [`refined-inspector`](references/refined-inspector.md) - Use inspector for trailing-edge detail panels
- [`refined-multi-detent`](references/refined-multi-detent.md) - Provide multiple sheet detents with drag indicator
- [`refined-matched-geometry`](references/refined-matched-geometry.md) - Use matchedGeometryEffect for contextual origin transitions
- [`refined-no-hard-cuts`](references/refined-no-hard-cuts.md) - Always animate between states, even minimally

## How to Use

Read individual reference files for detailed explanations and code examples:

- [Section definitions](references/_sections.md) - Category structure, principle sources, and impact levels
- [Rule template](assets/templates/_template.md) - Template for adding new rules

## Reference Files

| File | Description |
|------|-------------|
| [references/_sections.md](references/_sections.md) | Category definitions and principle grounding |
| [assets/templates/_template.md](assets/templates/_template.md) | Template for new rules |
| [metadata.json](metadata.json) | Version and reference information |

© pproenca · MIT · pproenca/dot-skills

Similar skills

All skills for Design →

From the same set139

The whole set →
ruby-refactor ruby-refactor — a refactoring skill with 45 community guidelines for Ruby projects. Helps agents simplify nested branches, decouple classes, and adopt modern Ruby 3.x patterns. CX Codex +1 307installs ios-xcode ios-xcode is a Claude Code skill for Xcode setup and iOS project tooling. It applies to App-target configuration, SwiftData, testing, debugging, profiling, and app distribution. CX Codex +1 307installs think think — a skill that shifts the AI into deep analysis mode: instead of the first reasonable answer, it finds the highest-leverage solution by connecting ideas across domains. Use it when you need strategy, not instructions. CX Codex +1 307installs restful-hateoas restful-hateoas adds 47 guidelines for building Richardson Maturity Level 3 REST APIs with HATEOAS in Ruby on Rails projects. CX Codex +1 304installs rails-dev Set of guidelines for Ruby on Rails development. Helps build clean controllers, optimize ActiveRecord queries, and configure caching. CX Codex +1 299installs swift-optimise The swift-optimise skill reviews Swift and SwiftUI performance across concurrency, rendering, and animation. Use it while profiling clinic modules. CX Codex +1 293installs ruby-optimise The ruby-optimise skill guides Ruby code reviews and refactors around performance. Use it when working with allocations, collections, ActiveRecord queries, or runtime settings. CX Codex +1 292installs swift-refactor swift-refactor is a Claude Code skill for reshaping existing SwiftUI code around a modular MVVM-C architecture. It applies to work on navigation, state, and app layer boundaries. CX Codex +1 289installs

Project sponsors

Companies that keep this analytics open