Agent skill

SwiftUI Design Skill

by Wholiver in Wholiver/swiftui-design-skill

Guides the agent to design distinctive SwiftUI interfaces for iOS and macOS, with six anti-generic rules, a design direction workflow and a five-dimension review.

MITAuto-check passedMobile

Install SwiftUI Design Skill

skills CLI
$ npx skills add Wholiver/swiftui-design-skill --skill swiftui-design-skill -a claude-code

Project install by default; add -g for ~/.claude/skills/.

GitHub CLI
$ gh skill install Wholiver/swiftui-design-skill swiftui-design-skill --agent claude-code

Project scope by default; add --scope user for a personal install. Needs GitHub CLI 2.90.0 or later (public preview).

Claude Code skills documentation · loads skills from .claude/skills/

Facts

Skill name
swiftui-design-skill
GitHub stars
204
Token cost
~2.8k tokens
SKILL.md length
1,167 words
Files
13 (incl. references)
Skills in repo
1
Repo updated
First seen
Licence
MIT

At a glance

Guides the agent to design distinctive SwiftUI interfaces for iOS and macOS, with six anti-generic rules, a design direction workflow and a five-dimension review.

  • Works in 9 steps: Understand Context (5 min) → Recommend 3 Directions → Present Visual Anchors → …
  • Designing new SwiftUI views or screens from scratch
  • SKILL.md covers When to Use, When NOT to Use, Prerequisites and Core Design Philosophy, plus 6 more sections
  • Instructions only: no scripts, shell commands, URLs or credentials in SKILL.md

What it does

This skill steers the agent toward SwiftUI screens that look deliberately designed instead of generic AI output. It rests on six principles, among them starting from context rather than a blank page (an existing design system, codebase or brand guidelines, or a brand-spec file when none exists), showing early hypotheses with placeholders, offering two or three distinct design directions rather than one final answer, and using a clean labeled placeholder in place of AI-generated SVG clipart.

A Design Direction workflow handles vague requirements, and every design must pass a five-dimension review before shipping. Reference files cover anti-generic patterns, design review, layout patterns, Swift extensions and typography and color, plus a brand-spec template. It expects Xcode 16 or newer with the iOS 18 and macOS 15 SDKs and SwiftUI rather than UIKit. Compile errors, performance work and accessibility-only tasks belong to the separate swiftui-expert-skill.

When your agent uses it

  • Designing new SwiftUI views or screens from scratch
  • Reviewing a SwiftUI interface that looks generic
  • Creating an iOS prototype or mockup
  • Choosing a visual style or design direction
  • Integrating brand assets into SwiftUI

Example prompts

  • “Design the onboarding screens for a habit tracker in SwiftUI, with three distinct directions.”
  • “Our settings screen looks generic, so review it and suggest fixes.”
  • “Create a brand spec for our app and apply it to the home view.”
  • “Build an iOS prototype of a recipe app that does not look AI-generated.”

Requirements

  • Xcode 16 or newer with the iOS 18 and macOS 15 SDKs
  • SwiftUI, not UIKit unless requested

Workflow steps

9 steps, taken from the step headings in SKILL.md.

  1. Understand Context (5 min)
  2. Recommend 3 Directions
  3. Present Visual Anchors
  4. Let User Choose
  5. Define the Design System (Before Coding)
  6. Build the Layout Hierarchy
  7. Apply Typography Hierarchy
  8. Add the Signature Detail
  9. Review Against Checklist

What it can do on your machine

Read from SKILL.md and the folder at commit 2c82638. It shows what the files ask for, not the result of running them.

  • Tool permissions

    Pre-approves nothing: there is no allowed-tools line, so your agent's usual permission prompts apply.

    From allowed-tools in the SKILL.md frontmatter.

  • Runs code

    No scripts in the folder and no shell commands in SKILL.md (its code samples are swift).

    From the folder's file list and the shell code blocks in SKILL.md.

  • Network

    No URLs in SKILL.md.

    From URLs in SKILL.md, links to its own repository left out.

  • Credentials

    Names no API keys, tokens, secrets or passwords.

    From names ending in _API_KEY, _TOKEN, _SECRET, _KEY or _PASSWORD in SKILL.md.

Context cost

SwiftUI Design Skill loads about 2.8k tokens when it runs, and up to ~12k if it reads all its reference files. Until then it costs about 109 tokens; SKILL.md has 1,167 words of instructions outside code blocks.

Always · name and description, kept in context so the agent knows when to use it
~109
When it runs · the whole SKILL.md, loaded when a task matches
~2.8k
With references · SKILL.md plus every file in references/, read only if the agent opens them
~12k

Estimates: characters ÷ 4, the usual rule of thumb; real counts depend on the model's tokenizer. Scripts and assets cost tokens only if the agent reads them.

Safety

Auto-check passed

The automated check found no risky patterns in SKILL.md.

Automated static check — not a guarantee. Review scripts before installing. It scans the text of SKILL.md for risky patterns (piping downloads into a shell, reading credential files, hidden Unicode, destructive commands); files beside SKILL.md are not scanned.

SKILL.md

The full file from Wholiver/swiftui-design-skill at commit 2c82638, republished under its MIT licence (© Wholiver). 1,167 words, ~2,794 tokens.

Download SKILL.mdSave it as .claude/skills/swiftui-design-skill/SKILL.md (or your agent's skills folder). This skill also uses 12 other files; get the full folder from GitHub.
name
swiftui-design-skill
description
SwiftUI frontend visual design skill. Creates beautiful, distinctive iOS/macOS interfaces that avoid generic AI slop patterns. Covers design direction, layout systems, typography, color, spacing, brand integration, and design review. Use when designing new SwiftUI views, reviewing UI quality, creating iOS prototypes, choosing visual styles, improving app aesthetics, or when the UI looks generic or AI-generated.
license
MIT
metadata.author
wholiver
metadata.version
1.0.0

SwiftUI Design Skill

TL;DR: Design SwiftUI apps that look intentionally crafted, not AI-generated. Follow the 6 Anti-Slop Rules, use the Design Direction workflow when requirements are vague, and always pass the 5-Dimension Review before shipping.

When to Use

  • Designing new SwiftUI views or screens from scratch
  • Reviewing or improving existing UI quality
  • Creating iOS app prototypes or mockups
  • Choosing a visual style or design direction
  • Integrating brand assets into SwiftUI
  • When someone says "the UI looks generic" or "make it look better"
  • When building a new feature that needs visual design

When NOT to Use

  • Pure backend / API work with no UI
  • Fixing SwiftUI compilation errors (use swiftui-expert-skill instead)
  • Performance optimization of existing views (use swiftui-expert-skill)
  • Accessibility compliance only (use swiftui-expert-skill's accessibility topic)

Prerequisites

  • Xcode 16+ with iOS 18+ / macOS 15+ SDK
  • SwiftUI framework (not UIKit unless explicitly requested)
  • Familiarity with SwiftUI view hierarchy and modifiers

Core Design Philosophy

These 6 principles guide every design decision. They are distilled from real-world design practice and anti-patterns observed in AI-generated UI.

Principle 1: Start From Context, Never Blank

Before designing any screen, ask:

  • Is there an existing design system, UI kit, or Figma file?
  • Is there an existing codebase with established visual language?
  • Are there brand guidelines or a style guide?

If no context exists, create a brand-spec.md first (see Brand Asset Protocol below).

Principle 2: Junior Designer Mode — Hypothesize Early, Iterate Fast

Don't wait for the "perfect" design. Show hypotheses with placeholders early:

  • Gray boxes for images are better than bad AI-generated SVGs
  • System fonts with good spacing > custom fonts with bad spacing
  • A rough but honest layout > a polished but generic one
Principle 3: Offer Variations, Not Finals

Always present 2-3 distinct design directions, not one "final answer." Each variation should:

  • Represent a different design philosophy (e.g., editorial, functional, expressive)
  • Have a clear rationale for why it works
  • Be visually distinct — not just color swaps
Principle 4: Placeholder > Bad Implementation

If you cannot source a real asset (icon, image, illustration):

  • Use a clean gray placeholder with clear labeling
  • Never use AI-generated SVG clipart
  • Never use emoji as icon substitutes in production UI
  • For icons, prefer SF Symbols (Apple's built-in icon library)
Principle 5: System First, Don't Fill

Every element must earn its place. Before adding any UI element, ask:

  • Does this serve the user's goal?
  • Can this be combined with something else?
  • What happens if I remove it?

Whitespace is a feature, not emptiness.

Principle 6: Anti-AI-Slop

These patterns are banned in production UI. See references/anti-ai-slop.md for detailed rules.

Banned visual patterns:

  • ❌ Purple-to-blue gradient backgrounds
  • ❌ Emoji as functional icons
  • ❌ Rounded cards with left-border accent color
  • ❌ Generic "hero section" with centered text over gradient
  • ❌ Inter/Roboto as display fonts on Apple platforms
  • ❌ Neon-on-dark "cyber" aesthetic (#0D1117 base)
  • ❌ Symmetric 3-column feature grids
  • ❌ AI-drawn SVG illustrations or CSS silhouettes

What to do instead:

  • ✅ Single warm accent color on neutral background
  • ✅ SF Symbols for icons, or custom icon set
  • ✅ Serif display font (e.g., New York, Georgia) for headings
  • ✅ Restrained info density — let content breathe
  • ✅ One signature detail at 120% effort per screen
  • ✅ Real photography or clean placeholders

Brand Asset Protocol

When building UI for a specific brand, follow this 5-step hard flow:

  1. Ask — Request brand guidelines, logo files, color palette, typography
  2. Search — If not provided, search the web for "[brand name] brand guidelines"
  3. Download — Get actual asset files (PNG/SVG logos, font files)
  4. Verify — Confirm colors match official sources (check hex values)
  5. Write brand-spec.md — Document: primary/secondary colors, fonts, logo usage rules, spacing tokens

Quality threshold: 5 real brand colors, 10 verified design tokens, 2 font families, 8pt spacing grid.

If no brand exists, create a brand-spec.md with:

  • 1 primary accent color (warm, not purple-blue gradient)
  • 1 neutral palette (grays with warm undertone)
  • 1 display font + 1 body font (SF Pro default is fine)
  • 8pt spacing grid

Design Direction Workflow

When requirements are vague or the user asks "what style should we use?", follow this workflow:

Phase 1: Understand Context (5 min)
  1. Ask: What is the app? Who is the user? What platform (iOS/macOS/watchOS)?
  2. Ask: Any reference apps or websites they admire?
  3. Check: Existing design system or brand assets?
Show full SKILL.md (477 more words)Show less
Phase 2: Recommend 3 Directions

Present 3 distinct design philosophies from different schools:

SchoolExample Directions
InformationClean data-first, chart-heavy, Bloomberg-style
EditorialMagazine layout, serif typography, generous whitespace
ExpressiveBold color, asymmetric layout, motion-forward
FunctionalDense utility, monospace accents, minimal decoration
Warm MinimalSoft neutrals, rounded shapes, subtle texture
Phase 3: Present Visual Anchors

For each direction, describe:

  • Color palette (3-5 colors with hex values)
  • Typography pairing (display + body)
  • Layout density (comfortable / compact / spacious)
  • Signature detail (one standout element per screen)
Phase 4: Let User Choose

Present options clearly. After choice, lock in the design system.


SwiftUI Design Workflow

Step 1: Define the Design System (Before Coding)

Create or confirm these design tokens:

swift
// Requires: references/swift-extensions.md (Color(hex:) extension)
// DesignTokens.swift
enum DesignTokens {
    // Colors
    static let accent = Color(hex: "E85D3A")      // Warm coral
    static let background = Color(hex: "FAFAF8")   // Warm white
    static let textPrimary = Color(hex: "1A1A1A")   // Near-black
    static let textSecondary = Color(hex: "6B6B6B") // Muted gray
    
    // Typography
    static let displayFont = "New York"  // Serif for headings
    static let bodyFont = "SF Pro"       // System default
    
    // Spacing (8pt grid)
    static let spaceXS: CGFloat = 4
    static let spaceS: CGFloat = 8
    static let spaceM: CGFloat = 16
    static let spaceL: CGFloat = 24
    static let spaceXL: CGFloat = 32
    static let spaceXXL: CGFloat = 48
    
    // Corner radius
    static let radiusS: CGFloat = 8
    static let radiusM: CGFloat = 12
    static let radiusL: CGFloat = 16
}
Step 2: Build the Layout Hierarchy

Follow the layout patterns in references/layout-patterns.md:

  • Start with the primary content container
  • Use VStack for vertical flow, HStack for horizontal
  • Use LazyVGrid / LazyHGrid for grid layouts
  • Use ScrollView with .scrollTargetBehavior(.paging) for paged content
  • Avoid GeometryReader — prefer containerRelativeFrame (iOS 17+)
Step 3: Apply Typography Hierarchy

Follow references/typography-color.md:

  • Display (screen titles): Serif font, 28-34pt, bold
  • Heading (section titles): Sans-serif, 20-24pt, semibold
  • Body (content text): Sans-serif, 15-17pt, regular
  • Caption (labels, metadata): Sans-serif, 12-13pt, secondary color
Step 4: Add the Signature Detail

Each screen should have ONE element that goes 120% — a custom animation, a unique layout choice, a distinctive color moment. This is what makes the design memorable.

Examples:

  • A custom pull-to-refresh with brand-colored animation
  • A card that expands with a spring animation on tap
  • A header that uses the brand's display font at an oversized scale
  • A subtle parallax effect on scroll
Step 5: Review Against Checklist

Before shipping, run the 5-Dimension Review (see references/design-review.md).


Common Mistakes to Avoid

MistakeFix
Using UIColor or NSColorUse Color (SwiftUI native)
UIScreen.main.bounds for sizingUse containerRelativeFrame or geometry-based modifiers
Default blue tint everywhereDefine a custom accent color in design tokens
No spacing system (random padding values)Use 8pt grid: 4, 8, 16, 24, 32, 48
Emoji as iconsUse SF Symbols or custom icon assets
Purple-blue gradient backgroundUse solid warm neutrals
All content in one giant VStackBreak into semantic sections with clear hierarchy
No visual hierarchy (everything same size)Use 3+ type scales (display, heading, body, caption)
Ignoring dark modeDefine semantic colors that adapt to appearance
Generic "Welcome!" hero sectionShow actual content immediately

Quick Reference: Topic Router

TopicReference File
Anti-AI-Slop Rules (detail)references/anti-ai-slop.md
Layout Patterns & Gridsreferences/layout-patterns.md
Typography & Color Systemsreferences/typography-color.md
5-Dimension Design Reviewreferences/design-review.md
Swift Extensions (required)references/swift-extensions.md
Brand Spec Templatetemplates/brand-spec.md

Validation Checklist

Before considering any SwiftUI design complete, verify:

  • Design tokens defined (colors, fonts, spacing)
  • No banned AI-slop patterns present
  • Typography has clear hierarchy (3+ scales)
  • Spacing follows 8pt grid
  • Dark mode colors defined and tested
  • One signature detail per screen
  • SF Symbols used for icons (not emoji)
  • Minimum 44×44pt tap targets
  • No GeometryReader or UIScreen.main.bounds
  • 5-Dimension Review score ≥ 7/10 on all dimensions

© Wholiver, MIT. Rendered from Markdown: HTML in the file is shown as text, images as links, and headings moved down two levels. Raw file

Files

SKILL.md and 12 other files (references) in the repository root of Wholiver/swiftui-design-skill.

  • SKILL.md
  • .gitignore
  • LICENSE
  • README-zh.md
  • README.md
  • RELEASE-v1.0.0.md
  • metadata.json
  • references/anti-ai-slop.md
  • references/design-review.md
  • references/layout-patterns.md
  • references/swift-extensions.md
  • references/typography-color.md
  • templates/brand-spec.md

Open the folder on GitHubat commit 2c82638

Compare with similar skills

SwiftUI Design Skill next to the 5 skills that share the most tags, products or categories with it. Stars are the repository's; “used in” counts other GitHub owners with a copy.

SwiftUI Design Skill compared with similar skills
SkillStarsUsed inTokensAuto-checkLicenceRepo updated
SwiftUI Design Skill this skillWholiver/swiftui-design-skill204—~2.8kAutomated safety check: PassMIT
FlowdeckSwiftedMind/Tessera116—~11kAutomated safety check: PassMIT
Bootstrap iOSRayFernando1337/rayfernando-skills130—~1.1kAutomated safety check: PassApache-2.0
Xcstrings ManagerEslzzyl/Pixiv-SwiftUI111—~482Automated safety check: PassAGPL-3.0
Swiftui Animation MatchRayFernando1337/rayfernando-skills130—~1.3kAutomated safety check: PassApache-2.0
Developing iOS Appsdaymade/claude-code-skills1.4k—~3.2kAutomated safety check: PassMIT

Similar skills

  • Flowdeck

    SwiftedMind/Tessera

    FlowDeck is REQUIRED for all Apple platform build/run/test/launch/debug/simulator/device/log/automation tasks.

    116 GitHub stars~11k tokensUpdated 5 mo ago
    MobileAuto-check passed
  • Bootstrap iOS

    RayFernando1337/rayfernando-skills

    Bootstrap agents for iOS, iPadOS, macOS, Swift, SwiftUI, SwiftData/Core Data, Swift Testing, Xcode build/test/debug, Simulator, App Intents, or XcodeBuildMCP work.

    130 GitHub stars~1.1k tokensUpdated 2 mo ago
    MobileAuto-check passed
  • Xcstrings Manager

    Eslzzyl/Pixiv-SwiftUI

    Manage Xcode String Catalog (.xcstrings) localization files through a command-line interface.

    111 GitHub stars~482 tokensUpdated 2 days ago
    MobileAuto-check passed
  • Swiftui Animation Match

    RayFernando1337/rayfernando-skills

    Match UI/UX interaction needs to proven SwiftUI animation patterns from curated open-source catalogs.

    130 GitHub stars~1.3k tokensUpdated 2 mo ago
    MobileAuto-check passed
  • Developing iOS Apps

    daymade/claude-code-skills

    Builds and ships iOS/macOS apps with XcodeGen, SwiftUI and SPM: Xcode build fixes, device deployment, Apple Developer signing/notarization, CI/CD pipelines.

    1.4k GitHub stars~3.2k tokensUpdated today
    MobileAuto-check passed
  • Init Xcode App

    glebis/claude-skills

    Scaffold a standalone SwiftUI app via XcodeGen — pick macOS, iOS, or iOS+watchOS; ships house conventions, a Swift Testing target, swiftformat/swiftlint, optional CloudKit/CI/Release/Push modules…

    391 GitHub stars~860 tokensUpdated 2 days ago
    MobileAuto-check passed

Questions about SwiftUI Design Skill

What does SwiftUI Design Skill do?

Guides the agent to design distinctive SwiftUI interfaces for iOS and macOS, with six anti-generic rules, a design direction workflow and a five-dimension review. This skill steers the agent toward SwiftUI screens that look deliberately designed instead of generic AI output. It rests on six principles, among them starting from context rather than a blank page (an existing design system, codebase or brand guidelines, or a brand-spec file when none exists), showing early hypotheses with placeholders, offering two or three distinct design directions rather than one final answer, and using a clean labeled placeholder in place of AI-generated SVG clipart.

When should I use SwiftUI Design Skill?

SwiftUI Design Skill fits situations like: designing new SwiftUI views or screens from scratch; reviewing a SwiftUI interface that looks generic; creating an iOS prototype or mockup; choosing a visual style or design direction.

How do I install SwiftUI Design Skill in Claude Code?

Run `npx skills add Wholiver/swiftui-design-skill --skill swiftui-design-skill -a claude-code`. Or copy the skill folder (the Wholiver/swiftui-design-skill repository) into .claude/skills/swiftui-design-skill in your project. Claude Code loads it when a task matches its description.

How do I install SwiftUI Design Skill in Codex?

Run `npx skills add Wholiver/swiftui-design-skill --skill swiftui-design-skill -a codex`. Or copy the skill folder (the Wholiver/swiftui-design-skill repository) into .agents/skills/swiftui-design-skill in your project. Codex loads it when a task matches its description.

Can I use SwiftUI Design Skill in Cursor, Gemini CLI or GitHub Copilot?

Cursor, Gemini CLI, GitHub Copilot and OpenCode also load SKILL.md folders. With the skills CLI, run `npx skills add Wholiver/swiftui-design-skill --skill swiftui-design-skill -a cursor` (or -a gemini-cli, github-copilot or opencode for the others). To copy it by hand, put the folder in .cursor/skills/swiftui-design-skill, .gemini/skills/swiftui-design-skill, .github/skills/swiftui-design-skill and .opencode/skills/swiftui-design-skill in your project.

What does SwiftUI Design Skill need to run?

SKILL.md names no scripts, command-line tools or credentials: SwiftUI Design Skill is instructions for the agent only. Our summary lists: Xcode 16 or newer with the iOS 18 and macOS 15 SDKs; SwiftUI, not UIKit unless requested.

Does SwiftUI Design Skill access the network?

SKILL.md contains no URLs. Any network use would come from the scripts or tools the agent runs. This is read from the text; nothing was executed.

Is SwiftUI Design Skill safe to install?

Our automated static check of SKILL.md found no risky patterns, such as piping downloads into a shell, reading credential files or hidden Unicode. It is not a guarantee. Review the folder before installing.

What licence does SwiftUI Design Skill use?

SwiftUI Design Skill is published under the MIT licence (declared in SKILL.md). It allows redistribution, so the full SKILL.md is shown on this page.

How many tokens does SwiftUI Design Skill use?

About 2.8k tokens (SKILL.md is roughly 11k characters). Agents keep only the skill's name and description in context until a task matches; then they load SKILL.md in full. Its references folder adds about 9.3k tokens, read only when the agent opens those files.

What are the alternatives to SwiftUI Design Skill?

Skills that share tags, products or a category with SwiftUI Design Skill: Flowdeck (SwiftedMind/Tessera, 116 stars), Bootstrap iOS (RayFernando1337/rayfernando-skills, 130 stars), Xcstrings Manager (Eslzzyl/Pixiv-SwiftUI, 111 stars) and Swiftui Animation Match (RayFernando1337/rayfernando-skills, 130 stars). The comparison table on this page puts their stars, adoption, token cost, safety result and licence side by side.

Who maintains SwiftUI Design Skill?

Wholiver (a GitHub user) maintains it in Wholiver/swiftui-design-skill, which has 204 GitHub stars. The repository was last updated on May 1, 2026.

Source: Wholiver/swiftui-design-skill on GitHub. Facts on this page come from the repository at the commit we read; the author's words are quoted as theirs.